Transférer vers un numéro | ElevenLabs Documentation

Vue d’ensemble

L’outil système transfer_to_number permet à un agent ElevenLabs de transférer l’appel en cours vers un numéro de téléphone ou un URI SIP spécifié lorsque certaines conditions sont remplies. Les agents peuvent ainsi transmettre les problèmes complexes, les demandes spécifiques ou les situations nécessitant une intervention humaine à un opérateur en direct.

Cette fonctionnalité prend en charge les transferts via Twilio et les numéros de trunk SIP. Lorsqu’il est déclenché, l’agent peut fournir un message à l’utilisateur pendant son attente, ainsi qu’un message distinct résumant la situation pour l’opérateur humain qui reçoit l’appel.

L’outil système transfer_to_number est disponible uniquement pour les appels téléphoniques et n’est pas disponible dans le widget de chat.

Types de transfert

Le système prend en charge trois types de transfert :

Transfert par conférence : comportement par défaut qui appelle la destination et ajoute le participant à une conférence, puis retire l’agent IA afin que seuls l’appelant et le participant transféré restent présents. Avec l’intégration Twilio native, prend en charge un message de transfert assisté (agent_message) lu à l’opérateur humain.
Transfert aveugle : transfère l’appel directement vers la destination, sans message de transfert assisté pour l’opérateur humain. Conserve l’identifiant de l’appelant d’origine. Disponible uniquement lorsque le numéro de téléphone de l’agent est importé via l’intégration Twilio native.
Transfert SIP REFER : utilise le protocole SIP REFER pour transférer les appels directement vers la destination. Fonctionne avec les numéros de téléphone comme avec les URI SIP, mais est disponible uniquement lorsque le protocole SIP est utilisé pendant la conversation et exige que votre trunk SIP autorise le transfert via SIP REFER. Ne prend pas en charge les messages de transfert assisté.

Les messages de transfert assisté (agent_message) sont disponibles uniquement lorsque le numéro de téléphone de l’agent est importé via l’intégration Twilio native. Les transferts basés sur SIP ne prennent pas en charge les messages de transfert assisté.

Les transferts aveugles sont disponibles uniquement lorsque le numéro de téléphone de l’agent est importé via l’intégration Twilio native et doivent actuellement être configurés via l’éditeur JSON dans l’interface. Sélectionnez « Edit as JSON » dans la configuration de l’outil de transfert, puis définissez "transfer_type": "blind" pour la règle de transfert souhaitée.

Objectif : Transférer de manière fluide les conversations à des opérateurs humains lorsque l’assistance de l’IA ne suffit pas.

Conditions de déclenchement : le LLM doit appeler cet outil lorsque :

Des problèmes complexes nécessitent un jugement humain
L’utilisateur demande explicitement une assistance humaine
L’IA atteint les limites de ses capacités pour la demande concernée
Les protocoles d’escalade sont déclenchés

Paramètres :

reason (chaîne, facultatif) : la raison du transfert
transfer_number (chaîne, obligatoire) : le numéro de téléphone vers lequel transférer l’appel, il doit correspondre aux numéros configurés
client_message (chaîne, obligatoire) : message lu au client pendant l’attente du transfert
agent_message (chaîne, obligatoire) : message destiné à l’opérateur humain qui reçoit l’appel

Format d’appel de fonction :

{
  "type": "function",
  "function": {
    "name": "transfer_to_number",
    "arguments": "{\"reason\": \"Complex billing issue\", \"transfer_number\": \"+15551234567\", \"client_message\": \"I'm transferring you to a billing specialist who can help with your account.\", \"agent_message\": \"Customer has a complex billing dispute about order #12345 from last month.\"}"
  }
}

Mise en œuvre : configurez les numéros de téléphone et les conditions de transfert. Définissez les messages destinés au client et à l’opérateur humain qui reçoit l’appel. Compatible avec Twilio et le trunking SIP.

Numéros vers lesquels transférer

Le transfert vers un humain permet de transférer vers des numéros de téléphone externes à l’aide du trunking SIP et des numéros de téléphone Twilio.

Activer le transfert vers un humain

Le transfert vers un humain se configure avec l’outil système transfer_to_number.

Ajouter l’outil de transfert

Activez le transfert vers un humain en sélectionnant l’outil système transfer_to_number dans la configuration de votre agent, sous l’onglet Agent. Choisissez « Transfer to Human » lors de l’ajout d’un outil.

Configurer la description de l’outil (facultatif)

Vous pouvez fournir une description personnalisée pour indiquer au LLM quand déclencher un transfert. Si vous la laissez vide, une description par défaut couvrant les règles de transfert définies sera utilisée.

Description de l’outil de transfert vers un humain — Configurer la description de l’outil de transfert

Définir les règles de transfert

Configurez les règles spécifiques de transfert vers des numéros de téléphone ou des URI SIP. Pour chaque règle, indiquez :

Type de transfert : choisissez entre les méthodes de transfert par conférence (par défaut), aveugle ou SIP REFER
Type de numéro : sélectionnez Téléphone pour les numéros de téléphone classiques ou URI SIP pour les adresses SIP
Numéro de téléphone/URI SIP : la destination cible au format approprié :
- Numéros de téléphone : format E.164 (par exemple, +12125551234)
- URI SIP : format SIP (par exemple, sip:1234567890@example.com)
Condition : description en langage naturel des circonstances dans lesquelles le transfert doit avoir lieu (par exemple, « L’utilisateur demande explicitement à parler à un humain », « L’utilisateur doit mettre à jour des informations de compte sensibles »).

Le LLM utilisera ces conditions, ainsi que la description de l’outil, pour déterminer quand effectuer le transfert et vers quelle destination.

Les transferts SIP REFER nécessitent le protocole SIP pendant la conversation et votre trunk SIP doit autoriser le transfert via SIP REFER. Seul SIP REFER prend en charge le transfert vers un URI SIP.

Les transferts aveugles sont disponibles uniquement lorsque le numéro de téléphone de l’agent est importé via l’intégration Twilio native et doivent être configurés via l’éditeur JSON. L’identifiant de l’appelant d’origine est conservé, mais aucun message de transfert assisté n’est envoyé à l’opérateur humain.

Configuration des règles de transfert vers un humain — Définir des règles de transfert avec un numéro de téléphone et une condition

Vérifiez que les destinations sont correctement formatées :

Numéros de téléphone : format E.164 et associés à un compte correctement configuré
URI SIP : format SIP valide (sip:user@domain ou sips:user@domain)

Configurer des en-têtes SIP REFER personnalisés (facultatif)

Lorsque vous utilisez des transferts SIP REFER, vous pouvez inclure des en-têtes SIP personnalisés afin de transmettre des informations supplémentaires au système destinataire.

Pour chaque en-tête personnalisé, indiquez :

Nom de l’en-tête : le nom de l’en-tête SIP (par exemple, X-Customer-ID, X-Priority)
Valeur de l’en-tête : la valeur de l’en-tête, qui peut être du texte statique ou inclure des variables dynamiques

Les en-têtes SIP REFER personnalisés sont inclus uniquement avec les transferts SIP REFER. Les transferts par conférence ne prennent pas en charge les en-têtes personnalisés.

Les en-têtes système X-Conversation-ID et X-Caller-ID sont automatiquement inclus par ElevenLabs et remplacent tout en-tête personnalisé portant le même nom, sans distinction entre majuscules et minuscules.

Configurer les informations utilisateur à utilisateur (UUI) (facultatif)

Les transferts SIP REFER peuvent transporter des informations utilisateur à utilisateur (UUI), une petite charge utile transmise à la plateforme destinataire, par exemple Talkdesk ou Genesys Cloud, dans le paramètre User-to-User de l’en-tête Refer-To. Les UUI sont envoyées uniquement lors des transferts SIP REFER vers une destination URI SIP ; les destinations avec numéro de téléphone (tel:) ne les transmettent pas.

Configurez les UUI pour chaque règle de transfert avec l’objet uui :

data : la charge utile à envoyer, en texte brut. ElevenLabs l’encode en hexadécimal et ajoute ;encoding=hex. Elle peut être du texte statique ou inclure des variables dynamiques. Maximum de 256 octets (UTF-8), appliqué après substitution des variables dynamiques. Pour du texte ASCII simple, cela correspond à 256 caractères, moins pour les caractères sur plusieurs octets.
protocol_discriminator : un seul octet hexadécimal, par exemple 04. Incluez-le pour les plateformes qui suppriment le premier octet de la charge utile ; omettez-le pour celles qui transmettent la charge utile telle quelle.
protocol_discriminator_mode : prefix (par défaut) ajoute l’octet au début et produit 04<hex>;encoding=hex. pd_parameter l’ajoute comme paramètre distinct et produit <hex>;pd=04;encoding=hex.

Talkdesk transmet la valeur sans la modifier, omettez donc le discriminateur de protocole. Genesys Cloud supprime le premier octet de la charge utile sauf si un discriminateur est présent, incluez donc un protocol_discriminator. Consultez les formats de données UUI de Genesys.

La limite de 256 octets s’applique après la substitution des variables dynamiques. Transmettez des identifiants ou des codes courts, comme un ID de compte, plutôt que du texte libre tel qu’un résumé complet de l’appel, qui dépasse la limite et est exclu du transfert.

Aucune configuration n’est requise pour recevoir des UUI lors d’appels SIP entrants. Lorsqu’un INVITE entrant contient un en-tête User-to-User, sa valeur est exposée à l’agent sous forme des variables dynamiques {{sip_uui_raw}} et {{sip_uui_data}}. Consultez la référence SIP.

Configurer les chiffres post-numérotation (facultatif)

Les chiffres post-numérotation sont des tonalités DTMF relayées après la connexion téléphonique à la destination du transfert. Ils permettent notamment de saisir automatiquement des postes ou de naviguer dans des menus SVI (serveur vocal interactif).

Pour chaque règle de transfert, vous pouvez indiquer une chaîne post_dial_digits contenant :

Chiffres (0-9) : tonalités DTMF standard
w : délai de 0,5 seconde
W : délai d’une seconde
* et # : tonalités DTMF spéciales

Par exemple, ww1234 attend une seconde après la connexion de l’appel, puis compose le poste 1234.

Les chiffres post-numérotation sont disponibles uniquement lorsque le numéro de téléphone de l’agent, c’est-à-dire le numéro qui initie le transfert, est importé via l’intégration Twilio native. Le numéro de destination peut être n’importe quel numéro de téléphone.

Les chiffres post-numérotation sont pris en charge uniquement pour les types de transfert par conférence et aveugle. Les transferts SIP REFER ne prennent pas en charge les chiffres post-numérotation.

Implémentation via l’API

Vous pouvez configurer l’outil système transfer_to_number lors de la création ou de la mise à jour d’un agent via l’API (Créer un agent, Mettre à jour un agent). L’outil permet de spécifier des messages à la fois pour le client, c’est-à-dire l’utilisateur transféré, et pour l’agent, c’est-à-dire l’opérateur humain qui reçoit l’appel.

from elevenlabs import AgentConfig, ConversationalConfig, ElevenLabs
elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")
# Define transfer rules
transfer_rules = [
    {
        "transfer_destination": {"type": "phone", "phone_number": "+15551234567"},
        "condition": "When the user asks for billing support.",
        "transfer_type": "conference",
        # Wait 1s, then dial extension 1234 (native Twilio only)
        "post_dial_digits": {"type": "static", "value": "ww1234"},
    },
    {
        "transfer_destination": {"type": "phone", "phone_number": "+15559876543"},
        "condition": "When the user asks to speak to a human.",
        # Native Twilio integration only, preserves caller ID, no warm transfer message
        "transfer_type": "blind",
    },
    {
        "transfer_destination": {"type": "sip_uri", "sip_uri": "sip:support@example.com"},
        "condition": "When the user requests to file a formal complaint.",
        "transfer_type": "sip_refer",
        "custom_sip_headers": [
            {"type": "static", "key": "X-Department", "value": "complaints"},
            {"type": "static", "key": "X-Priority", "value": "high"},
            # Use "dynamic" to read the value from a dynamic variable
            {"type": "dynamic", "key": "X-Customer-ID", "value": "{{customer_id}}"},
        ],
        "uui": {
            "data": "account_id={{customer_id}}",
            "protocol_discriminator": "04",           # Genesys Cloud; omit for Talkdesk
            "protocol_discriminator_mode": "prefix",  # or "pd_parameter"
        },
    },
]
response = elevenlabs.conversational_ai.agents.create(
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            first_message="Hi, how can I help you today?",
            prompt={
                "prompt": "You are a helpful assistant.",
                "built_in_tools": {
                    "transfer_to_number": {
                        "type": "system",
                        "name": "transfer_to_number",
                        # Optional custom description
                        "description": "Transfer the user to a human operator based on their request.",
                        "params": {
                            "system_tool_type": "transfer_to_number",
                            "transfers": transfer_rules,
                        },
                    }
                },
            },
        ),
    ),
)
# Note: When the LLM decides to call this tool, it needs to provide:
# - transfer_number: The phone number to transfer to (must match one defined in rules).
# - client_message: Message read to the user during transfer.
# - agent_message: Message read to the human operator receiving the call (native Twilio integration only, not used for blind transfers or SIP).