トーク Bot API の概要

    トーク Bot API を利用すると、トーク Bot アカウントからメンバーにメッセージを送受信できます。例えば、自社で用意したメッセージ送受信サーバーとメンバー間で対話型コミュニケーションを行なったり、メンバーが送信したトークに対して自動に返信することも可能です。

    トーク Bot API は、以下のようにトーク Bot の登録と照会、メッセージ送受信機能を提供します。

    • トーク Bot の登録: 自社のトーク Bot を登録、修正、照会します。
    • メッセージ送信: 自社のメッセージ送信サーバーからトーク Bot を通じてメンバーにメッセージを送信します。
    • メッセージ受信: メンバーがトーク Bot に返信すると、設定したメッセージ受信サーバーにメッセージを転送します。

    参考

    • Bot は最大 300 個(フリープランは 10 個)まで登録可能。

    トーク Bot

    トーク Bot を利用するとメンバーへのメッセージ送信や対話型コミュニケーションをすることができます。例えば、メンバーへのお知らせなどを行う場合、 Bot からのメッセージとして直接伝えることができます。また、メンバーが送信したメッセージにあわせて自動的に回答をするシステムを作り、対話型コミュニケーションを行うような活用方法も考えられます。

    トーク Bot API

    トーク Bot API を利用するとトーク Bot の登録、修正、照会、およびメンバーとの対話が可能になります。

    トーク Bot の登録とメッセージ送信は、以下のステップで行われます。

    1. registerBot API でトーク Bot 情報をテナントに登録。

    2. registerBotDomain API でトーク Bot を各ドメインに登録。

    3. sendMessage API を利用してメッセージ送信。

    4. 必要な場合、Bot の callback URL にメッセージ受信サーバーを登録してメンバーとのコミュニケーションが可能。

    API の流れを図であらわすと下記のようになります。

    図 1 トーク Bot API の流れ

    図 1 トーク Bot API の流れ

    トーク Bot の登録と照会

    トーク Bot API を利用するには、テナントとドメインの関係について理解しておく必要があります。1つのテナントは 1 つもしくは複数のドメインから構成されます。テナントは企業グループ、ドメインは個別企業をイメージしてください。

    LINE WORKS は各企業が直接トーク Bot を登録し、照会できる API を提供します。トーク Bot はまず最初にテナントに登録されます。登録されたトーク Bot を使用する場合は、あわせて利用ドメインにもトーク Bot の登録を行う必要があります。

    メッセージの送信

    トーク Bot は特定のメンバーにメッセージを送信することができます。

    メッセージの受信

    メンバーとトーク Bot の間でコミュニケーションが可能なインターフェースを提供します。メンバーからトーク Bot にメッセージが送信されると、LINE WORKS のメッセージサーバーを通じて、登録されたメッセージ受信サーバーへポストします。メッセージ受信サーバーに渡した値について改ざんの有無を確認するため、チェック値を X-WORKS-Signature ヘッダーに含めて送信し、API ID をキーとして確認することができます。(API ID 未設定の場合、メッセージはポストされません。)

    トーク Bot の状態

    トーク Bot には以下の 3 つの状態があります。

    • 開発中 (Developing) : テナント登録のみ行なった状態です。ドメイン登録を行うまで、メンバーはトーク Bot を使用できません。
    • 非公開 (Private) : アドレス帳には表示されませんが、Bot からメンバーにメッセージを送信できます。
    • 公開 (Public) : アドレス帳の Bot リストに表示され、メンバーから Bot を探して話しかけることができます。
    状態 説明
    準備中 テナント登録のみ行なった状態です。
    トーク Bot を使用する場合は、registerBotDomain API でトーク Bot のドメインを登録を行う必要があります。
    サービス中 各ドメインに登録された状態です。権限 ON 状態で
    sendMessage API を使って各メンバーにメッセージを送信できます。
    > 権限 ON Bot をトークルームに招待可。
    >> 公開 アドレス帳の Bot リストに表示。
    >> 非公開 アドレス帳の Bot リストに非表示。
    > 権限 OFF Bot をトークルームに招待不可。

    Bot の状態を変更すると、以下のサービス通知が送信されます。

    サービス通知タイプ 状態 送信先
    Bot リストに追加 ● 権限 ON & 公開 メンバー
    Bot リストから削除 ● 権限 ON & 非公開
    ● 権限 OFF
    ● 権限 ON の Bot をドメインから削除
    ● 権限 ON の Bot に対してドメイン利用範囲を限定
    ● 権限 ON の Bot を削除
    メンバー
    公開中の Bot を登録ドメインから削除 ● 公開中の Bot を削除
    ● 公開中の Bot に対してドメインの利用範囲を制限
    管理者
    公開中の Bot に'複数人のトークルームに招待可' を設定 ● '複数人のトークルームに招待可' 設定 管理者
    公開中の Bot から'複数人のトークルームに招待可' 設定を解除 ● '複数人のトークルームに招待可' 解除 管理者

    管理者は、最高管理者、副管理者、IT 管理者を意味します。

    '複数人のトークルームに招待可' に設定されると、公開範囲は全メンバーに固定されます。

    削除された Bot は復元できません。

    図であらわすと下記のようになります。

    ALT
    図 2 トーク Bot の状態遷移

    トーク Bot API 利用前の準備

    トークBot API を利用するには、API ID の発行が必要です。API ID はトーク Bot API の URL に使われます。API ID の発行と使い方については、API 共通ガイドを参照してください。

    API共通情報

    利用環境

    LINE WORKS ではサービス環境のみトーク Bot を利用できます。Sandbox 環境を使ったトーク Bot のテストはできません。

    • サービス環境: https://apis.worksmobile.com

    Request 共通

    HTTP リクエストでパラメータを渡すときは、application/json 方式を基本とします。Header と body すべて application/json 方式を遵守しなければなりません。パラメータの形式は、各 API の説明にて確認してください。

    Response 共通

    API を呼び出すと、以下の共通 JSON 形式で返されます。

    属性 タイプ 必須 説明
    code number Y ● 200: 成功
    ● 400 番台: クライアントリクエストエラー
        ● 400: パラメータ呼び出しエラー
        ● 401: アクセス権限のない IP
        ● 402: 認証失敗
        ● 404: 指定された API が見つからない。
    ● 500 番台: 想定外のエラー/サーバー内部エラー
        ● 500: バックエンドサーバー エラー
        ● 502: サーバー連携エラー
        ● 503: サービス使用不可
    message string Y コードについての詳細メッセージ

    例:

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

    上記の code は、200 を除いてすべてエラーを意味します。message のパラメータでエラー詳細を確認することができます。