智能体回调

智能体回调允许您的应用在特定事件发生时自动触发预设的操作或响应。通过阅读本文，您可以了解如何使用智能体回调。

功能概述

当智能体在运行过程中触发某些事件时，阿里云将主动向您的服务器发送请求。在接收到回调请求后，您可以添加相应的业务逻辑处理。

配置智能体回调

登录智能媒体服务控制台，选择您所需要配置的智能体，单击右侧操作列管理。
单击回调配置页签，开启智能体回调配置，勾选您需要配置回调的类型，并配置回调地址及鉴权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