Agent callbacks - Intelligent Media Services - Centre de documentation Alibaba Cloud

Utilisez les rappels d'agent pour déclencher automatiquement des actions ou réponses prédéfinies dans votre application lors de la survenue d'événements spécifiques.

Présentation

Lorsqu'un agent IA déclenche certains événements d'exécution, Alibaba Cloud envoie une requête de rappel à votre serveur. Vous pouvez alors y intégrer une logique métier pour traiter cette requête.

Configuration des rappels d'agent

Connectez-vous à la console Intelligent Media Service. Sélectionnez l'agent à configurer, puis cliquez sur Manage dans la colonne Actions.
Sous l'onglet Callback Configuration, activez les rappels d'agent, sélectionnez les types de rappel souhaités, puis saisissez l'Callback URL et, le cas échéant, un Authentication Token.

Remarque
Ce jeton est transmis dans le champ Authorization de l'en-tête de la requête. Votre serveur doit vérifier ce jeton pour garantir la sécurité des échanges.

Les types de rappel disponibles sont les suivants : 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 et Instruction callbacks. Si votre URL de rappel prend en charge les protocoles HTTP et HTTPS, l'utilisation de HTTPS est fortement recommandée pour renforcer la sécurité.
Cliquez sur OK pour valider la configuration du rappel.

Champs de la charge utile du rappel

Parameter	Type	Required	Description	Example
aiAgentId	String	Yes	ID de l'agent.	xxxxx
instanceId	String	Yes	ID unique de l'instance de l'agent.	39f8e0bc005e4f309379701645f4****
event	String	Yes	Type d'événement. Rappel d'état de l'agent : agent_start : Déclenché au démarrage de la tâche de l'agent. session_start : Déclenché lors de l'établissement de la session d'appel. agent_stop : Déclenché à l'arrêt de la tâche de l'agent. error : Déclenché en cas d'erreur. Rappel d'état du workflow : intent_detected : Déclenché lorsque l'agent commence à détecter l'intention de l'utilisateur. intent_recognized : Déclenché lorsque l'agent identifie une intention utilisateur plus complète. llm_data_received : Déclenché à la réception des données de réponse du grand modèle de langage (LLM). Pour une réponse en flux continu, cet événement est déclenché dès la réception du premier paquet de données. tts_data_received : Déclenché à la réception des données de réponse du service Text-to-Speech (TTS). Pour une réponse en flux continu, cet événement est déclenché dès la réception du premier paquet de données. Rappel d'historique de chat en temps réel : chat_record : Fournit une transcription en temps réel de la conversation. Rappel d'enregistrement audio : audio_record : Audio utilisateur (role="user") : Déclenché lorsque l'agent identifie une intention utilisateur plus complète. La charge utile contient les données audio de l'utilisateur et le résultat correspondant de la reconnaissance vocale (STT). Audio de l'agent (role="agent") : Déclenché lorsque l'agent termine la lecture audio ou lorsque l'utilisateur l'interrompt. La charge utile contient les données audio de l'agent et le texte correspondant. full_audio_record : Déclenché après la fin de l'appel si l'enregistrement complet est activé. La charge utile contient un lien vers le fichier audio complet mixé. Rappel d'état d'appel : outbound_call : Déclenché lors des changements d'état ou des événements de raccrochage d'un appel sortant. inbound_call : Déclenché lors des changements d'état ou des événements de raccrochage d'un appel entrant. Rappel pour les messages personnalisés du client : client_defined_data : Rappel pour les messages personnalisés envoyés par le client. Il est recommandé d'inclure un identifiant pour distinguer le début et la fin d'un message. Rappel d'instruction d'action de l'agent : instruction : Contient une instruction d'action à exécuter par l'agent.	agent_start
data	Json	No	Charge utile des données. La structure de ce champ dépend du type d'événement.	chat_record Historique de chat de messages textuels : { '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	Yes	Code d'état de l'événement de rappel.	1001
message	String	Yes	Message de rappel.	User has been kicked from the room
timestamp	String	Yes	Heure de l'événement, formatée selon la norme ISO 8601 (UTC).	2023-10-01T12:00:00Z
userData	String	No	Informations définies par l'utilisateur.
extendData	Json	No	Données d'extension personnalisées.

Exemples de rappels

État de l'appel sortant

Lorsque l'événement event est outbound_call, ce rappel indique l'état d'un appel sortant. Le tableau suivant décrit les champs de l'objet extendData pour cet événement.

Parameter	Type	Description
aiAgentId	String	ID de l'agent IA.
channelId	String	ID du canal.
instanceId	String	ID unique de l'instance de l'agent IA.
callerNumber	String	Numéro de téléphone de l'appelant (l'agent IA).
calleeNumber	String	Numéro de téléphone du destinataire.
failReason	Int	Motif de l'échec. Ce champ n'est renvoyé qu'en cas d'échec de l'appel sortant.
status	Int	État actuel de l'appel de l'agent IA. Les valeurs possibles sont : `2` : L'appel sortant ou le transfert d'appel a échoué. `3` : L'appel sortant ou le transfert d'appel a été établi avec succès. `4` : L'appel a été raccroché.
callStartTime	String	Heure de connexion de l'appel. Ce champ n'est renvoyé qu'au moment du raccrochage.
callEndTime	String	Heure de fin de l'appel (raccrochage). Ce champ n'est renvoyé qu'au moment du raccrochage.
hangupRole	Int	Partie ayant raccroché. Ce champ n'est renvoyé qu'au moment du raccrochage. Les valeurs possibles sont : `0` : L'appelant (l'agent IA). `1` : Le destinataire. `2` : La partie ayant reçu l'appel transféré.
forwardInfo	JSON	Informations relatives au transfert d'appel. Ce champ n'est renvoyé que pour les rappels liés aux transferts d'appel. Il contient les sous-champs suivants : `callerNumber` : Numéro de téléphone de la partie initiant le transfert. Type de données : String. `calleeNumber` : Numéro de téléphone de la partie recevant le transfert. Type de données : String. `callStartTime` : Heure de connexion de l'appel transféré. Type de données : String. Ce champ n'est renvoyé que si le transfert réussit ou en cas de raccrochage.

Échec de l'appel sortant

Ce rappel indique qu'un appel sortant a échoué car le numéro du destinataire était invalide, l'appel a été rejeté ou le destinataire était injoignable.

{
  "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
  }
}

Appel sortant connecté

Ce rappel est envoyé lorsque le destinataire répond à un appel sortant.

{
  "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
  }
}

Raccrochage du destinataire

Ce rappel est envoyé lorsque le destinataire raccroche après la connexion d'un appel sortant.

{
  "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
  }
}

Raccrochage de l'agent

Ce rappel est envoyé lorsque l'agent IA raccroche après la connexion d'un appel sortant.

{
  "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
  }
}

Transfert d'appel réussi

Ce rappel est envoyé lorsqu'un transfert d'appel est établi avec succès.

{
  "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"
      }
  }
}

Échec du transfert d'appel

Ce rappel est envoyé lorsqu'un transfert d'appel échoue.

{
  "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"
      }
  }
}

Raccrochage après transfert d'appel

Ce rappel est envoyé lorsque la partie ayant reçu le transfert raccroche.

{
  "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"
      }
  }
}

État de l'appel entrant

Lorsque l'événement event est inbound_call, ce rappel indique l'état d'un appel entrant. Le tableau suivant décrit les champs de l'objet extendData pour cet événement.

Parameter	Type	Description
aiAgentId	String	Cette valeur est identique au champ de niveau supérieur `aiAgentId` du rappel.
channelId	String	ID du canal.
instanceId	String	Cette valeur est identique au champ de niveau supérieur `instanceId` du rappel.
callerNumber	String	Numéro de téléphone de l'appelant (la partie effectuant l'appel entrant).
calleeNumber	String	Numéro de téléphone du destinataire (l'agent IA).
failReason	Int	Motif de l'échec. Ce champ n'est renvoyé qu'en cas d'échec de l'appel entrant.
status	Int	État actuel de l'appel de l'agent IA. Les valeurs possibles sont : `2` : L'appel entrant ou le transfert d'appel a échoué. `3` : L'appel entrant ou le transfert d'appel a été établi avec succès. `4` : L'appel a été raccroché.
callStartTime	String	Heure de connexion de l'appel. Ce champ n'est renvoyé qu'au moment du raccrochage.
callEndTime	String	Heure de fin de l'appel (raccrochage). Ce champ n'est renvoyé qu'au moment du raccrochage.
hangupRole	Int	Partie ayant raccroché. Ce champ n'est renvoyé qu'au moment du raccrochage. Les valeurs possibles sont : `0` : Le destinataire (l'agent IA). `1` : L'appelant (la partie effectuant l'appel entrant). `2` : La partie ayant reçu l'appel transféré.
forwardInfo	JSON	Informations relatives au transfert d'appel. Ce champ n'est renvoyé que pour les rappels liés aux transferts d'appel. Il contient les sous-champs suivants : `callerNumber` : Numéro de téléphone de la partie initiant le transfert. Type de données : String. `calleeNumber` : Numéro de téléphone de la partie recevant le transfert. Type de données : String. `callStartTime` : Heure de connexion de l'appel transféré. Type de données : String. Ce champ n'est renvoyé que si le transfert réussit ou en cas de raccrochage.

Appel entrant connecté

Ce rappel est envoyé lorsque l'agent IA répond avec succès à un appel entrant.

{
  "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
  }
}

Échec de l'appel entrant

Ce rappel est envoyé lorsque l'agent IA ne parvient pas à répondre à un appel entrant.

{
  "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
  }
}

Raccrochage de l'appel entrant

Ce rappel est envoyé lorsque l'agent IA raccroche après la connexion d'un appel entrant.

{
  "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
  }
}

Transfert d'appel réussi

Ce rappel est envoyé lorsqu'un transfert d'appel issu d'un appel entrant est établi avec succès.

{
  "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"
      }
  }
}

Échec du transfert d'appel

Ce rappel est envoyé lorsqu'un transfert d'appel issu d'un appel entrant échoue.

{
  "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"
      }
  }
}

Raccrochage après transfert d'appel

Ce rappel est envoyé lorsque la partie ayant reçu le transfert raccroche après un transfert issu d'un appel entrant.

{
  "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"
      }
  }
}

État du workflow

Pour les événements d'état du workflow, l'objet extendData contient les champs suivants :

Parameter	Type	Description
channelId	String	ID du canal.
sentenceId	Int	ID unique d'un tour de conversation. Remarque Les réponses de l'agent IA à une seule requête utilisateur partagent le même `sentenceId`.
requestTimestamp	String	Pour l'événement llm_data_received, il s'agit de l'horodatage d'envoi de la requête au LLM. Pour l'événement tts_data_received, il s'agit de l'horodatage d'envoi de la requête au service TTS. Pour l'événement intent_recognized, il s'agit de l'horodatage auquel l'agent IA a détecté la fin de la parole de l'utilisateur. Si l'agent n'a pas encore déterminé la fin de la parole, cette valeur est `None`.
responseTimestamp	String	Pour l'événement llm_data_received, il s'agit de l'horodatage de la première réponse du LLM. Pour l'événement tts_data_received, il s'agit de l'horodatage de la première réponse du service TTS. Pour l'événement intent_recognized, il s'agit de l'horodatage du retour du résultat ASR après que l'utilisateur a fini de parler.

Rappel d'instruction

Lorsque le type d'event est instruction, le rappel indique qu'une balise d'instruction d'action spécifique a été déclenchée. Les rappels d'instruction pris en charge incluent :

Rappel d'instruction de transfert d'appel

Ce rappel est envoyé lorsque l'agent IA déclenche une balise d'action de transfert d'appel.

{
  "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"
  }
}

Exemple de serveur

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)

Codes d'état des événements de rappel

Status code	Callback event	Description
1001	Agent starts	L'agent démarre.
1002	Agent stops	L'agent s'arrête.
1003	Session starts	La session démarre.
4001	Concurrent agent routes exhausted	Le nombre maximal de routes d'agent simultanées a été atteint.
4002	Agent kicked from channel	Le système a expulsé l'agent du canal.
4003	Invalid agent token	Le jeton de l'agent est invalide.
4004	Agent stream subscription failed	L'agent n'a pas pu s'abonner au flux.
4005	Third-party ASR failed	Le service ASR tiers a échoué.
4006	Avatar service unavailable	Le service d'avatar est indisponible.
8001	Intent recognized	Intention reconnue.
8002	LLM data received	Données LLM reçues.
8003	TTS data received	Données TTS reçues.
10002	Dial status failed	La connexion de l'appel a échoué.
10003	Dial status connected	L'appel a été connecté avec succès.
10004	Hangup	L'appel a été raccroché.
10005	Forward call failed	La tentative de transfert d'appel a échoué.
10006	Forward call connected	L'appel transféré a été connecté avec succès.
11001	Forward call triggered	Le système a déclenché un transfert d'appel.