Chapter 11

APIを利用してプロダクトに組み込む

maKunugi
maKunugi
2022.01.23に更新

APIの利用について

meboではWeb APIを利用して連携ができます。

API利用の開始方法

mebo管理画面のサイドメニューから「公開設定」に移動します。ページ下部にある「APIを有効にする」をクリックします。

APIが有効化されると、APIキーが発行されます。

このAPIキーを利用してAPI連携を行なっていきます。正常に通信ができるか、Curlコマンドでリクエストを送信してみましょう。APIキーの下に、Curlコマンドが表示されているので、コピーしてターミナルで実行しましょう。

curl -H "Content-Type: application/json" -X POST -d '{"<APIキー>","agent_id":"<エージェントID>","utterance":"おはようございます!"}' https://api-mebo.dev/api

リクエストに成功すると、下記の結果が返ってきます。

{
    "utterance": "おはようございます!",
    "bestResponse": {
        "utterance": "おはようございます!",
        "score": 88.0505028,
        "options": [
            "他の話題",
            "おはよう!",
            "お腹減ったな",
            "まだ布団から出られないよ",
            "良い朝迎えられた?",
            "今日良い1日になるかな?"
        ],
        "topic": "@chat-挨拶",
        "imageUrl": "",
        "url": ""
    }
}

リクエストとレスポンスの内容については、この後詳しく見ていきます。

利用状況と会話回数上限について

API連携を進めていく前に、利用の上限について確認する方法をご紹介します。現在の利用状況と会話回数の上限を確認する場合は、meboの管理画面サイドメニューにある「利用状況」から確認できます。

meboでは、プランごとに月当たりに可能なエージェントの会話回数が決まっています。公開しているエージェントが会話するとごとに、会話回数が消費されていきます。会話回数の上限に達すると、応答が返されなくなりますので、上限を確認の上ご利用ください。

APIのリクエストについて

APIリクエストの仕様を見ていきます。

リクエストメソッド: POST
リクエストヘッダー

key value
Content-Type application/json

リクエストパラメータ

パラメータ 説明 必須
api_key APIキー String
agent_id エージェントID String
utterance 発話 String
uid ユーザ識別子 String

上記リクエストパラメータを含んだJsonをリクエストボディとして付与します。APIキーとエージェントIDはmeboの公開設定ページで表示されている値を利用します。utteranceにはユーザの発話を格納します。ユーザ識別子(uid)を含めると、ユーザごとの情報を保持します。uidは必ず一意になるように設定してください。

ex.「サービス名_ユニークな文字列」

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

APIのレスポンスについて

APIのレスポンスの仕様を見ていきます。

レスポンスのステータス

ステータス 説明
200 応答に成功
400 Bad Request リクエストに問題がある。必要なパラメータが存在しない。
401 Unauthorized 認証エラー (APIキーが有効ではない)
404 Not Found 存在しないエンドポイントにリクエストしている
500 Internal Server Error サーバーの内部エラー

レスポンスパラメータ

key 説明
utterance ユーザの発話 String
bestResponse 一番スコアの高かった応答 Object

*Objectは下記のBestResponseオブジェクトが格納されます。

BestResponseオブジェクト

key 説明 必須
utterance 応答文 String
score 応答の発話のスコア Number
options クイックリプライに表示する発話候補 String配列
topic 応答のトピック String
imageUrl 画像URL String
url URL String

レスポンスのサンプル

{
    "utterance": "おはようございます!",
    "bestResponse": {
        "utterance": "おはようございます!",
        "score": 88.0505028,
        "options": [
            "他の話題",
            "おはよう!",
            "お腹減ったな",
            "まだ布団から出られないよ",
            "良い朝迎えられた?",
            "今日良い1日になるかな?"
        ],
        "topic": "@chat-挨拶",
        "imageUrl": "",
        "url": ""
    }
}

topicには、meboで作成したトピックが格納されます。雑談表現の時は、「@chat-」という接頭語が追加されます。

以上のリクエストとレスポンスを利用することで、APIを介した会話を行うことができます。