Guides
Start typing to search…

API経由で会話させる

※本Chapterは、miiboの提供するAPIの仕組みを利用します。Web API利用に関する知識や、利用をするためのプログラミングスキルを要します。

このチャプターのゴール

  • API経由でmiiboで作成したエージェントを会話ができる

準備するもの

  • 公開済みのエージェント

APIの利用方法

公式リファレンスは下記をご参照ください。
https://miibo.readme.io/reference/%E3%83%81%E3%83%A3%E3%83%83%E3%83%88

API利用のメリット

API経由で会話ができることはすなわち、様々なプロダクトにmiiboのエージェントを組み込めることです。アシスタントAIやカスタマーサポートAI、AIアバターと連動したAIなど、用途は様々です。

下記は、デジタルヒューマン社の提供するAIアバターと組み合わせた事例です。
https://www.youtube.com/watch?v=RCpdwtfr0mM
こちらも本APIを利用して連携しています。

様々なプロダクトに組み込むことができることは、AIの個性を多様に設定できることにも繋がります。

APIの有効化

「外部サービス連携」 -> 「APIを利用して会話やデータの入稿を行う」に移動します。
「APIを有効にする」を押すことで、APIが利用できるようになります。APIを有効にすると、API KEYが発行されます。API KEYを利用することで、割り当てられたプランの会話上限回数までAPIを利用することができます。

※会話の利用上限や現在の利用回数は、「利用状況」のページで確認ができます。
https://miibo.dev/admin/usageStats

※APIは1秒間に１回以上の同時リクエスト送ることはお控えください。その回数を超えてリクエストが飛び続けた場合、一時的にエージェントの会話が利用できなくなる可能性があります。

※この条件は、今後緩和される可能性があります。エンタープライズプランの場合、個別にご相談いただくことも可能です。

APIの仕様

リクエストメソッド

POST

エンドポイント

https://api-mebo.dev/api

リクエストヘッダー

KeyValue
Content-Typeapplication/json

リクエストパラメータ

パラメータ説明型必須
api_keyAPIキーString○
agent_idエージェントIDString○
utteranceユーザの発話String○
uidユーザ識別子String
stateユーザーステートMap
streamストリームの利用Bool
start_utterance会話開始時の発話String
base64_imageBase64エンコードされた画像の文字列(画像認識対応モデル利用時のみ)String
disable_ai_responseAI(LLM)による応答をOFFにするフラグ。(trueの場合はユーザーの発話がAIに対して投げかけられるのみで終了します。)Bool
disable_history会話の履歴を用いて応答することをBool
third_party_token外部のトークンを送ることができます。WebhookのURLやペイロード、Function Callingのパラメータで、「@{thirdPartyToken}」というコマンドを一時的に置き換えます。String

uidは「シナリオ対話機能」、「ステート」を利用する場合は必須です。

上記リクエストパラメータを含んだJsonをリクエストボディとして付与します。ユーザ識別子(uid)を含めると、ユーザごとにステートを保持することができます。

※uidは必ず一意になるように設定してください。

(例)
「サービス名_ユニークな文字列」

一意にならない場合、正常にユーザ情報が保持されない事象が発生する可能性があります。

streamにtrueを指定すると、ストリーム形式で応答が返されます。
※利用する場合は、エージェント設定画面で「ストリームの利用」を有効にしてください。
※下記の「ストリーミング応答を利用した場合」をよくお読みの上ご利用ください。

stateにKey, Valueの情報を送信すると、ステートに格納する情報をAPI経由で登録できます。

送信するステートはjsonで下記の形式になります。

{
  "username": "太郎",
  "age": "28歳",
}

username, ageはステートのキーとして保持されます。
uasername, ageというのは任意の文字列です。登録可能な値はStringのみです。

Curlサンプル

リクエストの動作確認のため、下記のCurlサンプルを必要に応じてご利用ください。(の部分は適宜置き換えてください。)

curl -H "Content-Type: application/json" -X POST -d '{"api_key":"<api key>","agent_id":"<agent_id>","utterance":"<発話>","uid":"mebo.ai_sample_001"}' https://api-mebo.dev/api

レスポンス

ステータスコード

APIから応答時に返されるステータスコードの一覧です。

ステータスコード説明
200リクエスト成功
400Bad Request リクエストに問題
401Unauthorized 認証エラー
404Not Found 存在しないエンドポイント
429Too Many Requests リクエストの超過
500Internal Server Error サーバーのエラー
503Service Unavailable サービスが利用できない

レスポンスボディ

(サンプル)

{
    "utterance": "ニックネームはなんですか？",
    "bestResponse": {
        "utterance": "ジョンと呼んでください！",
        "options": [
            "他の話題",
            "プロフィールについて",
        ],
        "topic": "プロフィールについて",
	"isAutoResponse": false,
	"extensions": null
    }
}

レスポンスパラメータ

Key説明型
utteranceユーザからの発話String
bestResponse一番スコアの高い応答Object

BestResponseオブジェクト

Key説明型
utterance応答の発話String
optionsクイックリプライの文字列String配列
topicトピックString
imageUrl画像のURLString
urlURLString
isAutoResponseAIによる自動応答かどうかBool
extensions応答に設定された付加データ(JSON) ※設定されていない場合はNULLJSONオブジェクト
shouldSelectOptionクイックリプライから選択をさせるべきか否かBool

ストリーミング応答を利用した場合

APIリクエスト時に「stream」パラメータをtrueにすると、ストリーミングでの応答が返されます。

"stream":true

ストリーミング時には、下記のレスポンスが返されます。
ストリーミング中のレスポンス
構造

{
    "bestResponse": {
        "utterance": "おはようございます！私は太郎といいます。どのようにお力になれますか？",
        "is_searching": false
    }
}

上記のJsonが一行ずつ返ります。

{"bestResponse": {"utterance": "おはようございます！私は太郎といいます。どのようにお力になれますか？","is_searching": false}}

bestResponse以外のパラメータも現在含まれていますが、将来的に不要になるパラメータです。bestResponseのutteranceを取得してください。
(他のパラメータは2023/12/31以降消去されます。)


ストリーミング終了時ののレスポンス

ストリーミングの最後に、上述のAPIの「レスポンスボディ」と同様の構造のJSONが返されます。

{"utterance":"おはようございます！","bestResponse":{"utterance":"おはようございます！私は太郎といいます。どのようにお力になれますか？","score":0.01,"options":[],"topic":"","imageUrl":"","url":"","isAutoResponse":true,"extensions":null,"shouldSelectOption":false,"state":"","embededHtml":""},"avatarIconUrl":"https://firebasestorage.googleapis.com/v0/b/mabo-f1cc7.appspot.com/o/tamago.jpeg?alt=media&token=e98701e3-4fec-4d89-84e5-a00221a4c77a","userState":{}}

ストリーミングのハンドリング時における注意点

:::message
💡 ストリーミング中には、途中のJSONが１回のレスポンスで複数返却されることが、通信状況によってはあり得ます。
:::

例: １回のレスポンスで下記が同時に返却される。

{"bestResponse": {"utterance": "おはようございます！私は太郎といいます。どのようにお力になれます","is_searching": false}}
{"bestResponse": {"utterance": "おはようございます！私は太郎といいます。どのようにお力になれますか","is_searching": false}}
{"bestResponse": {"utterance": "おはようございます！私は太郎といいます。どのようにお力になれますか？","is_searching": false}}

こういった場合に対応できるよう、APIからのレスポンスを改行で分割し、一番末端のJSONオブジェクトを利用するようにハンドリングしてください。

TypeScriptにおける例

eventSource.onmessage = (event) => {
    // 改行文字でデータを分割し、配列に格納
    const messages = event.data.split('\n');

    // 配列の最後の要素（最新のJSONオブジェクト）を取得
    const lastMessage = messages[messages.length - 1];

    // 最後のメッセージが空でない場合のみ処理
    if (lastMessage) {
        try {
            // JSONとして解析
            const jsonData = JSON.parse(lastMessage);
            // jsonDataを使用した処理
        } catch (e) {
            console.error("JSON解析エラー:", e);
        }
    }
};

拡張表現を利用する

miiboの会話コンテンツでは、エージェントの応答設定時に「拡張表現」をJson形式で設定できます。

拡張表現のJsonを設定すると、設定した応答がエージェントから返されるタイミングでextensionsというパラメータに設定したJsonが格納されます。

拡張表現を設定した場合のAPIのレスポンスの例です。

{
    "utterance": "おはようございます！",
    "bestResponse": {
        "utterance": "おはようございます！！良い天気ですね。",
        "options": [
            "他の話題",
            "調子はどう？",
            "今日は何して過ごそう"
        ],
        "topic": "",
        "imageUrl": "",
        "url": "",
        "isAutoResponse": false,
        "extensions": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}

APIをコールするサービスで利用するパラメータを応答と紐づけたい時などにご利用するのがお勧めです。

「会話開始」の判定について

シナリオ等の設定により、エージェントが会話を開始したことを検知する必要がある場合がございます。
会話の開始を明示する場合は、API経由で空の文字列をAPIで一度通信を行うことで、会話が開始したとエージェントが認識します。会話の開始時判定されると、AIのユーザーごとに保持している会話の短期記憶もリセットされます。

会話開始を判定させるためには、utteranceに空の文字列「""」を与えます。
会話開始時の発話(start_utterance)を上記の空文字と同時に指定すると、会話開始時の発言を制御できます。

Curlサンプル

curl -H "Content-Type: application/json" -X POST -d '{"api_key":"<api key>","agent_id":"<agent_id>","utterance":"","uid":"mebo.ai_sample_001"}' https://api-mebo.dev/api

以上がAPIを利用してエージェントと会話をする方法の説明になります。
このAPIを利用することで、miiboのチャット画面やLINE、Slack以外のプロダクトでエージェントと会話をすることができるようになります。ぜひ様々なプロダクトからご利用ください。

Updated 4 months ago

Did this page help you?