Transferir para um número | ElevenLabs Documentation

Visão geral

A ferramenta de sistema transfer_to_number permite que um agente da ElevenLabs transfira a chamada em andamento para um número de telefone ou URI SIP especificado quando determinadas condições são atendidas. Isso permite que os agentes encaminhem problemas complexos, solicitações específicas ou situações que exigem intervenção humana para um atendente ao vivo.

Este recurso oferece suporte a transferências por números da Twilio e troncos SIP. Quando acionado, o agente pode fornecer uma mensagem ao usuário enquanto ele aguarda e uma mensagem separada que resume a situação para o atendente humano que recebe a chamada.

A ferramenta de sistema transfer_to_number está disponível apenas para chamadas telefônicas e não está disponível no widget de chat.

Tipos de transferência

O sistema oferece suporte a três tipos de transferência:

Transferência em conferência: Comportamento padrão que liga para o destino e adiciona o participante a uma sala de conferência, depois remove o agente de IA para que permaneçam apenas o autor da chamada e o participante transferido. Ao usar a integração nativa da Twilio, oferece suporte a uma mensagem de transferência assistida (agent_message) lida para o atendente humano.
Transferência cega: Transfere a chamada diretamente para o destino sem uma mensagem de transferência assistida para o atendente humano. Preserva o ID do autor da chamada original. Disponível apenas quando o número de telefone do agente é importado pela integração nativa da Twilio.
Transferência SIP REFER: Usa o protocolo SIP REFER para transferir chamadas diretamente para o destino. Funciona com números de telefone e URIs SIP, mas está disponível apenas ao usar o protocolo SIP durante a conversa e exige que seu tronco SIP permita transferências via SIP REFER. Não oferece suporte a mensagens de transferência assistida.

Mensagens de transferência assistida (agent_message) estão disponíveis apenas quando o número de telefone do agente é importado pela integração nativa da Twilio . Transferências baseadas em SIP não oferecem suporte a mensagens de transferência assistida.

Transferências cegas estão disponíveis apenas quando o número de telefone do agente é importado pela integração nativa da Twilio e, no momento, precisam ser configuradas pelo editor JSON na interface. Selecione “Edit as JSON” na configuração da ferramenta de transferência e defina "transfer_type": "blind" para a regra de transferência desejada.

Objetivo: Transferir conversas sem interrupções para atendentes humanos quando a assistência de IA for insuficiente.

Condições de acionamento: o LLM deve chamar esta ferramenta quando:

Houver problemas complexos que exijam julgamento humano
O usuário solicitar explicitamente assistência humana
A IA atingir os limites de sua capacidade para a solicitação específica
Os protocolos de escalonamento forem acionados

Parâmetros:

reason (string, opcional): o motivo da transferência
transfer_number (string, obrigatório): o número de telefone para o qual transferir (deve corresponder aos números configurados)
client_message (string, obrigatório): mensagem lida ao cliente enquanto aguarda a transferência
agent_message (string, obrigatório): mensagem para o atendente humano que receberá a chamada

Formato da chamada de função:

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

Implementação: configure os números de telefone e as condições de transferência. Defina mensagens tanto para o cliente quanto para o atendente humano que receberá a chamada. Funciona com Twilio e troncos SIP.

Números para os quais é possível transferir

A transferência para humanos oferece suporte à transferência para números de telefone externos usando troncos SIP e números de telefone da Twilio.

Como habilitar a transferência para humanos

A transferência para humanos é configurada usando a ferramenta de sistema transfer_to_number.

Adicionar a ferramenta de transferência

Habilite a transferência para humanos selecionando a ferramenta de sistema transfer_to_number na configuração do seu agente, na aba Agent. Escolha “Transfer to Human” ao adicionar uma ferramenta.

Adicionar ferramenta de transferência para humanos — Selecione a ferramenta 'Transfer to Human'

Configurar a descrição da ferramenta (opcional)

Você pode fornecer uma descrição personalizada para orientar o LLM sobre quando acionar uma transferência. Se ficar em branco, será usada uma descrição padrão que abrange as regras de transferência definidas.

Descrição da ferramenta de transferência para humanos — Configurar descrição da ferramenta de transferência

Definir regras de transferência

Configure as regras específicas para transferir para números de telefone ou URIs SIP. Para cada regra, especifique:

Tipo de transferência: Escolha entre os métodos de transferência em conferência (padrão), cega ou SIP REFER
Tipo de número: Selecione Phone para números de telefone comuns ou SIP URI para endereços SIP
Número de telefone/URI SIP: O destino desejado no formato apropriado:
- Números de telefone: formato E.164 (por exemplo, +12125551234)
- URIs SIP: formato SIP (por exemplo, sip:1234567890@example.com)
Condição: Uma descrição em linguagem natural das circunstâncias em que a transferência deve ocorrer (por exemplo, “O usuário solicita explicitamente falar com um humano”, “O usuário precisa atualizar informações confidenciais da conta”).

O LLM usará essas condições, juntamente com a descrição da ferramenta, para decidir quando e para qual destino transferir.

Transferências SIP REFER exigem o protocolo SIP durante a conversa, e seu tronco SIP precisa permitir transferência via SIP REFER. Apenas o SIP REFER oferece suporte à transferência para um URI SIP.

Transferências cegas estão disponíveis apenas quando o número de telefone do agente é importado pela integração nativa da Twilio e precisam ser configuradas pelo editor JSON. O ID do autor da chamada original é preservado, mas nenhuma mensagem de transferência assistida é enviada ao atendente humano.

Configuração de regras de transferência para humanos — Definir regras de transferência com número de telefone e condição

Verifique se os destinos estão formatados corretamente:

Números de telefone: formato E.164 e associados a uma conta configurada corretamente
URIs SIP: formato SIP válido (sip:user@domain ou sips:user@domain)

Configurar cabeçalhos SIP REFER personalizados (opcional)

Ao usar transferências SIP REFER, você pode incluir cabeçalhos SIP personalizados para transmitir informações adicionais ao sistema que receberá a chamada.

Para cada cabeçalho personalizado, especifique:

Nome do cabeçalho: O nome do cabeçalho SIP (por exemplo, X-Customer-ID, X-Priority)
Valor do cabeçalho: O valor do cabeçalho, que pode ser um texto estático ou incluir variáveis dinâmicas

Cabeçalhos SIP REFER personalizados são incluídos apenas em transferências SIP REFER. Transferências em conferência não oferecem suporte a cabeçalhos personalizados.

Os cabeçalhos de sistema X-Conversation-ID e X-Caller-ID são incluídos automaticamente pela ElevenLabs e substituirão quaisquer cabeçalhos personalizados com os mesmos nomes (sem diferenciar maiúsculas de minúsculas).

Configurar Informações Usuário a Usuário (UUI) (opcional)

Transferências SIP REFER podem transportar Informações Usuário a Usuário (UUI), uma pequena carga útil entregue à plataforma receptora (por exemplo, Talkdesk ou Genesys Cloud) no parâmetro User-to-User do cabeçalho Refer-To. O UUI é enviado apenas em transferências SIP REFER para um destino URI SIP; destinos de número de telefone (tel:) não o transportam.

Configure o UUI por regra de transferência com o objeto uui:

data: A carga útil a enviar, como texto simples. A ElevenLabs a codifica em hexadecimal e acrescenta ;encoding=hex. Pode ser texto estático ou incluir variáveis dinâmicas. Máximo de 256 bytes (UTF-8), aplicado após a substituição das variáveis dinâmicas — em ASCII simples, são 256 caracteres; menos para caracteres de vários bytes.
protocol_discriminator: Um único octeto hexadecimal, por exemplo, 04. Inclua-o para plataformas que removem o primeiro octeto da carga útil; omita-o para plataformas que transmitem a carga útil sem alterações.
protocol_discriminator_mode: prefix (padrão) adiciona o octeto no início, produzindo 04<hex>;encoding=hex. pd_parameter o adiciona como um parâmetro separado, produzindo <hex>;pd=04;encoding=hex.

O Talkdesk transmite o valor sem alterações, então omita o discriminador de protocolo. O Genesys Cloud remove o primeiro octeto da carga útil, a menos que haja um discriminador. Portanto, inclua um protocol_discriminator. Consulte formatos de dados UUI do Genesys.

O limite de 256 bytes se aplica após a substituição das variáveis dinâmicas. Passe identificadores ou códigos curtos, como um ID de conta, e não texto livre, como um resumo completo da chamada, que excede o limite e é removido da transferência.

Para receber UUI em chamadas SIP recebidas, nenhuma configuração é necessária. Quando um INVITE recebido contém um cabeçalho User-to-User, seu valor é exposto ao agente como as variáveis dinâmicas {{sip_uui_raw}} e {{sip_uui_data}}. Consulte a referência SIP.

Configurar dígitos pós-discagem (opcional)

Os dígitos pós-discagem são tons DTMF transmitidos depois que o telefone se conecta ao destino da transferência. Isso é útil para inserir ramais ou navegar automaticamente por menus de URA (Unidade de Resposta Audível).

Para cada regra de transferência, você pode especificar uma string post_dial_digits contendo:

Dígitos (0-9): Tons DTMF padrão
w: Atraso de 0,5 segundo
W: Atraso de 1 segundo
* e #: Tons DTMF especiais

Por exemplo, ww1234 aguarda 1 segundo depois que a chamada é conectada e, em seguida, disca o ramal 1234.

Dígitos pós-discagem estão disponíveis apenas quando o número de telefone do agente (o número que inicia a transferência) é importado pela integração nativa da Twilio. O número de destino pode ser qualquer número de telefone.

Dígitos pós-discagem são compatíveis apenas com os tipos de transferência em conferência e cega. Transferências SIP REFER não oferecem suporte a dígitos pós-discagem.

Implementação com API

Você pode configurar a ferramenta de sistema transfer_to_number ao criar ou atualizar um agente pela API (Criar agente, Atualizar agente). A ferramenta permite especificar mensagens tanto para o cliente (usuário que está sendo transferido) quanto para o agente (atendente humano que recebe a chamada).

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