外部のAPIと連携するには?

このチャプターのゴール

DH-Conversationから外部のAPIを利用してエージェントに応答をさせることができる様になります。

外部のAPIと連携する方法

DH-Conversationでは外部にある様々なWeb APIを利用し、DH-Conversationで作成したエージェントと連携させることができます。エージェントの応答時に、外部のAPIにDH-Conversationから必要な情報を渡し、適切なレスポンスを受け取ることで外部のAPIを介した応答を行います。

1. API一覧画面を開く

API一覧画面

2. APIを追加する

「APIを追加する」というボタンをクリックします。

Notion image
項目名
説明
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側に対して指定された形式のレスポンスを返す必要があります。

💡
⚠︎APIがリクエストされてから5秒で強制的にタイムアウトになります。5秒以内に呼び出されたAPI側でステータス200のレスポンスを返すようにしてください。×警告を閉じる

レスポンスは下記の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