> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tigyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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**](/pt/voice-agent/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](/pt/core-concepts/context-and-variables#initial_context) 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**](/pt/voice-agent/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:

```json theme={null}
{
  "event": "call_inbound",
  "call_inbound": {
    "agent_id": 123,
    "from_number": "+12137771234",
    "to_number": "+12137771235"
  }
}
```

| 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`:

```json theme={null}
{
  "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:

```json theme={null}
{
  "initial_context": {
    "customer_name": "Jane Doe",
    "account_status": "active"
  }
}
```

<Note>
  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.
</Note>

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

<Note>
  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.
</Note>

## Variáveis aninhadas

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

```json theme={null}
{
  "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, `+12137771234`).
   * `called_number` — definida como o número que seria discado (por exemplo, `+12137771235`).
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.

<Note>
  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.
</Note>

## Exemplo de integração

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

```javascript theme={null}
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,
      },
    },
  });
});
```