Messaging APIに公開 – DialogPlay - TISI株式会社

本記事では、Messaging APIを利用するチャットボットの公開手順と簡単な利用手順について説明します。

なお、Messaging APIはMessaging APIオプションプランに加入することでご利用可能です。
オプションプランの詳細やお申し込み方法などについては、弊社営業担当、もしくは DialogPlay問合せ窓口 までお問い合わせください。

Messaging APIの利用方法は、大きく以下の流れとなります。

1. アプリケーションの公開
2. 認証を行い、access tokenを取得する
3. チャットルームへ入室する
4. 会話履歴を取得する
5. ユーザー発言を送信する

以下のトピックで、各詳細について説明します。

1. アプリケーションの公開

DialogPlay設定画面 上でチャットボットの作成を行い、アプリケーションを公開します。

項目	設定値
チャットボット公開先	Messaging API v1
メッセージフォーマット	標準
音声対話において冗長な処理を省略する	任意（チェックすると意図推定時のフローや、選択肢のページングが省略されます）

公開後に表示される『ClientID』、『Client Secret』を今後の認証で使用します。

2. 認証

POST /token を使用して認証を行い、access tokenを取得します。
以下のリクエストを送信してください。

Method: POST
Path: https://api.dialogplay.jp/api/v1/token
Request body:

{
  "grant_type": "client_credentials",
  "client_id": "前項で取得したClient ID",
  "client_secret": "前項で取得したClient Secret"
}

以下のレスポンスが返ってきます。

Response body:

{
  "access_token": "認証が必要なAPIで使用するアクセストークン",
  "token_type": "Bearer",
  "expires_in": 1800,
  "refresh_token": "期限切れトークンの更新に使用するリフレッシュトークン"
}

認証が必要なAPIを実行する際はResponse bodyに含まれる access_token を使用します。
有効期限は30分間です。期限切れトークンの更新処理については【備考1. 期限切れトークンの更新】を参照してください。

3. チャットルームへの入室／再入室

POST /channels を使用してチャットルームへ入り、チャットルーム（channel）のuuidを取得します。
以下のリクエストを送信してください。

Method: POST
Path: https://api.dialogplay.jp/api/v1/channels
Request headers:

{
  "Authorization": "Bearer 前項で取得したaccess_token"
}

Request body:

{
  "user_id": "ユーザーを一意に識別するID（メールアドレスなど）"
}

以下のレスポンスが返ってきます。

Response body:

{
  "uuid": "チャットルームを一意に識別するUUID",
  "user_id": "ユーザーを一意に識別するID",
  "stream_url": "WebSocket接続する場合に使用するURL"
}

uuid は、チャットルームを一意に識別するUUIDとなります。このUUDIを利用して、チャットルームの会話履歴の取得、ユーザー発言の送信を行います。

uer_id は、ユーザーを一意に識別するIDとなります。Request bodyでuser_idを省略した場合は、Response bodyにはDialogPlay側で自動的に採番されたuser_idが含まれます。同一のAccessTokenからのリクエストであっても、異なるidが発行され別人として扱われます。

stream_urlは、WebSocketを用いてチャットボットからのメッセージを取得する場合に使用するURLとなります。詳しくは、下記【4. 会話履歴の取得】をご覧ください。

4. 会話履歴の取得

会話履歴を取得する方法には、「REST APIを用いて会話履歴を取得する方法」、「WebSocketを用いてチャットボットからのメッセージを取得する方法」の2つがあります。

WebSocketを用いてチャットボットからのメッセージを取得する方法
WebSocketによりリアルタイムな双方向通信を行えるため、チャットボットからのメッセージを自動的に継続的に取得することができます。
ただし、現仕様ではWebSocketを用いてユーザー発言の送信を行うことはできません。ユーザー発言の送信は、下記【5. ユーザーによる発言】を参考にREST APIにて行ってください。
また、WebSocketプロトコルを利用できるネットワーク環境である必要があること、取得できるメッセージはWebSocket接続後に送られてきたチャットボットからのメッセージのみであるということがデメリットです。（過去の会話履歴や、送信したユーザー発言はレスポンスに含まれません。）
REST APIを用いて会話履歴を取得する方法
上記までのリクエストと同じくHTTPSプロトコルを使用するため利用しやすいことがメリットです。また、レスポンスには過去に行われた会話の履歴も含まれます。
一方で、会話履歴を取得するためには能動的にリクエストを送る必要があることがデメリットです。会話履歴の取得を継続的に行いたい場合には、ポーリングの仕組みなどを実装する必要があります。

業務要件に合わせてどちらかをご利用ください。

WebSocketを用いてチャットボットからのメッセージを取得する方法

WebSocket通信を行うことができるライブラリやクライアントソフトを用いて、上記【3. チャットルームへの入室／再入室】で取得したstream_url に対して接続することで、メッセージの取得を行うことができます。

REST APIを用いて会話履歴を取得する方法

以下のリクエストを送信してください。
なお、取得できるメッセージのフォーマットについては、【メッセージフォーマット（会話履歴の取得）】をご覧ください。

Method: GET
Path: https://api.dialogplay.jp/api/v1/channels/{uuid}/messages
Request headers:

{
  "Authorization": "Bearer 前項で取得したaccess_token"
}

Query string:
since: 指定した時刻(ISO8601形式)より後に発言されたメッセージのみを返します。（※1）
limit: 指定した件数までのメッセージを返します。（※2）

※1: 指定した時刻ちょうどの発言は含まれません。
※2: 件数を超過した場合は、新しいメッセージを優先します。

以下のレスポンスが返ってきます。

Response body:

{
  "format": "dialogplay",
  "messages": [
    {
      "uuid": "58045c04-19bc-44fe-ba36-bd9533f2588e",
      "channel_uuid": "040b6e56-137f-4a4f-9dff-4442582d7cf1",
      "timestamp": "2019-04-04T09:32:35.898833+00:00",
      "sender_platform": "bot",
      "sender_uid": "検証用",
      "sender_name": "検証用",
      "sender_type": "bot",
      "type": "text",
      "content": {
        "text": "チャットボットからの返信テキスト",
        "value": null
      }
    },
    ...
  ]
}

5. ユーザーによる発言

POST /channels/{uuid}/messages を使用して、ユーザーによる発言を行うことができます。
以下のリクエストを送信してください。
なお、リクエストメッセージのフォーマットは、【メッセージフォーマット（ユーザー発言の送信）】をご覧ください。

Method: POST
Path: https://api.dialogplay.jp/api/v1/channels/{uuid}/messages
Request headers:

{
  "Authorization": "Bearer 前項で取得したaccess_token"
}

Request body:

{
  "type": "text",
  "content": {
    "text": "ユーザーが発言する文言"
  }
}

以下のレスポンスが返ってきます。

Response body:


{
  "id": "00112233-4455-6677-8899-ffffffffffff"
}

id は、メッセージのUUIDとなります。

レスポンスにチャットボットの返答は含まれないため、前項【4. 会話履歴の取得】を用いて返答を確認します。

備考1. 期限切れトークンの更新

2番で取得した access_token は30分で期限切れとなります。
期限が切れた場合は、同じく2番で取得した refresh_token を使用して、 access_token の更新を行ってください。
以下のリクエストを送信してください。

Method: POST
Path: https://api.dialogplay.jp/api/v1/token
Request headers:

{
  "Authorization": "Bearer 期限切れになったaccess_token"
}

Request body:

{
  "grant_type": "refresh_token",
  "refresh_token": "2番で取得したrefresh_token"
}