Transferir chamadas

Salve os números para os quais um agente pode transferir e encaminhe quem liga com uma transferência fria ou permaneça na linha e faça uma apresentação com uma transferência assistida.

Um agente transfere chamadas apenas para seus números de transferência: uma lista de nomes e números de telefone que você salva no agente. O prompt se refere a cada número pelo nome e informa quando transferir e se a transferência deve ser fria ou morna. O agente vê apenas os nomes, nunca os números. Um agente sem números de transferência não pode transferir chamadas.

Se o agente omitir o modo, a transferência será fria.

Configurar transferências#

No painel:

1. Abra Agentes de voz, selecione o agente e abra Config.
2. Em Números de transferência, adicione cada destino com um nome e um número de telefone, como Faturamento e +1 415 555 2671. Um agente pode ter até 50 números de transferência.
3. No prompt, faça referência a cada destino pelo nome e diga quando usá-lo e se deve usar o modo cold ou warm, por exemplo, "transfira dúvidas sobre faturamento para Faturamento". Não crie uma ferramenta personalizada.
4. Para transferências com consulta, escolha o que acontece Antes de conectar e, opcionalmente, o que o Resumo deve informar. Consulte Antes de conectar.
5. Se necessário, defina Avançado → Duração do toque de 5 a 120 segundos.
6. Selecione Implantar.

Com a API, use PATCH /v1/agents/{agent_id} para preparar transfer_destinations, o prompt e os opcionais warm_transfer_style, warm_transfer_briefing e ring_duration_seconds, depois use POST /v1/agents/{agent_id}/deploy:

{
  "transfer_destinations": [
    {"name": "Billing", "number": "+14155552671"},
    {"name": "Front desk", "number": "+19375551234"}
  ],
  "warm_transfer_style": "introduce",
  "warm_transfer_briefing": "The caller's name and what they need."
}

Uma gravação substitui toda a lista, e [] remove todos os números de transferência. Consulte a API de agentes para ver as regras dos campos e os erros de validação.

Nomes e números#

• Nome: de 1 a 60 caracteres, único no agente sem diferenciar maiúsculas de minúsculas. Esta é a palavra que o prompt usa.
• Número: um número de telefone completo. Números sem código de país são interpretados como números dos EUA, e todos os números são armazenados no formato E.164. Ramais e o intervalo fictício de 555-0100 a 555-0199 são recusados.
• Número variável: em vez de um número de telefone, uma variável de chamada isolada, como {{rep_phone}}. Ela é preenchida a partir das variáveis da chamada quando a chamada começa. Se a variável estiver ausente ou não for um número válido nessa chamada, uma transferência para esse nome será recusada.

Quais números uma chamada pode alcançar#

O que uma transferência pode alcançar depende de qual linha a transporta. Uma transferência transportada na linha do ThunderPhone pode alcançar apenas números dos EUA, excluindo números de tarifa premium e outros números de serviços especiais. Uma transferência transportada pela sua própria operadora pode alcançar qualquer número que você salvou.

Um número na sua própria operadora realiza chamadas de saída e pernas assistidas apenas pelo tronco de saída da própria conexão: conexões SIP manuais com um tronco de saída, conexões Twilio com chamadas de saída configuradas e conexões Telnyx. Sem esse tronco, o número não pode discar para fora, portanto oferece suporte apenas a transferência fria. Essas chamadas nunca usam como alternativa a linha do ThunderPhone.

Se sua organização não tiver números na sua própria operadora, salvar um número que a linha do ThunderPhone não consegue alcançar falhará com um erro. Depois que você conectar sua própria operadora, esses números serão salvos e marcados como funcionando apenas em transferências que sua operadora transporta (platform_ok: false na API). Um agente pode atender nos dois tipos de número, portanto a verificação é executada em cada chamada.

Antes de conectar#

Cada agente escolhe o que acontece quando a pessoa no destino atende uma transferência assistida. A configuração se aplica a todas as transferências assistidas realizadas pelo agente.

Use Apresentar na linha a menos que a pessoa que atende precise poder recusar chamadas ou deva saber sobre quem liga antes que essa pessoa entre na linha. Perguntar primeiro permite que ela recuse, mas mantém quem liga em espera por mais tempo, e correio de voz, silêncio ou uma recusa fazem quem liga voltar ao agente. Sussurrar fornece o contexto em particular sem perguntar; o correio de voz faz quem liga voltar ao agente.

A apresentação#

A configuração Apresentação define o que o agente diz à pessoa que atende sobre quem liga. Com Apresentar na linha, essa é a apresentação que ambos ouvem quando são conectados. Por padrão, ela é muito curta: quem está ligando e por quê, como "Olá, tenho Alex na linha sobre um pedido. Alex, pode falar." Com Perguntar primeiro, é a frase privada antes de quem liga ser conectado, terminando com a pergunta se a pessoa pode atender a chamada; a apresentação depois que ela aceita segue a mesma ideia. Com Sussurro, é a frase privada antes de quem liga ser conectado, como "Alex está ligando sobre um pedido atrasado, vou transferir agora." É uma afirmação, não uma pergunta.

Para alterar o que ele diz, escreva uma instrução de Apresentação no agente (warm_transfer_briefing, até 300 caracteres), por exemplo "O nome de quem liga, o número da conta e o que precisa." O agente segue essa instrução ao redigir cada apresentação ou briefing. Limite-se aos poucos fatos importantes: uma apresentação ou frase de Sussurro com mais de cerca de 40 palavras, ou um briefing de Perguntar primeiro com mais de cerca de 25 palavras, é substituído por uma frase padrão curta. Deixe em branco para usar o padrão.

O que acontece durante uma transferência assistida#

Com Introduzir na linha (o padrão):

1. O agente informa a quem liga que está iniciando a transferência. A gravação da chamada para, e o ThunderPhone começa imediatamente a ligar para o destino usando o número que está atendendo a chamada, enquanto o agente ainda está falando.
2. Enquanto o destino toca, quem liga aguarda brevemente em silêncio. Não há música de espera nesse estilo.
3. Assim que o destino atende, quem liga já está na linha e, portanto, ouve a saudação desde a primeira palavra.
4. Quando a pessoa que atendeu termina de falar e está aguardando uma resposta, o agente apresenta quem liga em uma ou duas frases que ambos ouvem, como "Olá, estou com Alex na linha sobre um pedido. Alex, pode falar." O agente determina isso pelo que a pessoa disse, e não por uma pausa: um aviso de gravação ou "aguarde" não indica o fim da vez dela; "Como posso ajudar?" indica. Se ela não disser nada, o agente começa após cerca de 3 segundos. Se ela começar a falar durante a apresentação, o agente para, deixa que ela termine e repete a apresentação. Após cerca de 15 segundos, por exemplo em um menu telefônico longo, o agente apresenta quem liga mesmo assim. Uma apresentação ausente ou excessivamente longa é substituída por uma frase padrão curta, falada no idioma da chamada.
5. O agente sai automaticamente; não diz mais nada.

Quem atender é conectado. Se for uma saudação de caixa postal, o agente não diz nada nela e sai, para que quem liga possa deixar uma mensagem. Se o destino não atender, estiver ocupado, não for possível completar a chamada ou a pessoa que atendeu desligar antes que a apresentação termine, o ThunderPhone encerra essa chamada e quem liga retorna ao agente. O agente recebe o resultado e continua a conversa original. Ele pode anotar uma mensagem, sugerir outra opção ou fazer uma transferência fria se quem liga ainda quiser uma.

Com Perguntar primeiro#

1. O agente informa a quem liga que está iniciando a transferência, e então a pessoa ouve música de espera enquanto o destino chama.
2. Quando o destino atende, o agente deixa a pessoa que atende concluir primeiro sua saudação, avaliada da mesma forma descrita acima. Se o anúncio de consentimento do agente estiver ativado, a pessoa que atende o ouve primeiro. Em seguida, o agente faz sua apresentação e pergunta se ela pode atender a chamada. Quem liga, em espera, não ouve nada disso.
3. A pessoa pode fazer perguntas, que o agente responde com base na conversa até o momento. Se ela aceitar, quem liga é conectado, o agente apresenta quem liga em uma ou duas frases que ambos ouvem e sai da chamada.
4. Se ela recusar, não responder ou a chamada cair na caixa postal, o ThunderPhone encerra essa chamada e tira quem liga da espera. O agente recebe o resultado, incluindo qualquer mensagem que a pessoa tenha pedido para transmitir, e continua com quem liga.

Nesse estilo, a transferência não interrompe a gravação da chamada. Se o agente grava chamadas, tanto a conversa privada com a pessoa que atende quanto a chamada conectada são gravadas. Se a gravação de chamadas estiver desativada para o agente, nenhuma das duas será gravada.

Com Sussurro#

1. O agente informa a quem liga que está iniciando a transferência, e então a pessoa ouve música de espera enquanto o destino chama.
2. Quando o destino atende, o agente aguarda a pessoa que atende concluir sua saudação. Se o anúncio de consentimento do agente estiver ativado, a pessoa que atende o ouve primeiro. Em seguida, o agente informa a ela, em uma frase curta, quem está ligando e por quê. Ele não pergunta se ela pode atender a chamada. Quem liga, em espera, não ouve nada disso.
3. Quem liga é conectado e o agente sai da chamada. Nada é dito na linha.
4. Se a chamada cair na caixa postal, o agente desliga e tira quem liga da espera. Se o destino não atender, estiver ocupado ou a chamada não puder ser realizada, quem liga também retorna ao agente. O agente recebe o resultado e continua com quem liga.

A gravação funciona como em Perguntar primeiro: se o agente grava chamadas, tanto a frase privada quanto a chamada conectada são gravadas.

Instrua o agente a transferir chamadas corretamente#

Inclua as regras de roteamento no prompt do agente e nomeie cada destino exatamente como aparece em Números de transferência. Não escreva números de telefone no prompt; o agente transfere pelo nome. Especifique o modo de transferência para cada rota e forneça ao agente uma alternativa para transferências assistidas que falharem.

Transfer policy
 
Confirm the caller's name and reason for calling before any transfer.
 
| Caller needs | Destination | Transfer mode |
| --- | --- | --- |
| A new purchase or plan change | Sales | warm |
| Help with an existing order | Order support | warm |
| The main office | Front desk | cold |
 
For a warm transfer:
- Keep the introduction to one or two short sentences: who is calling and
  why.
- Do not plan to speak after the introduction because you will be dropped.
- If the target does not answer or is busy, tell the caller what happened,
  then offer to take a message or try another route. Do not cold-transfer
  unless the caller asks.

O agente fornece estes campos ao chamar a ação integrada:

Não é necessário definir ou anexar uma ferramenta personalizada chamada transfer_call. A descrição da ação segue as configurações Antes de conectar e Resumo do agente, portanto o prompt não precisa repeti-las.

Quando uma transferência é recusada#

O ThunderPhone verifica cada transferência antes de realizá-la. Ele recusa uma transferência quando o nome não é um dos números de transferência do agente, quando um número variável não tem um valor válido nesta chamada ou quando uma transferência realizada pela linha do ThunderPhone alcançaria um número fora dos EUA ou um número de tarifa premium.

Uma transferência recusada não encerra a chamada. O agente não anuncia a transferência, recebe o motivo (incluindo a lista de nomes válidos quando o nome não correspondeu) e continua falando com quem liga. Indique no prompt o que ele deve fazer em vez disso, como anotar um recado. A recusa aparece como um erro de ferramenta no histórico da chamada.

Transferências com sussurro#

“Transferência com sussurro” é um nome comum no setor para uma transferência assistida em que o destino ouve um contexto privado antes de quem liga ser conectado, sem que seja perguntado se deseja aceitar a chamada. Essa é a configuração Sussurro em Antes de conectar.

Isso é diferente de POST /v1/calls/{id}/whisper. Esse endpoint permite que um membro da equipe ou proprietário envie orientações privadas em texto ao agente de IA durante uma chamada ao vivo. Ele não liga nem fornece contexto a um destino de transferência.

Requisitos, limites e testes#

Webhooks e motivos de encerramento#

A carga de conclusão registra o destino em transfer_number e usa um destes motivos de encerramento:

Uma tentativa com consulta não atendida, ocupada ou com falha não é uma transferência concluída. Quem liga retorna ao agente, portanto o motivo de encerramento final reflete o que encerra a chamada original.

Em uma transferência com consulta bem-sucedida, o evento de conclusão e o motivo de encerramento da chamada de IA são registrados quando a IA sai, logo após as partes serem conectadas. Com Apresentar na linha, a gravação cobre a chamada até a transferência e termina ali (recording_stopped_at); a conversa entre as duas pessoas não é gravada nem transcrita. Com Perguntar primeiro e Sussurrar, a gravação (quando o agente grava chamadas) continua até que a chamada conectada seja encerrada.

Consulte Webhooks de conclusão para ver a carga completa e o comportamento legado.

Solução de problemas#

A chamada cai quando o agente transfere#

Verifique o país de destino. Chamadas em números do ThunderPhone oferecem suporte a transferências apenas para números dos EUA. A operadora pode recusar uma transferência para outro país, desconectando quem liga, e a chamada ainda termina com ai_transfer. Para alcançar outros países, conecte sua própria operadora e encaminhe a chamada por um número importado dela. A operadora deve aceitar transferências de chamadas e permitir chamadas para esse país. Em um tronco SIP da Twilio, ative Transferências de chamadas e Ativar transferências de chamadas para a PSTN.

O agente faz uma transferência fria em vez de uma transferência assistida#

Verifique se a chamada está usando um número que pode fazer chamadas de saída: um número VoIP verificado e importado com roteamento de saída funcionando ou um número ThunderPhone com chamadas de saída aprovadas. O modo assistido é removido das opções da ferramenta para outros números e para sessões que não são de telefone. Também deixe o modo explícito na tabela de roteamento do prompt.

O destino nunca atende#

Confirme se o seu tronco VoIP pode fazer chamadas de saída para o destino e se as regras de autenticação e roteamento estão atualizadas. Verifique o número salvo em Números de transferência. Aumente ring_duration_seconds se 45 segundos forem pouco para uma transferência assistida.

O destino cai na caixa postal#

Com Apresentar na linha, quem liga é conectado a quem atender, incluindo uma saudação de caixa postal. O agente reconhece a saudação, não diz nada na caixa postal e desliga, e quem liga pode deixar uma mensagem. Com Perguntar primeiro e Sussurrar, o agente desliga ao chegar à caixa postal, e quem liga retorna ao agente. Se um destino costuma cair na caixa postal, forneça ao agente outra rota para ele no prompt.

Uma transferência fria aguarda antes de conectar#

Se você usa o webhook legado de URL única, verifique se ele retornou {"transfer_ready": false}. Quem liga ouve música de espera enquanto o ThunderPhone aguarda. Atualize o estado de prontidão para transferência da chamada quando o destino estiver preparado.

O agente diz que não consegue transferir#

Verifique se o agente tem números de transferência e se o prompt usa os mesmos nomes. Um agente sem números de transferência não tem nenhuma ação de transferência. Se a transferência usar a linha do ThunderPhone (consulte Quais números uma chamada pode alcançar), o destino deve ser um número dos EUA que não seja de tarifa premium. Para um número variável, verifique se as variáveis da chamada incluem um número de telefone válido para ele.

A implantação falha com um erro de número de transferência#

Cada implantação verifica novamente os números de transferência salvos. Um número fora dos EUA salvo enquanto sua organização tinha um número em sua própria operadora falha na verificação quando essa organização deixa de ter um. Remova o número ou conecte sua própria operadora novamente.

O sussurro para a equipe não inicia uma transferência#

O sussurro em chamadas ao vivo apenas orienta a IA. Adicione instruções de transferência ao prompt do agente e deixe que ele chame transfer_call. Consulte Monitorar chamadas ao vivo.