logo
Development
概要開発スペースワークスペースAPI Referenceベストプラクティス更新履歴
検索
日本語
API Reference / Agent API / webhookでメッセージを受信
Webhookモード
最終更新日：約1か月前

Webhookモード

GPTBotsエージェントは、現在3つのメッセージレスポンスモードに対応しています：blocking、streaming、そしてwebhookモードです。
開発者がwebhookモードを使用してレスポンスメッセージを受信する場合、AIのレスポンスと人によるレスポンスの両方が指定された Webhook URL に送信されます。

レスポンスモード サポートされるメッセージの種類
blocking AIのレスポンス
streaming AIのレスポンス
webhook AIのレスポンス、人によるレスポンス

メッセージ送信 API による webhook へのレスポンスメッセージ

メソッド

POST

呼び出し先（エンドポイントの設定）

「Agent → Integration → API → Webhook」ページにて、あなたのメッセージ受信用URLを設定してください。

認証方式

Basic 認証と Bearer 認証の2種類に対応しており、開発者は自身の状況に応じて適切な認証方式を選択し、「Agent → Integration → API → Webhook」ページで設定できます。

  • webhook アドレスを連携する際、開発者が webhook ユーザー名 のみを入力した場合、GPTBots が開発者の webhook URL へリクエストを送信する際にはデフォルトで Bearer 認証方式が使用され、その値は開発者が入力した webhook ユーザー名 になります。
  • webhook アドレスを連携する際、開発者が webhook ユーザー名 と webhook シークレットキー の両方を入力した場合、GPTBots が開発者の webhook URL へリクエストを送信する際には Basic 認証方式が使用され、ユーザー名は開発者が入力した webhook ユーザー名、パスワードは開発者が入力した webhook シークレットキー になります。

リクエスト

リクエスト例

curl -X POST 'YOUR_API_URL' \ -H 'Authorization: Bearer ${API Key}' \ -H 'Content-Type: application/json' \ -d '{ "create_time": 1679587005, "user_id": "65a4ccfc7ce58e728d5897e0", "anonymous_id": "device_abcdef123456", "conversation_id": "657303a8a764d47094874bbe", "message_id": "65a4ccfC7ce58e728d5897e0", "output": [ { "from_component_branch": "1", "from_component_name": "Component Name", "content": { "text": "Hi, is there anything I can help you?", "audio": [ { "audio": "http://gptbots.ai/example.mp3", "transcript": "The transcribed content of the audio" } ] } } ], "usage": { "tokens": { "total_tokens": 29, "prompt_tokens": 19, "prompt_tokens_details": { "audio_tokens": 0, "text_tokens":0 }, "completion_tokens": 10, "completion_tokens_details": { "reasoning_tokens": 0, "audio_tokens": 0, "text_tokens": 0 } }, "credits": { "total_credits":0.0, //prompt + completion "text_input_credits": 0.0, "text_output_credits": 0.0, "audio_input_credits": 0.0, "audio_output_credits": 0.0 } } }'
                      
                      curl -X POST 'YOUR_API_URL' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "create_time": 1679587005,
    "user_id": "65a4ccfc7ce58e728d5897e0",
    "anonymous_id": "device_abcdef123456",
    "conversation_id": "657303a8a764d47094874bbe",
    "message_id": "65a4ccfC7ce58e728d5897e0",
    "output": [
        {
            "from_component_branch": "1",
            "from_component_name": "Component Name",
            "content": {
                "text": "Hi, is there anything I can help you?",
                "audio": [
                    {
                        "audio": "http://gptbots.ai/example.mp3",
                        "transcript": "The transcribed content of the audio"
                    }
                ]
            }
        }
    ],
    "usage": {
        "tokens": {
           "total_tokens": 29,
            "prompt_tokens": 19,
            "prompt_tokens_details": 
                {  
                    "audio_tokens": 0,
                    "text_tokens":0
                },
            "completion_tokens": 10,
            "completion_tokens_details": 
                {
                    "reasoning_tokens": 0,
                    "audio_tokens": 0,
                    "text_tokens": 0
                }
        },
        "credits": {
            "total_credits":0.0,  //prompt + completion
            "text_input_credits": 0.0,
            "text_output_credits": 0.0,
            "audio_input_credits": 0.0,
            "audio_output_credits": 0.0
        }
    }
}'
このコードブロックをポップアップで表示

リクエストボディ

フィールド タイプ 説明
user_id String 開発者が紐付けたユーザーID。ユーザーが紐付けられていない場合は null です。
anonymous_id String 匿名ユーザー（デバイス）ID。
conversation_id String 会話の一意な識別子です。
message_id String 会話内の特定メッセージの一意な識別子です。
create_time Long このメッセージが生成されたタイムスタンプです。
output JSON Array AIエージェントの出力内容です。
from_component_branch String フローエージェントの分岐名です。
from_component_name String フローエージェントにおける上流コンポーネント名です。
content Object エージェントの返信内容。現在はtext と audio の2種類をサポートしています。
usage Object 使用量に関する情報です。
tokens JSON Array この対話で消費されたトークンの合計です。
total_tokens Integer 入力と出力を含めた総トークン数です。
prompt_tokens Integer 入力に使用されたトークン数です。
completion_tokens Integer 出力に使用されたトークン数です。
prompt_tokens_details Object 入力におけるトークン消費の内訳です。
completion_tokens_details Object 出力におけるトークン消費の内訳です。
credits Object この対話で消費されたクレジットの情報です。
text_input_credits Double テキスト入力メッセージに使用されたクレジット数です。
text_output_credits Double テキスト出力メッセージに使用されたクレジット数です。
audio_input_credits Double 音声入力メッセージに使用されたクレジット数です。
audio_output_credits Double 音声出力メッセージに使用されたクレジット数です。

レスポンス仕様

開発者の webhook サービスがメッセージを正常に受信した場合、HTTP ステータスコード 200 を返し、レスポンスボディに JSON 形式の成功識別子を返す必要があります。

GPTBots Webhook サービス状態の検出

GPTBots は、自身の webhook サービスを監視するためのヘルスモニタリングインターフェースを提供しています。開発者はこのインターフェースを呼び出して、GPTBots の webhook サービスが正常に利用可能かどうかを確認できます。HTTP ステータスコード 200 が返され、かつレスポンスボディがサービス正常を示す英語の識別子（例：service is normal）であれば、GPTBots の webhook サービスが正常に利用可能であることを意味します。このインターフェースは認証不要で、プレーンテキストを返します。

リクエストメソッド

GET

エンドポイント

https://api.gptbots.ai/v1/webhook/service/health

リクエスト例

curl -X GET 'https://api.gptbots.ai/v1/webhook/service/health'
                      
                      curl -X GET 'https://api.gptbots.ai/v1/webhook/service/health'
このコードブロックをポップアップで表示

レスポンス

GPTBots サービスが正常に利用可能な場合、HTTP ステータスコード 200 が返され、レスポンスボディにサービス正常を示す英語の識別子が返されます。

service is normal
                      
                      service is normal
このコードブロックをポップアップで表示

可用性の判定に関する推奨事項

呼び出し側は、HTTP ステータスコードのみを判定基準とすれば十分です：

状況 判定
200 が返され、かつレスポンスボディが service is normal GPTBots サービスは正常に利用可能
200 以外（例：5xx）が返される／リクエストタイムアウト／接続失敗 GPTBots サービスは利用不可

適切なリクエストタイムアウト（例：3～5秒）を設定し、一定の頻度でポーリング検出する（QPM:3）ことを推奨します。このインターフェースは認証不要で、呼び出し時に API Key を付与する必要はありません。