Chapter 11

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

maKunugi

2022.01.23に更新

このチャプターの目次

APIの利用について

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を介した会話を行うことができます。