外部のAPIと連携するには?
このチャプターのゴール
DH-Conversationから外部のAPIを利用してエージェントに応答をさせることができる様になります。
外部のAPIと連携する方法
DH-Conversationでは外部にある様々なWeb APIを利用し、DH-Conversationで作成したエージェントと連携させることができます。エージェントの応答時に、外部のAPIにDH-Conversationから必要な情報を渡し、適切なレスポンスを受け取ることで外部のAPIを介した応答を行います。
1. API一覧画面を開く
API一覧画面
2. APIを追加する
「APIを追加する」というボタンをクリックします。
項目名 | 説明 |
API名 | APIの名前を入力します。DH-Conversationの管理画面で表示されるAPIの名前です。 |
APIのラベル | APIを一意に定めるラベルです。このラベルをDH-Conversationの会話コンテンツの回答に仕込むことで、APIと連携できます。
${ラベル名} DH-Conversationのエージェントが返す応答に、上記の記法でラベル名を埋め込むと、埋め込まれた応答がエージェントから返される際に登録されたAPIがコールされます。 |
URL | のURLを入力します。「https://」から入力をしてください。 |
ヘッダー | APIのリクエスト時に送信するヘッダー情報を登録できます。入力は任意です。 |
パラメータ | APIリクエスト時にBodyに付与するJSONです。JSON形式で入力をしてください。入力は任意です。 |
3. DH-ConversationからコールされるAPIを作成する
DH-Conversationからリクエストを送るAPIを用意しましょう。
DH-ConversationのAPIリクエスト仕様
APIコール時に発生するリクエストは下記の仕様です。
Method
POST
Headers
Content-Type: application/json
このHeaderに加え、DH-Conversationで設定したヘッダーを付与します。
リクエストボディ
DH-Conversationから外部APIに向けて下記のリクエストボディが付与されたリクエストが送られます。形式はJsonです。
Key | 型 | 説明 |
utterance | String | ユーザからの発話 |
options | String配列 | 発火した応答が持つクイックリプライ |
userId | String | ユーザを一意に特定する識別子 |
userState | オブジェクト | ユーザのステート情報 |
extensions | オブジェクト | 発火した応答が持つExtensions |
parameters | オブジェクト | APIに設定されたJSONパラメータ |
userState
DH-Conversationから外部APIに向けて送られるリクエストには、会話をしているユーザのステート情報が格納されます。
{ "username": "太郎", "purpose": "雑談" }
このパラメータを利用することで、DH-Conversation上でエージェントと会話しながら取得したステートを利用できます。
DH-Conversationに返すレスポンス
DH-Conversationから呼び出された外部APIは、DH-Conversation側に対して指定された形式のレスポンスを返す必要があります。
レスポンスは下記のJSONを返します。
Key | 型 | 説明 |
utterance | String | エージェントに応答させたい文言 |
options | String配列 | エージェントの応答時に表示するクイックリプライ |
imageUrl | String | エージェントの応答時に表示する画像のURL |
url | String | エージェントの応答時に表示するリンクのURL |
extensions | オブジェクト | エージェントの応答時に付与したいExtension (Jsonフォーマット) |
サンプルレスポンス
{ "utterance": "おすすめの商品はxxxです。ぜひお試しください。", "options": [ "参考になった", "参考にならなかった" ], "imageUrl": "https://xxxxxxx.png", "url": "https://xxxxxxxxxxx", "extensions": null }
外部APIのエラー時の挙動
呼び出されたAPI側でエラーが発生した場合やタイムアウトが発生した場合など、いかなる場合においてDH-Conversation側はAPIリクエストのリトライは行いません。
活用例
独自のAPIとDH-Conversationを連携させることによって、下記のようなことを実現できます。
- ユーザのステートの内容に合わせたレコメンデーション
- 外部のAPIからコンテンツを表示する (天気, 商品, 株価 etc…)
- Webhookとして活用し何らかの処理のトリガーにする (ChatOps)
DH-Conversationと他サービスを連携させるために、この機能をぜひご活用ください。
最終更新日 January 1, 2023