Pre-Call Data Fetch

Busque dados do cliente do seu CRM ou ERP antes de a chamada começar, para que seu agente de voz possa cumprimentar os chamadores pelo nome e consultar os detalhes da conta.

O Pre-Call Data Fetch permite enriquecer o contexto da chamada com dados externos antes de o agente de voz começar a falar. Configure-o no nó Start Call para todas as chamadas ou apenas chamadas recebidas. Enquanto a resposta está carregando, o chamador ouve um tom de ring-back. Quando os dados chegam, eles são mesclados no contexto inicial da chamada e ficam disponíveis como variáveis de template nos seus prompts e saudações.

​

Como funciona

1. Uma chamada chega.
2. A Tig.ai envia uma requisição POST ao seu endpoint configurado com um payload padronizado.
3. O chamador ouve um tom de ring-back enquanto espera pela resposta.
4. Sua API responde com um objeto JSON contendo um objeto initial_context.
5. As variáveis são mescladas no contexto inicial da chamada.
6. O agente de voz começa com acesso total aos dados buscados por meio da sintaxe {{variable_name}}.

​

Configuração

Abra o editor do nó Start Call e expanda as Advanced Settings. Escolha um modo de Pre-Call Data Fetch e configure o endpoint quando o modo não estiver desativado:

Campo	Descrição
Pre-Call Data Fetch	Disabled, Always ou Inbound calls only.
Endpoint URL	A URL para a qual a Tig.ai enviará a requisição POST.
Authentication	Credencial opcional para autenticar a requisição. Suporta API key, bearer token, autenticação básica e cabeçalho personalizado.

​

Formato da requisição

A Tig.ai envia uma requisição POST com o seguinte payload JSON:

{
  "event": "call_inbound",
  "call_inbound": {
    "agent_id": 123,
    "from_number": "[phone]",
    "to_number": "[phone]"
  }
}

Campo	Descrição
event	Sempre "call_inbound".
call_inbound.agent_id	O ID do workflow (agente).
call_inbound.from_number	O número de telefone do chamador (caller_number do contexto inicial).
call_inbound.to_number	O número de telefone chamado (called_number do contexto inicial).

O cabeçalho Content-Type é definido como application/json. Se você configurou uma credencial, o cabeçalho de autenticação correspondente é incluído.

​

Formato esperado da resposta

Sua API deve retornar um objeto JSON com um código de status 2xx. As variáveis a injetar no contexto da chamada devem ser colocadas dentro da chave initial_context:

{
  "call_inbound": {
    "initial_context": {
      "customer_name": "Jane Doe",
      "account_status": "active",
      "loyalty_tier": "gold",
      "open_tickets": 2
    }
  }
}

Você também pode colocar initial_context no nível superior:

{
  "initial_context": {
    "customer_name": "Jane Doe",
    "account_status": "active"
  }
}

A chave legada dynamic_variables ainda é aceita como um alias substituto de initial_context, para que as integrações existentes continuem funcionando sem alterações. Use initial_context para novas integrações. Se uma resposta contiver ambas as chaves, initial_context tem precedência.

Depois que a resposta é recebida, você pode referenciar esses valores em qualquer lugar em que variáveis de template sejam suportadas:

• Saudação: Hello {{customer_name}}, thank you for calling!
• Prompt: The customer is a {{loyalty_tier}} member with {{open_tickets}} open support tickets.

Se a resposta não for um objeto JSON válido, não contiver initial_context (ou o legado dynamic_variables), ou a requisição falhar ou atingir o timeout, a chamada prossegue normalmente sem o contexto adicional. A busca pré-chamada nunca bloqueia ou falha uma chamada.

​

Variáveis aninhadas

Se o seu initial_context contiver objetos aninhados, você pode acessá-los usando a notação de ponto:

{
  "call_inbound": {
    "initial_context": {
      "customer": {
        "name": "Jane Doe",
        "address": {
          "city": "Los Angeles"
        }
      }
    }
  }
}

Acesse nos prompts como {{customer.name}} e {{customer.address.city}}.

​

Timeout

A requisição tem um timeout de 10 segundos. Se sua API não responder dentro dessa janela, a chamada prossegue sem os dados buscados. Projete seu endpoint para responder o mais rápido possível para minimizar a duração do tom de ring-back.

​

Testando com chamadas de teste

Quando uma chamada telefônica real chega, as variáveis de contexto caller_number e called_number são definidas automaticamente pelo provedor de telefonia e incluídas na requisição de pre-call data fetch como from_number e to_number. No entanto, quando você faz uma chamada de teste — seja uma chamada web (WebRTC) ou uma chamada de teste telefônica no editor de workflow — essas variáveis não estão disponíveis por padrão.

Para simular os dados de telefonia durante os testes:

1. Abra seu workflow e vá para Settings.
2. Em Context Variables, adicione as seguintes variáveis:
   • caller_number — definida como um número de telefone que você quer simular como chamador (por exemplo, [phone]).
   • called_number — definida como o número que seria discado (por exemplo, [phone]).
3. Salve as configurações.

Agora, quando você fizer uma chamada de teste (web ou telefônica), esses valores serão enviados na requisição de pre-call data fetch ao seu endpoint, permitindo testar o fluxo completo como se uma chamada recebida real estivesse chegando.

Essas variáveis de contexto são usadas apenas durante as chamadas de teste do editor de workflow. Nas chamadas recebidas de produção, os dados reais de telefonia são usados e esses valores são ignorados.

​

Exemplo de integração

Um endpoint simples em Node.js que consulta um cliente pelo número de telefone:

app.post("/tig/pre-call", async (req, res) => {
  const { call_inbound } = req.body;

  const customer = await db.customers.findOne({
    phone: call_inbound.from_number,
  });

  if (!customer) {
    return res.json({});
  }

  res.json({
    call_inbound: {
      initial_context: {
        customer_name: customer.name,
        account_status: customer.status,
        loyalty_tier: customer.tier,
      },
    },
  });
});