ConfigurarHerramientasHerramientas del sistema

Transferir a un número

Transfiere llamadas a números de teléfono externos o URI SIP según las condiciones definidas.

Resumen

La herramienta del sistema transfer_to_number permite que un agente de ElevenLabs transfiera la llamada en curso a un número de teléfono o URI SIP especificados cuando se cumplen ciertas condiciones. Esto permite a los agentes derivar problemas complejos, solicitudes específicas o situaciones que requieren intervención humana a un operador en directo.

Esta función admite transferencias mediante números de Twilio y troncales SIP. Cuando se activa, el agente puede proporcionar un mensaje al usuario mientras espera y otro mensaje independiente que resuma la situación para el operador humano que recibe la llamada.

La herramienta del sistema transfer_to_number solo está disponible para llamadas telefónicas y no está disponible en el widget de chat.

Tipos de transferencia

El sistema admite tres tipos de transferencias:

  • Transferencia en conferencia: Comportamiento predeterminado que llama al destino y añade al participante a una sala de conferencia; después elimina al agente de IA para que solo permanezcan la persona que llama y el participante transferido. Al usar la integración nativa de Twilio, admite un mensaje de transferencia asistida (agent_message) que se lee al operador humano.
  • Transferencia ciega: Transfiere la llamada directamente al destino sin un mensaje de transferencia asistida para el operador humano. Conserva el identificador de la persona que llama original. Solo está disponible cuando el número de teléfono del agente se importa mediante la integración nativa de Twilio.
  • Transferencia SIP REFER: Usa el protocolo SIP REFER para transferir llamadas directamente al destino. Funciona tanto con números de teléfono como con URI SIP, pero solo está disponible cuando se usa el protocolo SIP durante la conversación y requiere que tu troncal SIP permita transferencias mediante SIP REFER. No admite mensajes de transferencia asistida.

Los mensajes de transferencia asistida (agent_message) solo están disponibles cuando el número de teléfono del agente se importa mediante la integración nativa de Twilio . Las transferencias basadas en SIP no admiten mensajes de transferencia asistida.

Las transferencias ciegas solo están disponibles cuando el número de teléfono del agente se importa mediante la integración nativa de Twilio y actualmente deben configurarse mediante el editor JSON de la interfaz. Selecciona “Edit as JSON” en la configuración de la herramienta de transferencia y establece "transfer_type": "blind" para la regla de transferencia deseada.

Propósito: Transferir sin interrupciones las conversaciones a operadores humanos cuando la asistencia de IA no sea suficiente.

Condiciones de activación: El LLM debe llamar a esta herramienta cuando:

  • Haya problemas complejos que requieran criterio humano.
  • El usuario solicite explícitamente asistencia humana.
  • La IA alcance los límites de sus capacidades para la solicitud específica.
  • Se activen los protocolos de escalado.

Parámetros:

  • reason (cadena, opcional): El motivo de la transferencia.
  • transfer_number (cadena, obligatorio): El número de teléfono al que transferir (debe coincidir con los números configurados).
  • client_message (cadena, obligatorio): Mensaje que se leerá al cliente mientras espera la transferencia.
  • agent_message (cadena, obligatorio): Mensaje para el operador humano que recibe la llamada.

Formato de llamada a función:

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

Implementación: Configura los números de teléfono y las condiciones de transferencia. Define mensajes tanto para el cliente como para el operador humano que recibe la llamada. Funciona con Twilio y con SIP trunking.

Números a los que se puede transferir

La transferencia a una persona permite transferir a números de teléfono externos mediante troncales SIP y números de teléfono de Twilio.

Activar la transferencia a una persona

La transferencia a una persona se configura mediante la herramienta del sistema transfer_to_number.

1

Añade la herramienta de transferencia

Activa la transferencia a una persona seleccionando la herramienta del sistema transfer_to_number en la configuración de tu agente, dentro de la pestaña Agent. Elige “Transfer to Human” al añadir una herramienta.

Añadir herramienta de transferencia a una persona
Selecciona la herramienta 'Transfer to Human'
2

Configura la descripción de la herramienta (opcional)

Puedes proporcionar una descripción personalizada para indicar al LLM cuándo activar una transferencia. Si la dejas en blanco, se usará una descripción predeterminada que abarcará las reglas de transferencia definidas.

Descripción de la herramienta de transferencia a una persona
Configura la descripción de la herramienta de transferencia
3

Define las reglas de transferencia

Configura las reglas específicas para transferir a números de teléfono o URI SIP. Para cada regla, especifica:

  • Tipo de transferencia: Elige entre los métodos de transferencia en conferencia (predeterminado), ciega o SIP REFER
  • Tipo de número: Selecciona Phone para números de teléfono normales o SIP URI para direcciones SIP
  • Número de teléfono/URI SIP: El destino objetivo en el formato adecuado:
    • Números de teléfono: formato E.164 (por ejemplo, +12125551234)
    • URI SIP: formato SIP (por ejemplo, sip:1234567890@example.com)
  • Condición: Una descripción en lenguaje natural de las circunstancias en las que debe producirse la transferencia (por ejemplo, “El usuario solicita explícitamente hablar con una persona”, “El usuario necesita actualizar información confidencial de la cuenta”).

El LLM usará estas condiciones, junto con la descripción de la herramienta, para decidir cuándo y a qué destino transferir.

Las transferencias SIP REFER requieren el protocolo SIP durante la conversación y tu troncal SIP debe permitir transferencias mediante SIP REFER. Solo SIP REFER permite transferir a una URI SIP.

Las transferencias ciegas solo están disponibles cuando el número de teléfono del agente se importa mediante la integración nativa de Twilio y deben configurarse mediante el editor JSON. Se conserva el identificador de la persona que llama original, pero no se envía ningún mensaje de transferencia asistida al operador humano.

Configuración de reglas de transferencia a una persona
Define reglas de transferencia con número de teléfono y condición

Asegúrate de que los destinos tengan el formato correcto:

  • Números de teléfono: formato E.164 y asociados a una cuenta correctamente configurada
  • URI SIP: formato SIP válido (sip:user@domain o sips:user@domain)
4

Configura encabezados SIP REFER personalizados (opcional)

Al usar transferencias SIP REFER, puedes incluir encabezados SIP personalizados para enviar información adicional al sistema receptor.

Para cada encabezado personalizado, especifica:

  • Nombre del encabezado: El nombre del encabezado SIP (por ejemplo, X-Customer-ID, X-Priority)
  • Valor del encabezado: El valor del encabezado, que puede ser texto estático o incluir variables dinámicas

Los encabezados SIP REFER personalizados solo se incluyen en las transferencias SIP REFER. Las transferencias en conferencia no admiten encabezados personalizados.

ElevenLabs incluye automáticamente los encabezados del sistema X-Conversation-ID y X-Caller-ID, que sustituirán cualquier encabezado personalizado con los mismos nombres, sin distinguir entre mayúsculas y minúsculas.

5

Configura la información de usuario a usuario (UUI) (opcional)

Las transferencias SIP REFER pueden incluir información de usuario a usuario (UUI), una pequeña carga útil que se entrega a la plataforma receptora (por ejemplo, Talkdesk o Genesys Cloud) en el parámetro User-to-User del encabezado Refer-To. La UUI solo se envía en transferencias SIP REFER a un destino URI SIP; los destinos de número de teléfono (tel:) no la incluyen.

Configura la UUI para cada regla de transferencia con el objeto uui:

  • data: La carga útil que se enviará, como texto sin formato. ElevenLabs la codifica en hexadecimal y añade ;encoding=hex. Puede ser texto estático o incluir variables dinámicas. El máximo es de 256 bytes (UTF-8), aplicado después de sustituir las variables dinámicas; para ASCII simple son 256 caracteres y menos para caracteres multibyte.
  • protocol_discriminator: Un único octeto hexadecimal, por ejemplo, 04. Inclúyelo en plataformas que eliminan el primer octeto de la carga útil; omítelo en plataformas que transmiten la carga útil sin modificarla.
  • protocol_discriminator_mode: prefix (predeterminado) antepone el octeto y genera 04<hex>;encoding=hex. pd_parameter lo añade como parámetro independiente y genera <hex>;pd=04;encoding=hex.

Talkdesk transmite el valor sin modificarlo, así que omite el discriminador de protocolo. Genesys Cloud elimina el primer octeto de la carga útil salvo que haya un discriminador, así que incluye un protocol_discriminator. Consulta los formatos de datos UUI de Genesys.

El límite de 256 bytes se aplica después de sustituir las variables dinámicas. Envía identificadores o códigos cortos, como un ID de cuenta, no texto libre como un resumen completo de la llamada, que supera el límite y se elimina de la transferencia.

No se requiere configuración para recibir UUI en llamadas SIP entrantes. Cuando una INVITE entrante contiene un encabezado User-to-User, su valor se expone al agente como las variables dinámicas {{sip_uui_raw}} y {{sip_uui_data}}. Consulta la referencia de SIP.

6

Configura los dígitos posteriores a la marcación (opcional)

Los dígitos posteriores a la marcación son tonos DTMF que se retransmiten después de que el teléfono se conecte al destino de transferencia. Esto resulta útil para introducir extensiones o navegar automáticamente por menús IVR (respuesta de voz interactiva).

Para cada regla de transferencia, puedes especificar una cadena post_dial_digits que contenga:

  • Dígitos (0-9): Tonos DTMF estándar
  • w: Retraso de 0,5 segundos
  • W: Retraso de 1 segundo
  • * y #: Tonos DTMF especiales

Por ejemplo, ww1234 espera 1 segundo después de que se conecte la llamada y, a continuación, marca la extensión 1234.

Los dígitos posteriores a la marcación solo están disponibles cuando el número de teléfono del agente (el número que inicia la transferencia) se importa mediante la integración nativa de Twilio. El número de destino puede ser cualquier número de teléfono.

Los dígitos posteriores a la marcación solo se admiten para los tipos de transferencia en conferencia y ciega. Las transferencias SIP REFER no admiten dígitos posteriores a la marcación.

Implementación de la API

Puedes configurar la herramienta del sistema transfer_to_number al crear o actualizar un agente mediante la API (Crear agente, Actualizar agente). La herramienta permite especificar mensajes tanto para el cliente (usuario que se transfiere) como para el agente (operador humano que recibe la llamada).

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).