> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Transférer vers un numéro ## 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. > **Note** > > 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](/docs/fr/eleven-agents/phone-numbers/twilio-integration/native-integration), 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](/docs/fr/eleven-agents/phone-numbers/twilio-integration/native-integration). * **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é. > **Note** > > 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](/docs/fr/eleven-agents/phone-numbers/twilio-integration/native-integration). Les transferts basés sur SIP > ne prennent pas en charge les messages de transfert assisté. > **Note** > > 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](/docs/fr/eleven-agents/phone-numbers/twilio-integration/native-integration) 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** : ```json { "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](/docs/fr/eleven-agents/phone-numbers/sip-trunking) et des [numéros de téléphone Twilio](/docs/fr/eleven-agents/phone-numbers/twilio-integration/native-integration). ## 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. ![Ajouter l’outil de transfert vers un humain](/docs/_fern-img/1b0a0985dd32cab9532b38b80aaa90873b4076bb26e7a47ce2e12832dd78ea45.webp) #### 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](/docs/_fern-img/23b446030f915db9a10693153e44f95ab59c313e01df2b95291e40e12f2f4bde.webp) #### 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](mailto: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. > **Note** > > 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. > **Note** > > 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](/docs/fr/eleven-agents/phone-numbers/twilio-integration/native-integration) 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](/docs/_fern-img/86e46148dc133fe68e6b517752d38bf493bef8347fee91a577e9f27600bafa5d.webp) > **Note** > > 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](/docs/fr/eleven-agents/customization/personalization/dynamic-variables) > **Note** > > 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. > **Warning** > > 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)](https://www.rfc-editor.org/rfc/rfc7433), 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](/docs/fr/eleven-agents/customization/personalization/dynamic-variables). 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;encoding=hex`. `pd_parameter` l’ajoute comme paramètre distinct et produit `;pd=04;encoding=hex`. > **Note** > > 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](https://help.genesys.cloud/articles/uui-data-formats/). > **Warning** > > 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](/docs/fr/eleven-agents/phone-numbers/sip-reference). #### 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. > **Note** > > 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](/docs/fr/eleven-agents/phone-numbers/twilio-integration/native-integration). Le numéro de destination peut être n’importe quel numéro de téléphone. > **Note** > > 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](/docs/fr/api-reference/agents/create), [Mettre à jour un agent](/docs/fr/api-reference/agents/update)). 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. ```python 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). ``` ```javascript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient({ apiKey: "YOUR_API_KEY", }); await elevenlabs.conversationalAi.agents.create({ conversationConfig: { agent: { firstMessage: "Hi, how can I help you today?", prompt: { prompt: "You are a helpful assistant.", builtInTools: { transferToNumber: { type: "system", name: "transfer_to_number", description: "Transfer the user to a human operator based on their request.", // Optional custom description params: { systemToolType: "transfer_to_number", transfers: [ { transferDestination: { type: "phone", phoneNumber: "+15551234567" }, condition: "When the user asks for billing support.", transferType: "conference", // Wait 1s, then dial extension 1234 (native Twilio only) postDialDigits: { type: "static", value: "ww1234" }, }, { transferDestination: { type: "phone", phoneNumber: "+15559876543" }, condition: "When the user asks to speak to a human.", // Native Twilio only, preserves caller ID, no warm transfer message transferType: "blind", }, { transferDestination: { type: "sip_uri", sipUri: "sip:support@example.com" }, condition: "When the user requests to file a formal complaint.", transferType: "sip_refer", customSipHeaders: [ { 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}}", protocolDiscriminator: "04", // Genesys Cloud; omit for Talkdesk protocolDiscriminatorMode: "prefix", // or "pd_parameter" }, }, ], }, }, }, }, }, }, }); // 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). ```