智能體回調 - Intelligent Media Services

智能體回調允許您的應用在特定事件發生時自動觸發預設的操作或響應。通過閱讀本文，您可以瞭解如何使用智能體回調。

功能概述

當智能體在運行過程中觸發某些事件時，阿里雲將主動向您的伺服器發送請求。在接收到回調請求後，您可以添加相應的商務邏輯處理。

配置智能體回調

登入智能媒體服務控制台，選擇您所需要配置的智能體，單擊右側操作列管理。
單擊回調配置頁簽，開啟智能體回調配置，勾選您需要配置回調的類型，並配置回調地址及鑒權Token（可選）。

說明
Token將作為鑒權資訊置於要求標頭的 Authorization 欄位中，接收方可驗簽以確保請求安全。

可選的回調類型包括：智能體狀態回調、工作流程狀態回調、聊天記錄即時回調、掛斷電話意圖檢測回調、電話呼出狀態回調、電話呼入狀態回調、用戶端推送的自訂訊息回調、指令回調。若回調地址同時支援HTTP和HTTPS請求，請優先使用HTTPS。
單擊確定，完成智能體回調配置。

回調訊息體欄位說明

名稱	類型	必填	描述	樣本值
aiAgentId	String	是	智能體ID。	xxxxx
instanceId	String	是	智能體執行個體的唯一ID。	39f8e0bc005e4f309379701645f4****
event	String	是	事件類型。智能體狀態回調： agent_start：智能體任務已開啟。 session_start：通話已建立。 agent_stop：智能體任務已關閉。 error：錯誤發生。工作流程狀態回調： intent_detected：開始識別到使用者的說話意圖時觸發。 intent_recognized：識別到較為完整的使用者說話意圖時觸發。 llm_data_received：收到LLM應答資料，對於流式應答，將在第一次收到應答時觸發。 tts_data_received：收到TTS應答資料，對於流式應答，將在第一次收到應答時觸發。聊天記錄即時回調： chat_record：即時聊天記錄。語音錄製回調： audio_record：使用者音頻：role為user，當識別到較為完整的使用者說話意圖時，觸發該過程，其內容包括使用者的語音資料及其對應的語音辨識結果。智能體音頻：role為agent，當智能體結束語音播放或使用者主動打斷智能體播放時，觸發該過程，其內容包括智能體的語音資料以及對應的文本資訊。 full_audio_record：配置開啟整通錄製後，語音通話內容合流並錄製為一個完整的音頻檔案。電話狀態回調： outbound_call：電話呼出狀態以及掛斷情況回調。 inbound_call：電話呼入狀態以及掛斷情況回調。用戶端推送的自訂訊息回調： client_defined_data：用戶端自訂訊息發送回調。（建議攜帶標識，區分訊息的開始與結束）智能體動作指令回調： instruction：智能體動作指令回調。	agent_start
data	Json	否	實際發送資料，如聊天記錄等。	chat_record 訊息對話聊天記錄： { 'requestId': 'abcd', 'code': 'Success', 'message': 'Success', 'dialogues': [ { 'roundId': 'xxxxxxx', 'producer': 'agent', 'text': '1+1=2', 'reasoningText': '嗯，使用者問的是1加1等於多少，這看起來很簡單，但我要仔細想一想。', 'time': 1739445458025, 'source': 'chat', 'dialogueId': 'xxxxxxxxxx', 'type': 'normal' }, { 'roundId': 'xxxxxxxxxxx', 'producer': 'user', 'text': '簡單回答1+1=？', 'time': 1739445436218, 'source': 'chat', 'dialogueId': 'xxxxxxxxxxx', 'type': 'normal' } ] } `{ 'role': 'user', 'type': 'normal', 'text': '講個長點兒的故事', 'sentence_id': 1 }` audio_record `{ 'role': 'user', 'sentence_id': 1, 'start_timestamp': 1743151532.33012, 'text': '講個長點兒的故事', 'audio_url': '<file oss address>' }` full_audio_record `{ 'audio_url': '<file oss address>'', 'start_timestamp': '2025-11-06T09:33:48.776253+00:00', 'end_timestamp': '2025-11-06T09:34:34.550809+00:00' }` video_frame `{ 'sentence_id': 1, 'start_timestamp': 1743151532.33012, 'text': '我的手裡拿著什嗎？', 'url_list': [<file oss address>, <file oss address>] }`
code	String	是	回調事件狀態代碼。	1001
message	String	是	具體回調資訊。	User has been kicked from the room
timestamp	String	是	時間戳記，表示回調事件的發生時間。	2023-10-01T12:00:00Z
userData	String	否	使用者自訂資訊。
extendData	Json	否	定製化擴充資訊。

事件回調樣本

電話呼出狀態回調

當event為“outbound_call”，表示回調類型為電話呼出回調；“extendData”內的欄位釋義如下：

名稱	類型	描述
aiAgentId	String	智能體ID。
channelId	String	房間ID資訊。
instanceId	String	智能體執行個體的唯一ID。
callerNumber	String	主叫（智能體）電話號碼。
calleeNumber	String	被叫電話號碼。
failReason	Int	失敗原因，僅在呼出失敗時出現。
status	Int	智能體當前通話狀態： 2：表示呼出/轉呼失敗； 3：表示呼出/轉呼成功並接通； 4：表示掛斷。
callStartTime	String	電話接通時間，僅在掛斷時出現。
callEndTime	String	電話掛斷時間，僅在掛斷時出現。
hangupRole	Int	掛斷方，僅在掛斷時出現： 0：主叫（智能體）； 1：被叫； 2：轉呼方。
forwardInfo	JSON	轉呼資訊。該欄位僅在轉呼相關回調中出現，其中包含3個子欄位： callerNumber：轉呼主叫電話號碼，資料類型為String； calleeNumber：被轉呼方電話號碼，資料類型為String； callStartTime：轉呼接通時間，資料類型為String。僅在轉呼成功/掛斷時出現。

電話呼出失敗

當使用智能體電話呼出功能時，若被叫方空號、拒接、無法接通時，智能體將發送此回調。回調資料結構如下：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10002,
  "message":"Dial status failed",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "failReason": -6,
      "status": 2
  }
}

電話呼出成功

使用智能體電話呼出，被叫方接通通話時，智能體將發送此回調。回調資料結構如下：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10003,
  "message":"Dial status connected",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 3
  }
}

使用者掛斷

使用智能體電話呼出，被叫方接通後掛斷電話，智能體將發送此回調。回調資料結構：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 4,
      "callStartTime": "2023-10-01T12:00:00.135045+00:00",
      "callEndTime": "2023-10-01T12:01:00.135045+00:00",
      "hangupRole": 1
  }
}

電話呼出掛斷

使用智能體電話呼出，在電話接通後，某一方掛斷電話時，將發送此回調，資料結構如下：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 4,
      "callStartTime": "2023-10-01T12:00:00.135045+00:00",
      "callEndTime": "2023-10-01T12:01:00.135045+00:00",
      "hangupRole": 0
  }
}

電話轉呼成功

使用智能體電話呼出，並發起轉呼後，轉呼方接通通話時，將發送此回調。回調資料結構如下：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10006,
  "message":"Forward call connected",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 3,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX",
        "callStartTime": "2023-10-01T12:00:59Z"
      }
  }
}

電話轉呼失敗

使用智能體電話呼出，並發起轉呼後，轉呼失敗時，將發送此回調，資料結構如下：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10005,
  "message":"Forward call failed",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "failReason": 480,
      "status": 2,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX"
      }
  }
}

電話轉呼掛斷

使用智能體電話呼出，並轉呼成功後，某一方掛斷電話時，將發送此回調，資料結構如下：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 4,
      "callStartTime": "2023-10-01T12:00:00.135045+00:00",
      "callEndTime": "2023-10-01T12:01:00.135045+00:00",
      "hangupRole": 2,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX",
        "callStartTime": "2023-10-01T12:00:59Z"
      }
  }
}

電話呼入狀態回調

當event為“inbound_call”，表示回調類型為電話呼入回調；“extendData”內的欄位釋義如下：

名稱	類型	描述
aiAgentId	String	同主訊息體欄位。
channelId	String	房間ID資訊。
instanceId	String	同主訊息體欄位。
callerNumber	String	主叫（呼入方）電話號碼。
calleeNumber	String	被叫（智能體）電話號碼。
failReason	Int	失敗原因，僅在呼入失敗時出現。
status	Int	智能體當前通話狀態： 2：表示呼入/轉呼失敗； 3：表示呼入/轉呼成功並接通； 4：表示掛斷。
callStartTime	String	電話接通時間，僅在掛斷時出現。
callEndTime	String	電話掛斷時間，僅在掛斷時出現。
hangupRole	Int	掛斷方，僅在掛斷時出現： 0：被叫（智能體）； 1：主叫（呼入方）； 2：轉呼方。
forwardInfo	JSON	轉呼資訊。該欄位僅在轉呼相關回調中出現，其中包含3個子欄位： callerNumber：轉呼主叫電話號碼，資料類型為String； calleeNumber：被轉呼方電話號碼，資料類型為String； callStartTime：轉呼接通時間，資料類型為String。僅在轉呼成功/掛斷時出現。

電話呼入成功

使用智能體電話呼入，智能體接通通話時，將發送此回調。回調資料結構如下：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10003,
  "message":"Dial status connected",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 3
  }
}

電話呼入失敗

使用智能體電話呼入，智能體接通通話失敗時，將發送此回調，資料結構如下：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10002,
  "message":"Dial status failed",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "failReason": -6,
      "status": 2
  }
}

電話呼入掛斷

使用智能體電話呼入，在電話接通後，某一方掛斷電話時，將發送此回調，資料結構如下：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 4,
      "callStartTime": "2023-10-01T12:00:00.135045+00:00",
      "callEndTime": "2023-10-01T12:01:00.135045+00:00",
      "hangupRole": 0
  }
}

電話轉呼成功

使用智能體電話呼入，並發起轉呼後，轉呼方接通通話時，將發送此回調。回調資料結構如下：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10006,
  "message":"Forward call connected",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 3,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX",
        "callStartTime": "2023-10-01T12:00:59Z"
      }
  }
}

電話轉呼失敗

使用智能體電話呼入，並發起轉呼後，轉呼失敗時，將發送此回調，資料結構如下：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10005,
  "message":"Forward call failed",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "failReason": 480,
      "status": 2,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX"
      }
  }
}

電話轉呼掛斷

使用智能體電話呼入，並轉呼成功後，某一方掛斷電話時，將發送此回調，資料結構如下：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "aiAgentId": "0d31c************b3c787",
      "channelId": "XXX",
      "instanceId": "39f8e0bc005e4f309379*********",
      "callerNumber": "XXX",
      "calleeNumber": "XXX",
      "status": 4,
      "callStartTime": "2023-10-01T12:00:00.135045+00:00",
      "callEndTime": "2023-10-01T12:01:00.135045+00:00",
      "hangupRole": 2,
      "forwardInfo": {
        "callerNumber": "XXX",
        "calleeNumber": "XXX",
        "callStartTime": "2023-10-01T12:00:59Z"
      }
  }
}

工作流程狀態回調

當event為類型為工作流程狀態回調時，“extendData”內的欄位釋義如下：

名稱	類型	描述
channelId	String	房間ID資訊。
sentenceId	Int	問答ID資訊。說明對於使用者的同一次提問，智能體回答會使用相同的ID資訊。
requestTimestamp	String	當event為llm_data_received時，表示向LLM模型發起請求的時間戳記資訊。當event為tts_data_received時，表示向TTS模型發起請求的時間戳記資訊。當event為intent_recognized時，表示智能體檢測到使用者說話結束的時間戳記資訊。當智能體判斷未達到語音結束的檢測條件時，此時值為None。
responseTimestamp	String	當event為llm_data_received時，表示從LLM模型收到第一次應答的時間戳記資訊。當event為tts_data_received時，表示從TTS模型收到第一次應答的時間戳記資訊。當event為intent_recognized時，表示在使用者說話結束後得到ASR識別結果的時間戳記資訊。

智能體動作指令回調

當event類型為instruction時，表示回調類型為智能體動作指令回調，該回調錶明某一動作指令標籤被觸發。當前支援的動作指令回調包括了：

電話轉呼指令回調

當智能體輸出了電話轉呼動作指令標籤時，智能體將發送如下所示資料結構的回調：

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"instruction",
  "code":11001,
  "message":"Forward call triggered",
  "timestamp":"2023-10-01T12:00:00Z",
  "extenddData":{
      "triggerTime": "2023-10-01T12:00:00Z"
  }
}

Server 樣本

Python

from aiohttp import web
import json
from loguru import logger
async def handle_post(request):
    """
    處理POST請求並記錄接收到的資料。
    """
    # 擷取要求標頭中的Authorization
    authorization_header = request.headers.get('Authorization')
    if authorization_header is None or not authorization_header.startswith('Bearer fixed-token'):
        logger.error("Unauthorized request")
        return web.Response(status=401, text='Unauthorized')
    try:
        # 從請求體中擷取資料
        callback_data = await request.json()
        logger.info("Parsed JSON data:")
        logger.info(json.dumps(callback_data, indent=4))
        return web.Response(text='Callback received successfully', status=200)
    except json.JSONDecodeError:
        # 如果JSON解析失敗，則返回錯誤響應
        return web.Response(text='Invalid JSON', status=400)
app = web.Application()
app.add_routes([web.post('/', handle_post)])
if __name__ == '__main__':
    web.run_app(app, host='localhost', port=8081)

回調事件狀態代碼

狀態代碼	回調事件	回調資訊
1001	智能體啟動	AI Agent starts.
1002	智能體終止	AI Agent ends.
1003	會話建立	Session starts
4001	數字人並發路數超額	Concurrent routes exhausted
4002	智能體被踢出房間	User has been kicked from the room
4003	智能體token有誤	Invalid token for the AI agent
4004	智能體訂閱音頻流失敗	Failed to pull stream for the AI agent
4005	第三方ASR失敗	error description
4006	數字人服務不可用	Avatar service is not available
8001	意圖識別事件	Intent recognized event
8002	大模型資料接收事件	LLM data received event
8003	TTS資料接收事件	TTS data received event
10002	電話接通失敗	Dial status failed
10003	電話接通成功	Dial status connected
10004	電話掛斷	Hangup
10005	電話轉呼失敗	Forward call failed
10006	電話轉呼成功	Forward call connected
11001	轉呼指令觸發	Forward call triggered