Chapter 20

外部のAPIと連携する

maKunugi
maKunugi
2021.12.19に更新

このチャプターのゴール

  • 外部のAPIを利用してエージェントに応答をさせることができる

外部のAPIと連携する方法

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

1. API一覧画面を開く

API一覧画面を開きましょう。

https://mebo-admin.work/admin/apis

2. APIを追加する

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

上記のモーダルでAPIの設定を行います。各設定項目について説明していきます。

API名

APIの名前を入力します。meboの管理画面で表示されるAPIの名前です。

APIのラベル

APIを一意に定めるラベルです。このラベルをmeboの会話コンテンツの回答に仕込むことで、APIと連携できます。

${ラベル名}

meboのエージェントが返す応答に、上記の記法でラベル名を埋め込むと、埋め込まれた応答がエージェントから返される際に登録されたAPIがコールされます。

URL

APIのURLを入力します。「https://」から入力をしてください。

ヘッダー

APIのリクエスト時に送信するヘッダー情報を登録できます。入力は任意です。

パラメータ

APIリクエスト時にBodyに付与するJsonです。Json形式で入力をしてください。入力は任意です。

3. meboからコールされるAPIを作成する

meboからリクエストを送るAPIを用意しましょう。

meboのAPIリクエスト仕様

APIコール時に発生するリクエストは下記の仕様です。

Method

POST

Headers

Content-Type: application/json
このHeaderに加え、meboで設定したヘッダーを付与します。

リクエストボディ

meboから外部APIに向けて下記のリクエストボディが付与されたリクエストが送られます。形式はJsonです。

Key 説明
utterance String ユーザからの発話
options String配列 発火した応答が持つクイックリプライ
userId String ユーザを一意に特定する識別子
userState オブジェクト ユーザのステート情報
extensions オブジェクト 発火した応答が持つExtensions
parameters オブジェクト APIに設定されたJSONパラメータ
userState

meboから外部APIに向けて送られるリクエストには、会話をしているユーザのステート情報が格納されます。

{
	"username": "太郎",
	"purpose": "雑談"
}

このパラメータを利用することで、mebo上でエージェントと会話しながら取得したステートを利用できます。

meboに返すレスポンス

meboから呼び出された外部APIは、mebo側に対して指定された形式のレスポンスを返す必要があります。

レスポンスは下記の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側でエラーが発生した場合やタイムアウトが発生した場合など、いかなる場合においてmebo側はAPIリクエストのリトライは行いません。

活用例

独自のAPIとmeboを連携させることによって、下記のようなことを実現できます。

  • ユーザのステートの内容に合わせたレコメンデーション
  • 外部のAPIからコンテンツを表示する (天気, 商品, 株価 etc...)
  • Webhookとして活用し何らかの処理のトリガーにする (ChatOps)

meboと他サービスを連携させるために、この機能をぜひご活用ください。