Agent callbacks - Intelligent Media Services: Central de Documentação do Alibaba Cloud

Use callbacks do agente para acionar automaticamente ações ou respostas predefinidas na sua aplicação quando eventos específicos ocorrerem.

Visão geral

Quando um agente de IA dispara determinados eventos de execução, a Alibaba Cloud envia uma solicitação de callback ao seu servidor. Você pode então adicionar lógica de negócios para processar essa solicitação.

Configure callbacks do agente

Faça login no console do Intelligent Media Service. Selecione o agente que deseja configurar e clique em Manage na coluna Actions.
Na aba Callback Configuration, ative os callbacks do agente, selecione os tipos de callback e insira a Callback URL e um Authentication Token opcional.

Nota
Esse token é enviado no campo Authorization do cabeçalho da solicitação. Seu servidor deve verifique esse token para garantir a segurança da requisição.

Os tipos de callback disponíveis incluem: Agent status callbacks, Workflow status callbacks, Real-time chat history callbacks, Hang-up intent detection callbacks, Outbound call status callbacks, Inbound call status callbacks, Custom client message callbacks e Instruction callbacks. Se a URL de callback suportar HTTP e HTTPS, recomenda-se fortemente o uso de HTTPS para maior segurança.
Clique em OK para concluir a configuração de callback.

Campos do payload de callback

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
aiAgentId	String	Sim	ID do agente.	xxxxx
instanceId	String	Sim	ID exclusivo da instância do agente.	39f8e0bc005e4f309379701645f4****
event	String	Sim	Tipo de evento. Callback de status do agente: agent_start: disparado quando a tarefa do agente inicia. session_start: disparado quando a sessão de chamada é estabelecida. agent_stop: disparado quando a tarefa do agente para. error: disparado quando ocorre um erro. Callback de status do fluxo de trabalho: intent_detected: disparado quando o agente começa a detectar a intenção do usuário. intent_recognized: disparado quando o agente reconhece uma intenção de usuário mais completa. llm_data_received: disparado quando dados de resposta são recebidos do modelo de linguagem grande (LLM). Para respostas em streaming, este evento é disparado ao receber o primeiro pacote de dados. tts_data_received: disparado quando dados de resposta são recebidos do serviço Text-to-Speech (TTS). Para respostas em streaming, este evento é disparado ao receber o primeiro pacote de dados. Callback de registro de chat em tempo real: chat_record: fornece uma transcrição em tempo real da conversa. Callback de gravação de áudio: audio_record: Áudio do usuário (role="user"): disparado quando o agente reconhece uma intenção de usuário mais completa. O payload contém os dados de áudio do usuário e o resultado correspondente de speech-to-text (STT). Áudio do agente (role="agent"): disparado quando o agente termina de reproduzir o áudio ou quando o usuário o interrompe. O payload contém os dados de áudio do agente e o texto correspondente. full_audio_record: disparado após o término da chamada se a gravação completa estiver ativada. O payload contém um link para o arquivo de áudio completo com canais mixados. Callback de status de chamada: outbound_call: disparado para alterações de status ou eventos de desligamento em uma chamada de saída. inbound_call: disparado para alterações de status ou eventos de desligamento em uma chamada de entrada. Callback para mensagens personalizadas do cliente: client_defined_data: callback para mensagens personalizadas enviadas pelo cliente. Recomenda-se incluir um identificador para distinguir o início e o fim de uma mensagem. Callback de instrução de ação do agente: instruction: contém uma instrução de ação para o agente executar.	agent_start
data	Json	Não	Payload de dados. A estrutura deste campo depende do tipo de evento.	chat_record Registro de chat de mensagem de texto: { 'requestId': 'abcd', 'code': 'Success', 'message': 'Success', 'dialogues': [ { 'roundId': 'xxxxxxx', 'producer': 'agent', 'text': '1+1=2', 'reasoningText': 'The user is asking what 1+1 is. It seems simple, but I need to think carefully.', 'time': 1739445458025, 'source': 'chat', 'dialogueId': 'xxxxxxxxxx', 'type': 'normal' }, { 'roundId': 'xxxxxxxxxxx', 'producer': 'user', 'text': 'Just answer, what is 1+1?', 'time': 1739445436218, 'source': 'chat', 'dialogueId': 'xxxxxxxxxxx', 'type': 'normal' } ] } `{ 'role': 'user', 'type': 'normal', 'text': 'Tell me a long story.', 'sentence_id': 1 }` audio_record `{ 'role': 'user', 'sentence_id': 1, 'start_timestamp': 1743151532.33012, 'text': 'Tell me a long story.', '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' }`
code	String	Sim	Código de status do evento de callback.	1001
message	String	Sim	Mensagem de callback.	User has been kicked from the room
timestamp	String	Sim	Momento em que o evento ocorreu, formatado como string ISO 8601 (UTC).	2023-10-01T12:00:00Z
userData	String	Não	Informações definidas pelo usuário.
extendData	Json	Não	Dados de extensão personalizados.

Exemplos de callback

Status de chamada de saída

Quando o event é outbound_call, este callback relata o status de uma chamada de saída. A tabela a seguir descreve os campos no objeto extendData para este evento.

Parâmetro	Tipo	Descrição
aiAgentId	String	ID do agente de IA.
channelId	String	ID do canal.
instanceId	String	ID exclusivo da instância do agente de IA.
callerNumber	String	Número de telefone de quem liga (o agente de IA).
calleeNumber	String	Número de telefone de quem recebe a chamada.
failReason	Int	Motivo da falha. Retornado apenas quando a chamada de saída falha.
status	Int	Status atual da chamada do agente de IA. Valores possíveis: `2`: falha na chamada de saída ou na transferência de chamada. `3`: chamada de saída ou transferência de chamada conectada com sucesso. `4`: chamada desligada.
callStartTime	String	Horário em que a chamada foi conectada. Retornado apenas no desligamento.
callEndTime	String	Horário em que a chamada foi desligada. Retornado apenas no desligamento.
hangupRole	Int	Parte que desligou a chamada. Retornado apenas no desligamento. Valores possíveis: `0`: quem ligou (o agente de IA). `1`: quem recebeu a chamada. `2`: parte que recebeu a chamada transferida.
forwardInfo	JSON	Informações sobre a transferência de chamada. Retornado apenas para callbacks relacionados a transferência de chamada. Contém os seguintes subcampos: `callerNumber`: número de telefone da parte que iniciou a transferência. Tipo de dados: String. `calleeNumber`: número de telefone da parte que recebeu a transferência. Tipo de dados: String. `callStartTime`: horário em que a chamada transferida foi conectada. Tipo de dados: String. Retornado apenas se a transferência for bem-sucedida ou se ocorrer um desligamento.

Falha na chamada de saída

Este callback indica que uma chamada de saída falhou porque o número de quem recebeu a chamada era inválido, a chamada foi rejeitada ou o destinatário estava inacessível.

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

Chamada de saída conectada

Este callback é enviado quando o destinatário atende a uma chamada de saída.

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

Desligamento pelo destinatário

Este callback é enviado quando o destinatário desliga após a conexão de uma chamada de saída.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "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
  }
}

Desligamento pelo agente

Este callback é enviado quando o agente de IA desliga após a conexão de uma chamada de saída.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "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
  }
}

Transferência de chamada bem-sucedida

Este callback é enviado quando uma transferência de chamada é conectada com sucesso.

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

Falha na transferência de chamada

Este callback é enviado quando uma transferência de chamada falha.

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

Desligamento após transferência de chamada

Este callback é enviado quando a parte que recebeu a transferência desliga.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"outbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "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"
      }
  }
}

Status de chamada de entrada

Quando o event é inbound_call, este callback relata o status de uma chamada de entrada. A tabela a seguir descreve os campos no objeto extendData para este evento.

Parâmetro	Tipo	Descrição
aiAgentId	String	Valor igual ao campo `aiAgentId` de nível superior no callback.
channelId	String	ID do canal.
instanceId	String	Valor igual ao campo `instanceId` de nível superior no callback.
callerNumber	String	Número de telefone de quem liga (a parte que faz a chamada de entrada).
calleeNumber	String	Número de telefone de quem recebe a chamada (o agente de IA).
failReason	Int	Motivo da falha. Retornado apenas quando a chamada de entrada falha.
status	Int	Status atual da chamada do agente de IA. Valores possíveis: `2`: falha na chamada de entrada ou na transferência de chamada. `3`: chamada de entrada ou transferência de chamada conectada com sucesso. `4`: chamada desligada.
callStartTime	String	Horário em que a chamada foi conectada. Retornado apenas no desligamento.
callEndTime	String	Horário em que a chamada foi desligada. Retornado apenas no desligamento.
hangupRole	Int	Parte que desligou a chamada. Retornado apenas no desligamento. Valores possíveis: `0`: quem recebeu a chamada (o agente de IA). `1`: quem ligou (a parte que fez a chamada de entrada). `2`: parte que recebeu a chamada transferida.
forwardInfo	JSON	Informações sobre a transferência de chamada. Retornado apenas para callbacks relacionados a transferência de chamada. Contém os seguintes subcampos: `callerNumber`: número de telefone da parte que iniciou a transferência. Tipo de dados: String. `calleeNumber`: número de telefone da parte que recebeu a transferência. Tipo de dados: String. `callStartTime`: horário em que a chamada transferida foi conectada. Tipo de dados: String. Retornado apenas se a transferência for bem-sucedida ou se ocorrer um desligamento.

Chamada de entrada conectada

Este callback é enviado quando o agente de IA atende com sucesso a uma chamada de entrada.

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

Falha na chamada de entrada

Este callback é enviado quando o agente de IA não consegue atender a uma chamada de entrada.

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

Desligamento de chamada de entrada

Este callback é enviado quando o agente de IA desliga após a conexão de uma chamada de entrada.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "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
  }
}

Transferência de chamada bem-sucedida

Este callback é enviado quando uma transferência de chamada de entrada é conectada com sucesso.

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

Falha na transferência de chamada

Este callback é enviado quando uma transferência de chamada de entrada falha.

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

Desligamento após transferência de chamada

Este callback é enviado quando a parte que recebeu a transferência desliga após uma transferência de chamada de entrada.

{
  "aiAgentId":"0d31c************b3c787",
  "instanceId":"39f8e0bc005e4f309379*********",
  "event":"inbound_call",
  "code":10004,
  "message":"Hangup",
  "timestamp":"2023-10-01T12:00:00Z",
  "extendData":{
      "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"
      }
  }
}

Status do fluxo de trabalho

Para eventos de status do fluxo de trabalho, o objeto extendData contém os seguintes campos:

Parâmetro	Tipo	Descrição
channelId	String	ID do canal.
sentenceId	Int	ID exclusivo para um turno de conversa. Nota As respostas do agente de IA a uma única consulta do usuário compartilham o mesmo `sentenceId`.
requestTimestamp	String	Evento llm_data_received: timestamp de envio da solicitação ao LLM. Evento tts_data_received: timestamp de envio da solicitação ao serviço TTS. Evento intent_recognized: timestamp em que o agente de IA detectou o fim da fala do usuário. Se o agente ainda não determinou o fim da fala, este valor é `None`.
responseTimestamp	String	Evento llm_data_received: timestamp da primeira resposta do LLM. Evento tts_data_received: timestamp da primeira resposta do serviço TTS. Evento intent_recognized: timestamp em que o resultado ASR foi retornado após o usuário terminar de falar.

Callback de instrução

Quando o tipo de event é instruction, o callback indica que uma tag específica de instrução de ação foi acionada. Os callbacks de instrução suportados incluem:

Callback de instrução de transferência de chamada

Este callback é enviado quando o agente de IA aciona uma tag de ação de transferência de chamada.

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

Exemplo de servidor

Python

from aiohttp import web
import json
from loguru import logger
async def handle_post(request):
    """
    Handle POST requests and log the received data.
    """
    # Get the Authorization header from the request.
    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:
        # Parse the request body as JSON.
        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:
        # Return an error if JSON parsing fails.
        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)

Códigos de status de evento de callback

Código de status	Evento de callback	Descrição
1001	Agent starts	Agente iniciado.
1002	Agent stops	Agente parado.
1003	Session starts	Sessão iniciada.
4001	Concurrent agent routes exhausted	Número máximo de rotas simultâneas do agente atingido.
4002	Agent kicked from channel	Sistema removeu o agente do canal.
4003	Invalid agent token	Token do agente inválido.
4004	Agent stream subscription failed	Falha na assinatura do stream pelo agente.
4005	Third-party ASR failed	Falha no serviço ASR de terceiros.
4006	Avatar service unavailable	Serviço de avatar indisponível.
8001	Intent recognized	Intenção reconhecida.
8002	LLM data received	Dados do LLM recebidos.
8003	TTS data received	Dados do TTS recebidos.
10002	Dial status failed	Falha na conexão da chamada.
10003	Dial status connected	Chamada conectada com sucesso.
10004	Hangup	Chamada desligada.
10005	Forward call failed	Falha na tentativa de encaminhamento de chamada.
10006	Forward call connected	Chamada encaminhada conectada com sucesso.
11001	Forward call triggered	Encaminhamento de chamada acionado pelo sistema.