チャットAPIの利用方法

miiboで作成したエージェントとAPI経由で会話が可能です。

エージェント会話API仕様

リクエスト情報

• メソッド: POST
• エンドポイント: https://api-mebo.dev/api

ヘッダー

Key	Value
Content-Type	application/json

パラメータ

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

• uid: 「シナリオ対話機能」、「ステート」を利用する場合は必須。一意にならない場合、ユーザ情報が正常に保持されない可能性あり。例：「サービス名_ユニークな文字列」
• stream: true指定でストリーム形式応答。利用する場合は、エージェント設定画面で「ストリームの利用」を有効にしてください。
• state: Key, Valueを指定してステート情報を追加する事が可能。登録可能な値はStringのみ。例:

JSON

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

Curlサンプル

Bash

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

レスポンス情報

ステータスコード

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

レスポンスボディ (サンプル)

JSON

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

レスポンスボディ

パラメータ	説明	型
utterance	ユーザーの発話	String
bestResponse	エージェントの最適な応答	Object
userState	ユーザーステート	Object

userStateはエージェントとユーザーが会話を行い保持された、ステートのペアが格納されます。

JSON

{
    "興味のある商品": "冷蔵庫",
    "購買意欲": "3"
}

bestResponseオブジェクトは以下のプロパティを含みます：

パラメータ	説明	型	備考
utterance	エージェントの応答	String
score	応答スコア	Float
options	オプション	Array
topic	トピック	String
imageUrl	画像URL	String
url	URL	String
isAutoResponse	自動応答かどうか	Boolean
isSearching	検索中かどうか	Boolean
extensions	拡張子	String	null
shouldSelectOption	クイックリプライから選択をさせるべきか否か	Boolean
state	トピックやシナリオで発火した発言に紐づくステートのキー	String
scenarioNode	呼び出されたシナリオにおける現在のシナリオノードの詳細情報	Object	Deprecated
(2023/8/20まで)
embededHtml	埋め込みHTML	String	※一部のお客様にのみ提供

拡張表現を利用する

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

会話開始の判定

API経由で空の文字列「""」をAPIで一度通信を行うことで、会話が開始したとエージェントが認識します。

Curlサンプル:

Bash

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

💡 会話開始時の発話(start_utterance)を上記の空文字と同時に指定すると、会話開始時の発言を制御できます。

ストリーミングを利用した応答 (Beta版)

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

JSX

"stream":true

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

ストリーミング中のレスポンス

構造

JSON

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

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

JSON

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

💡 bestResponse以外のパラメータも現在含まれていますが、将来的に不要になるパラメータです。bestResponseのutteranceを取得してください。

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

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

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":{}}

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

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

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

JSON

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

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

TypeScriptにおける例

JavaScript

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);
        }
    }
};