Message Bot API Overview

    Message Bot API

    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.

    Message Bot

    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.

    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:

    1. Register message bot information using the registerBot API.
    2. Get the registered bot information using the getBotList API.
    3. Register a domain using the registerBotDomain API.
    4. Send a message using the sendMessage API.
    5. 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

    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.

    Send Messages

    A message bot can send messages to a specific user.

    Receive Messages

    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:

    Status Description
    Developing In this state, you should add a domain by using the registerBotDomain API to use a message bot in the domain.
    Private In this state, you can send messages to each domain by using the sendMessage API.
    Public In this state, a message bot is shown on the client's bot list and a user can directly invite and use it.

    As a message bot's status changes, the following service notifications are sent.

    Service notification type Status Recipient
    Convert into Public ● updateBotDomain API (Private -> Public) ● Members
    Convert into Private ● updateBotDomain API (Public -> Private)
    ● removeBot API (delete from Public)
    ● Members
    Delete bot ● removeBot API (delete from Public)
    ● removeBot API (delete from Private)
    ● Admin
    ● Sub Admins
    ● IT Managers

    A message bot once deleted cannot be recovered.

    The following figure shows the transition of each state with APIs.

    그림 2 메시지 Bot 상태의 흐름

    Figure 2 Transition of message bot status

    Prerequisite

    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

    Supported Environment

    LINE WORKS supports the following environment:

    • Live environment: https://apis.worksmobile.com

    Request Common

    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

    It returns a code and message in the following common JSON format when an API call is made.

    Property Type Required Description
    code number Y ● 200: Success
    ● 4xx: Client request errors
      ● 400: Invalid parameters
      ● 401: Unauthorized IP address
      ● 402: Authentication failed.
      ● 404: API not found.
    ● 5xx: Unexpected errors and server internal errors
      ● 500: Backend server error
      ● 502: Failed to integrate with server.
      ● 503: Service unavailable
    message string Y Description about the code

    An example is shown below.

    {"code ":200, "message":"OK"}
    

    Code values other than "200" mean an error, and you can see the message for details.