このチャプターのゴール

Webhookによる外部API連携の方法が理解できている

※本チャプターでは、一部エンジニアリングの知識が必要になります。

Webhookとは？

Webhookとは、サービス(アプリケーション)の何らかのアクションを他のアプリケーションへリアルタイムに通知する仕組みのことです。特定のイベントが発生した際、指定したURLにリクエストを送信します。
この仕組みにより、miiboと様々なサービスやAPIを連携させることが可能になります。

miibo webhooksを使うことにより、簡単に下記のようなインテグレーションを実現できます。

例

miiboのエージェントが応答を返したタイミングで、Slackに通知を送る
miiboのエージェントが予定を聞いたら、カレンダーに予定を追加する
miiboのエージェントが特定のお問い合わせを受けたら、Slackに通知する
miiboのエージェントにツイートを行わせる
miiboのエージェントに対して外部のAPIから専門知識を与え、応答をカスタマイズする

MakeやZapierなどのIPaaSサービスと組み合わせると、様々なサービスと手軽に連携可能です。

Make
https://www.make.com/en

Zapier
https://zapier.com/

利用例:
https://note.com/makunugi/n/n198fd6c8bcb4
Notionに自動サマリーを記述するAIメンター
https://www.youtube.com/watch?v=3pD7jXqHV30

Webhook発火のタイミング

1. ユーザーがエージェントに話しかけた

ユーザーがエージェントに話しかけた際に発火します。

設定方法

トリガーの種類で「ユーザーが発話をした」を選択します。

トリガーの条件は下記の３つから選択可能です。

何らかの発話があったら
下記の値のいずれかと一致したら
下記の値のいずれかが含まれたら

すべての発話をトリガーとしたい場合は１を、発話の内容を絞りたい場合は2か3を利用してください。

ペイロードにJSONを指定すると、リクエスト時のBodyに任意のパラメータを追加できます。

2. エージェントが応答をした

エージェントが応答をした際に発火します。

設定方法

トリガーの種類で「エージェントが応答を返した」を選択します。

トリガーの条件は下記の３つから選択可能です。

何らかの発話があったら
下記の値のいずれかと一致したら
下記の値のいずれかが含まれたら

すべての発話をトリガーとしたい場合は１を、発話の内容を絞りたい場合は2か3を利用してください。

ペイロードにJSONを指定すると、リクエスト時のBodyに任意のパラメータを追加できます。

3. function callingが発火した

GPT-3.5、GPT-4、GPT-4o、GPT-4o-miniで利用が可能な、「Function Calling」という仕組みで発火するWebhookです。

「カレンダーに日程を登録したい会話がなされた」
「ユーザーから要望があった」

といった特定の会話内容を検知し、トリガーとすることができます。

設定方法

下記の３つが必須です。

Functionの名前

Functionの名前を指定してください。発火時の「functionName」というパラメータになります。

Functionの詳細

Functionの内容を記述します。どういった会話の内容をトリガーとしたいのか、詳細に記述してください。下記は、ユーザーからのお問い合わせを検知しています。

Function Callingのパラメータ

OpenAI APIの定めるFunction CallingのパラメーターのJSONを指定します。

OpenAI API公式のDoc

パラメータの例

    {
        "type": "object",
        "properties": {
            "question": {
                "type": "string",
                "description": "お問い合わせの質問を入力してください。"
            },
            "email": {
                "type": "string",
                "description": "ユーザーのメールアドレスです。"
            }
        },
        "required": [
            "question","email"
        ]
    }

type
「object」を指定してください。
properties:
必ず指定してください。この配下に複数のオブジェクトを指定できます。

                "question": {
                    "type": "string",
                    "description": "お問い合わせの質問を入力してください。"
                },

上記のquestionは任意のパラメータです。
任意のパラメータを設定し、descriptionに説明を記述しましょう。

required
requiredには、発火時に取得が必須なパラメータを指定します。

"required": [
    "question","email"
]

OpenAI APIでFunction Callingを利用する際に指定するJSONの内、「parameters」配下のオブジェクトを記載します。parameters　は含めないでください。

Function Callingで取得できるパラメータは、下記のようにWebhookのURLやペイロードに挿入できます。

(例) 「area」というパラメータをFunction Callingで取得した場合

@{area} という文字列を利用することで、パラメータで文字列をリプレイスすることができます。

URLへの挿入

https://xxxxx/com?area=@{area}

ペイロードへの挿入

{
  "area": "@{area}"
}

Webhookのリクエスト仕様

Webhookが発火すると、下記の仕様のリクエストが送信されます。

URL

Webhookのリクエスト先となるURLを指定してください。

※@{query} という記法を挿入することで、miiboが自動生成した検索クエリーを代入できます。

ex: https://xxxxx.com/api?query=@{query}

メソッド

Webhookの設定で指定したメソッド

(POST, GET, PUT)

ヘッダー

下記は自動で付与されるHeaderです。

KEY	内容
X-HMAC	Hash Based Message Authentication Codeです。通信が正規のものかどうかを検証する際に利用できます。独自のAPIと連携をする場合は、この文字列を利用して通信の検証を行ってください。(https://www.notion.so/webhook-4e57a895cb7d448980744f900eada27a?pvs=21)

Webhookの設定で指定したヘッダー情報も合わせて付与されます。

リクエストボディ

リクエストはJson形式のBodyが付与され、送信される。

※ GETメソッドを指定した場合は付与されません。

自動で送信されるパラメータ

パラメータ	型	値の例	補足
webhookType	String	「user_utterance」 or 「agent_response」 or 「function_calling」	user_utterance
state	Object(String:String)	{"username":"masashi"}	miiboのステートという機能によって記録されたKey, Valueのmapです。https://zenn.dev/makunugi/books/f3d9eb62b6d133/viewer/a1c5e8
userId	String	ユーザーを一意に識別する識別子
history	String	直近の会話の履歴

下記は設定に応じて送信されるパラメータです。

Webhook設定のペイロードに設定したJSON
Functaion Callingで取得されたJSON

「自動で送信されるパラメータ」とマージされたJSONとしてリクエストに利用されます。

※マージされる際、キー名が同じ項目は、「設定に応じて送信されるパラメータ」に上書きされます。
※@{query} という記法を挿入することで、miiboが自動生成した検索クエリーを代入できます。

サンプルリクエスト

{
    "email": "hoge@miibo.jp",
    "functionName": "contact",
    "history": "user: 不具合を報告したいです。 \nai: もちろんです、正雄さん！不具合の内容を詳しく教えていただけますか？それによって、どのように対応するべきかが変わりますので。\nuser: miiboのログ画面でスクロールをすると固まります",
    "question": "miiboのログ画面でスクロールをすると固まる不具合が発生しています",
    "state": {
        "username": "正雄"
    },
    "userId": "xxxxxxxxxxxx",
    "utterance": "miiboのログ画面でスクロールをすると固まります",
    "webhookType": "function_calling"
}

※リトライ処理は行われません。リクエストに対するレスポンスのタイムアウト時間は10sですが、AIの応答が遅くなることを防止するため、なるべく早いレスポンス速度であることが重要です。

Webhookのリクエストに対する応答を利用する

Webhookの行うリクエストに対して外部APIがレスポンスを返す場合、そのレスポンスをGPTの応答生成時にプロンプトへ付与することができます。

この機能を利用することにより、外部のAPIから取得した情報をもとにしたAIの応答を行うことができます。(RAGとしての利用)

※ 「エージェントが応答をした」のトリガー利用時は利用できません。

Webhookのリクエストに対する応答でステートをアップデートする

Webhookのリクエストに対して、下記のようなレスポンスパラメータを含めることにより、ステートを更新できます。

{
  "state":{
        "recommended_item": "item1"
  }
}

ステートを利用する

下記の項目では、ステートや一部の特殊記号を利用することができます。

WebhookのURL
Webhookのペイロード(JSON)
Webhookをプロンプトで利用する場合のプレフィックス

ペイロード(JSON)の例

{
  "趣味":"#{hobby}"
}

プロンプトプレフィックスの例

下記は関連すルAPIから得られたレスポンスです。このレスポンスを参考に応答をしてください。
また、ユーザーの下記の情報を踏まえて応答を行なってください。

趣味: #{hobby}
困りごと: #{trouble}

その他の変数を利用する

下記の項目では、特別な変数を利用することができます。

WebhookのURL
Webhookのペイロード(JSON)
Webhookをプロンプトで利用する場合のプレフィックス

利用可能な変数。

変数	説明
@{query}	生成された検索クエリーで置き換えます
@{function_callingで取得した値}	Function Callingで取得したパラメータの値で置き換えます。	例: @{area}
@{utterance}	ユーザーの発話で置き換えます。
@{thirdPartyToken}	APIのリクエストやWebチャット画面に渡されたサードパーティートークンで置き換えます。	例: `{ "token" : "@{thirdPartyToken}"}`
@{sessionId}	現在のセッションのIDを格納します。ただし、会話の開始時の発話に対しては空欄が返ります。また、URLへの埋め込みはできません。
@{history}	会話の直近の履歴を埋め込むことができます。デフォルトのhistoryパラメータではなく、historyを任意の箇所に埋め込みたい時に利用します。	`"utterance" : "下記はユーザーの会話の履歴です。\n@{history}"``` `