Message Bot API Overview
The Message Bot API (hereinafter, "API") enables the client to interact with individual users, by using a message bot account. The client can send conversational messages to users from its message receiving server, through the LINE WORKS API server at any time, and can automatically reply to the messages that users send on the chat room.
The API provides the following features:
- Register and Get Message Bots: Registers message bots to be used for the client, updates and gets registered message bots.
- Send Messages: Sends messages to individual users through the client's message bot server.
- Receive Messages: Makes conversation with users invited to the client's message bot, on their chat room.
Using a message bot, the client can directly send messages to users or interact with them. For example, if there is an important notice, the client can send it to users directly or can communicate with them by building a system that automatically replies to specific sentences they typed.
- You can register up to 100 bots. (Note that Free subscribers can only register up to 10 bots.)
Message Bot API
With the API, the client can register, update and get a message bot, and can also send messages to users or communicate with them.
Generally a message bot is registered and sends a message in the following steps:
- Register message bot information using the “Register a Message Bot” API.
- Register a domain using the “Register a Message Bot Domain” API.
- Send a message using the “Send Messages” API.
- If necessary, register a callback URL in the bot to communicate with users.
The following figure shows the flow of using the API.
[Figure 1 Message Bot Platform API's flow]
Register and Get Message Bots
To use the API, you need to understand the concept of a tenant and domain. A tenant is compared to a corporate group, so to speak, while a domain is a subsidiary company. Multiple domains can belong to one tenant.
LINE WORKS provides an interface that lets a user register a message bot and get registered message bots. Once a message bot is registered, it is registered only in the tenant that the user belongs to. You should register its domain if you want to use it in a specified domain.
After registering a message bot and adding domains for it, you can send and receive messages through the message bot.
Makes a message bot send messages to a specific user.
LINE WORKS provides an interface for communication between message bots and users. After receiving messages sent from a user, the message bot delivers them to the client's message receiving server. You need an API ID to verify the check value in the X-WORKS-Signature header, which is used to check if the messages sent from the message server are falsified.
Message Bot Status
The status values of a message bot are described below:
|Preparing||A bot has been registered. To use it in each domain,
you should register a domain using the “Register a Message Bot Domain” API.
|In service||A bot has been added to each domain. If the permission is ON,
you can send messages to each domain using the “Send Messages” API.
|> Permission ON||Users can communicate with the bot.|
|>> Public||The bot is shown on the contact list.|
|>> Private||The bot is not shown on the contact list.|
|> Permission OFF||Users cannot communicate with the bot.|
As a message bot's status changes, the following service notifications are sent.
|Service notification type||Status||Recipient|
|Add to contact list||￮ Permission ON & Public||Members|
|Remove from contact list||￮ Permission ON & Private
￮ Permission OFF
￮ When the domain of the bot with permission ON is removed.
￮ When the scope of domains for the bot with permission ON is limited
￮ When the bot with permission ON is deleted.
|Remove domain of bot in service||￮ When the bot in service is deleted.
￮ When the scope of domains for the bot in service is limited.
|Enable "Invitation to team/group or 1:N chat room available" of bot in service||￮ When "Invitation to team/group or 1:N chat room available" is enabled.||Admins|
|Disable "Invitation to team/group or 1:N chat room available" of bot in service||￮ When "Invitation to team/group or 1:N chat room available" is disabled.||Admins|
Admins in the table refer to the Admin, Sub Admins and IT Admins.
When "Invitation to team/group or 1:N chat room available" is enabled, all members in a domain are allowed to use the bot.
A message bot once deleted cannot be recovered.
The following figure shows the transition of each state with APIs.
[Figure 2 Transition of message bot status]
To use the API, you need an API ID that is used in the API's URL. For how to get your API ID, see API Common Guide.
API Common Information
LINE WORKS supports the following environment:
- Live environment: https://apis.worksmobile.com
Request - Common Information
The HTTP content type, including both the header and the body, used to pass parameters is application/json. For types of parameter values, see each API description.
Response - Common Information
If the API call is successful, it returns HTTP status 200 with response data, which is described in each API description.