Chapter 18

作成したエージェントとAPI経由で会話する

maKunugi
maKunugi
2022.06.07に更新

このチャプターのゴール

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

準備するもの

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

APIの利用方法

APIの有効化

公開設定ページの「APIを有効にする」を押すことで、APIが利用できるようになります。APIを有効にすると、API KEYが発行されます。API KEYを利用することで、割り当てられたプランの会話上限回数まで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

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

Curlサンプル

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

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 リクエスト成功
400 Bad Request リクエストに問題
401 Unauthorized 認証エラー
404 Not Found 存在しないエンドポイント
429 Too Many Requests リクエストの超過
500 Internal Server Error サーバーのエラー
503 Service Unavailable サービスが利用できない

レスポンスボディ

(サンプル)

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

レスポンスパラメータ

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

BestResponseオブジェクト

Key 説明
utterance 応答の発話 String
options クイックリプライの文字列 String配列
topic トピック String
imageUrl 画像のURL String
url URL String
isAutoResponse AIによる自動応答かどうか Bool
extensions 応答に設定された付加データ(JSON) ※設定されていない場合はNULL JSONオブジェクト

拡張表現を利用する

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

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

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

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

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

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