Webhook 模式

GPTBots AI 代理目前支援三種訊息回應模式：blocking、streaming 及 webhook。當開發者使用 webhook 模式接收回應訊息時，無論是「AI 回應」或「人工回應」都會提交至指定的 webhook URL。

回應模式	支援的訊息類型
blocking	AI 回應
streaming	AI 回應
webhook	人工回應、AI 回應

發送訊息 API 回應訊息到 webhook

請求方式

POST

呼叫位址

請在 Agent - 整合 - API - webhook 頁面設定你的訊息接收位址。

鑑權方式

支援 Basic 鑑權和 Bearer 鑑權兩種方式，開發者可依自身情況選擇合適的鑑權方式，並在 Agent - 整合 - 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
        }
    }
}'

此代碼塊在浮窗中顯示

請求參數

層級符號（%%、%%% 等）用於標示 JSON 結構層級，便於閱讀。

欄位	類型	描述
user_id	string	開發者綁定的使用者 ID，未綁定使用者時為 null。
anonymous_id	string	匿名使用者（裝置）ID。
conversation_id	string	對話的唯一識別碼。
message_id	string	對話中某條訊息的唯一識別碼。
create_time	long	訊息生成的時間戳。
output	JSON 陣列	AI 代理回應內容。
from_component_branch	string	FlowAgent 分支。
from_component_name	string	FlowAgent 中的上游元件名稱。
content	object	AI 代理回應訊息內容，目前包含 `text`（文字）和 `audio`（音訊）訊息類型。
usage	object	使用量消耗。
tokens	JSON 陣列	該對話中 AI 代理消耗的總 token 數量。
total_tokens	integer	該對話中輸入 + 輸出的總 token 數量。
prompt_tokens	integer	該對話中輸入消耗的 token 總數。
completion_tokens	integer	該對話中輸出消耗的 token 總數。
prompt_tokens_details	object	該對話中輸入消耗的 token 詳情。
completion_tokens_details	object	該對話中輸出消耗的 token 詳情。
credits	object	該對話中 AI 代理消耗的總點數。
text_input_credits	double	該對話中輸入文字訊息消耗的點數。
text_output_credits	double	該對話中輸出文字訊息消耗的點數。
audio_input_credits	double	該對話中輸入音訊訊息消耗的點數。
audio_output_credits	double	該對話中輸出音訊訊息消耗的點數。

回應規範

當開發者的 webhook 服務成功接收到訊息後，需回傳 HTTP 狀態碼 200，且回應體回傳 JSON 格式的成功標識。

{ "code": 200, // 狀態碼 "msg": "success" // 狀態訊息 }

                      
                      {
  "code": 200, // 狀態碼
  "msg": "success" // 狀態訊息
}

此代碼塊在浮窗中顯示

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。