Transferência de Chamada

A ferramenta Call Transfer permite que seu agente de IA transfira uma chamada telefônica ativa para um número de telefone ou endpoint SIP. Você pode configurar um destino fixo, selecionar um com regras de contexto ordenadas, usar um template do contexto da chamada ou resolver o destino no momento da transferência chamando seu endpoint HTTP. Use esta ferramenta quando o chamador deve falar com um operador humano, departamento, fila de escalonamento, fila de suporte ou outro sistema telefônico.

Provedores suportados

A transferência de chamada está disponível para chamadas telefônicas que usam os provedores Twilio, Telnyx ou Asterisk ARI.

As Web Calls não suportam transferência de chamada.

Como funciona a transferência de chamada

Quando o LLM decide que uma transferência é necessária, ele chama a ferramenta Call Transfer. A Tig.ai resolve o destino, valida a configuração da transferência e então inicia a transferência do provedor. Para uma transferência bem-sucedida:

O agente chama a ferramenta Call Transfer.
A Tig.ai resolve o destino a partir da configuração estática, dos mapeamentos de contexto ordenados ou de um resolvedor HTTP dinâmico.
A Tig.ai opcionalmente reproduz uma mensagem pré-transferência.
A Tig.ai começa a discar o destino pelo provedor de telefonia.
O chamador ouve a música de espera enquanto a perna de destino está conectando.
Quando o destino atende, a Tig.ai conecta o chamador e encerra a participação do agente de IA.

A transferência é uma transferência às cegas. A Tig.ai atualmente não passa o contexto da conversa para o humano que recebe como parte da transferência.

Origem do destino

Você deve escolher uma origem de destino para cada ferramenta Call Transfer.

Estático / Template

Use esta opção quando o destino da transferência já é conhecido antes de a transferência acontecer. Os destinos estáticos podem ser:

Um número de telefone E.164 fixo, como +1234567890
Um endpoint SIP, como PJSIP/sales-queue
Um valor de template do contexto, como {{initial_context.transfer_destination}}

Esta é a opção mais simples para linhas de suporte fixas, departamentos fixos ou casos em que o destino é fornecido antes de a chamada começar.

Mapeamento de contexto

Use esta opção quando um conjunto finito de valores de contexto deve selecionar o destino da transferência. Você pode adicionar várias regras e ordená-las. A Tig.ai avalia as regras de cima para baixo e usa a primeira rota cujo valor corresponda, ignorando maiúsculas e minúsculas e espaços em branco ao redor. Para cada regra, informe um campo de contexto e um ou mais mapeamentos de valor para destino. Um campo sem prefixo, como department, lê gathered_context.department primeiro e recorre a initial_context.department quando o valor coletado está ausente. Você pode usar gathered_context.department ou initial_context.department quando quiser ler apenas um contexto. Os destinos mapeados e de fallback podem ser:

Um in-group do VICIdial, como sales
Um endpoint SIP, como PJSIP/1001
Um número PSTN E.164, como +1234567890
Um template de contexto, como {{initial_context.transfer_destination}}

A Tig.ai realiza a extração final de variáveis antes de avaliar os mapeamentos de contexto. Se nenhuma regra corresponder, ela usa o destino de fallback opcional. Se não houver fallback, ou se um template de destino selecionado for resolvido para um valor vazio, a transferência falha antes de discar e o agente pode continuar a chamada.

Resolvedor HTTP dinâmico

Use esta opção quando o destino precisar ser decidido durante a conversa. A Tig.ai envia uma requisição POST ao seu endpoint resolvedor antes de iniciar a transferência. Seu endpoint retorna o destino e pode retornar uma mensagem personalizada a reproduzir antes de discar. Casos de uso comuns:

Roteie por região, fuso horário ou idioma
Consulte a equipe de conta correta no seu sistema de clientes
Roteie por nível do cliente ou status da conta
Roteie por tipo de problema, idioma ou departamento
Use a lógica de negócios do seu backend em vez de codificar números na Tig.ai

Requisição do resolvedor dinâmico

O corpo da requisição do resolvedor é um objeto JSON simples. A Tig.ai o constrói a partir de:

Parâmetros de LLM: valores que o agente extrai da conversa quando chama a ferramenta de transferência
Parâmetros predefinidos: valores que a Tig.ai injeta a partir de valores fixos ou templates, como {{initial_context.account_id}} ou {{gathered_context.billing_issue_type}}

Se ambos definirem a mesma chave, os parâmetros predefinidos têm precedência. Exemplo de corpo de requisição:

{
  "account_id": "acct_123",
  "plan": "enterprise",
  "billing_issue_type": "invoice_dispute"
}

A Tig.ai não envia a transcrição completa da conversa ao resolvedor. Adicione os valores específicos de que você precisa como parâmetros de LLM ou parâmetros predefinidos.

Resposta do resolvedor dinâmico

Seu resolvedor deve retornar um objeto JSON com transfer_context.destination. transfer_context.custom_message é opcional.

{
  "transfer_context": {
    "destination": "+1234567890",
    "custom_message": "Please wait while I connect you with our enterprise billing team."
  }
}

Siga exatamente este formato de resposta. A Tig.ai lê chaves específicas da resposta do resolvedor. Na resolução dinâmica de transferência, uma resposta inválida não faz fallback silencioso: a transferência falha antes de discar.

Comportamento dos campos:

destination: Obrigatório. Número de telefone E.164 ou endpoint SIP.
custom_message: Opcional. Se retornado, esta mensagem é reproduzida antes de a transferência do provedor começar.

Se o resolvedor falhar, atingir o timeout, retornar JSON inválido ou omitir transfer_context.destination, a transferência falha graciosamente e o agente pode continuar atendendo o chamador.

Configuração do resolvedor dinâmico

Ao usar um resolvedor dinâmico, configure:

Resolver URL: endpoint HTTPS ou HTTP que a Tig.ai chama com POST
Resolver Timeout: quanto tempo a Tig.ai espera pela resposta do resolvedor
Resolver Wait Message: mensagem opcional falada enquanto a Tig.ai espera, como “Um momento enquanto encontro a equipe certa.”
LLM Parameters: valores que o agente deve extrair da conversa, como billing_issue_type ou requested_department
Preset Parameters: valores injetados pela Tig.ai a partir do contexto ou de valores fixos
Custom Headers: cabeçalhos estáticos enviados ao seu endpoint resolvedor
Credential: credencial salva opcional usada para autenticar a requisição ao resolvedor

O resolvedor dinâmico usa apenas POST. Se você precisar de comportamento personalizado no backend, implemente-o atrás do seu endpoint resolvedor e retorne o formato transfer_context esperado.

Mensagens pré-transferência

A Call Transfer suporta uma configuração comum de mensagem pré-transferência para destinos estáticos, mapeados por contexto e dinâmicos. Para transferências estáticas:

A Tig.ai resolve o destino estático ou de template.
A Tig.ai reproduz a mensagem pré-transferência configurada, se houver.
A Tig.ai inicia a transferência do provedor.

Para transferências dinâmicas:

A Tig.ai pode reproduzir a mensagem de espera do resolvedor enquanto chama seu resolvedor.
Se o resolvedor retornar custom_message, a Tig.ai reproduz essa mensagem.
Se o resolvedor não retornar custom_message, a Tig.ai usa a mensagem pré-transferência configurada.
A Tig.ai inicia a transferência do provedor.

O custom_message do resolvedor substitui a mensagem pré-transferência configurada para aquela tentativa de transferência.

Timeout da transferência

O timeout da transferência é o tempo máximo que a Tig.ai espera o destino atender depois que a transferência do provedor começa. Esse timeout se aplica a transferências estáticas, mapeadas por contexto e dinâmicas. O timeout do resolvedor é separado. Ele controla somente quanto tempo a Tig.ai espera pelo seu resolvedor HTTP antes de a discagem começar.

Formatos de destino

Twilio e Telnyx

Use números de telefone E.164:

+1234567890

O número deve ser alcançável a partir do seu provedor de telefonia.

Asterisk ARI

Use endpoints SIP:

PJSIP/sales-queue
SIP/1001

As transferências do Asterisk ARI funcionam apenas com endpoints SIP configurados no seu servidor Asterisk. Números de telefone externos exigem configuração de tronco PSTN no seu ambiente Asterisk.

Exemplo: rotear chamadas de faturamento empresarial

Use esta configuração quando o agente identifica um problema de faturamento e seu backend decide se deve encaminhar o chamador para o faturamento padrão, faturamento empresarial ou cobranças (collections). Configure os parâmetros de LLM:

[
  {
    "name": "billing_issue_type",
    "type": "string",
    "description": "The billing issue the caller needs help with, such as invoice_dispute, payment_failed, refund_request, or plan_change.",
    "required": true
  },
  {
    "name": "requested_department",
    "type": "string",
    "description": "The department the caller is asking for, if they explicitly mention one.",
    "required": false
  }
]

Configure os parâmetros predefinidos:

[
  {
    "name": "account_id",
    "type": "string",
    "value_template": "{{initial_context.account_id}}",
    "required": true
  },
  {
    "name": "plan",
    "type": "string",
    "value_template": "{{initial_context.plan}}",
    "required": true
  }
]

Seu resolvedor recebe:

{
  "billing_issue_type": "invoice_dispute",
  "requested_department": "billing",
  "account_id": "acct_123",
  "plan": "enterprise"
}

Seu resolvedor retorna:

{
  "transfer_context": {
    "destination": "+18005550199",
    "custom_message": "Please wait while I connect you with our enterprise billing team."
  }
}

Práticas recomendadas

Mantenha a latência do resolvedor baixa. Mire em 2 a 3 segundos.
Use uma mensagem de espera do resolvedor se o resolvedor puder levar um tempo perceptível.
Envie apenas os parâmetros de que seu resolvedor precisa.
Prefira parâmetros predefinidos para valores já disponíveis no initial_context ou gathered_context.
Coloque as regras de mapeamento de contexto mais específicas primeiro e configure um fallback apenas quando for seguro para todo valor sem correspondência.
Torne as descrições dos parâmetros de LLM explícitas para que o agente saiba o que extrair.
Teste tanto o caminho de transferência bem-sucedida quanto o de falha do resolvedor antes de ir ao ar.
Mantenha a validação de destino e a lógica de roteamento no seu backend quando o roteamento depender de dados de conta ou regras de negócio.

Solução de problemas

A ferramenta de transferência não é chamada

Verifique se a ferramenta está anexada ao nó correto e se o prompt do nó diz claramente ao agente quando transferir.

A transferência estática falha sem destino

O modo estático exige um destino configurado. Use um destino fixo ou um template que seja resolvido para um valor não vazio.

A transferência dinâmica falha antes de discar

Verifique a resposta do resolvedor. Ela deve incluir:

{
  "transfer_context": {
    "destination": "+1234567890"
  }
}

Também verifique a URL do resolvedor, os cabeçalhos de autenticação, a credencial e o timeout.

O resolvedor recebe parâmetros ausentes

Confirme se o parâmetro está configurado como:

um parâmetro de LLM, se o agente deve extraí-lo da conversa
um parâmetro predefinido, se a Tig.ai deve injetá-lo a partir do contexto

Para valores de contexto conhecidos, prefira parâmetros predefinidos como {{initial_context.account_id}} ou {{gathered_context.billing_issue_type}}.

O destino não conecta

Verifique se o número de telefone ou endpoint SIP é válido e alcançável a partir do provedor de telefonia configurado.

Começando

Crie seu Primeiro Agente

Conceitos Principais

Configurações

Construtor de Agentes de Voz

Telefonia

Gerencie seu workspace

Transferência de Chamada

Provedores suportados

Como funciona a transferência de chamada

Origem do destino

Estático / Template

Mapeamento de contexto

Resolvedor HTTP dinâmico

Requisição do resolvedor dinâmico

Resposta do resolvedor dinâmico

Configuração do resolvedor dinâmico

Mensagens pré-transferência

Timeout da transferência

Formatos de destino

Twilio e Telnyx

Asterisk ARI

Exemplo: rotear chamadas de faturamento empresarial

Práticas recomendadas

Solução de problemas

A ferramenta de transferência não é chamada

A transferência estática falha sem destino

A transferência dinâmica falha antes de discar

O resolvedor recebe parâmetros ausentes

O destino não conecta

​Provedores suportados

​Como funciona a transferência de chamada

​Origem do destino

​Estático / Template

​Mapeamento de contexto

​Resolvedor HTTP dinâmico

​Requisição do resolvedor dinâmico

​Resposta do resolvedor dinâmico

​Configuração do resolvedor dinâmico

​Mensagens pré-transferência

​Timeout da transferência

​Formatos de destino

​Twilio e Telnyx

​Asterisk ARI

​Exemplo: rotear chamadas de faturamento empresarial

​Práticas recomendadas

​Solução de problemas

​A ferramenta de transferência não é chamada

​A transferência estática falha sem destino

​A transferência dinâmica falha antes de discar

​O resolvedor recebe parâmetros ausentes

​O destino não conecta

Provedores suportados

Como funciona a transferência de chamada

Origem do destino

Estático / Template

Mapeamento de contexto

Resolvedor HTTP dinâmico

Requisição do resolvedor dinâmico

Resposta do resolvedor dinâmico

Configuração do resolvedor dinâmico

Mensagens pré-transferência

Timeout da transferência

Formatos de destino

Twilio e Telnyx

Asterisk ARI

Exemplo: rotear chamadas de faturamento empresarial

Práticas recomendadas

Solução de problemas

A ferramenta de transferência não é chamada

A transferência estática falha sem destino

A transferência dinâmica falha antes de discar

O resolvedor recebe parâmetros ausentes

O destino não conecta