---
title: "Variáveis e contexto por chamada"
description: "Forneça a cada chamada seus próprios detalhes, como variáveis nomeadas para o prompt ou um resumo de formato livre, sem alterar o agente."
---

Cada chamada pode incluir dois tipos de entrada por chamada. Use um deles ou ambos
juntos:

- **`variables`**: valores nomeados que preenchem `{{placeholders}}` no prompt. Use-os
  para campos aos quais o prompt se refere pelo nome, como o nome de quem liga, um
  número de conta ou um horário de agendamento.
- **`context`**: texto livre adicionado após o prompt. Use-o para um resumo que
  não se encaixa em um modelo, como uma descrição da tarefa desta chamada ou
  observações coletadas anteriormente.

Ambos funcionam com um agente salvo e com uma configuração inline, em todas as formas de
iniciar uma chamada descritas abaixo. Nenhum deles altera o agente salvo, o histórico de versões
ou outras configurações.

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
  "context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}
```

## Variáveis

Insira marcadores no prompt do agente salvo e forneça um objeto `variables`
ao iniciar uma chamada. O ThunderPhone processa o texto antes de enviar a
configuração da chamada para o runtime de voz.

Quando não forem necessários valores, omita `variables`; não envie `null` (rejeitado com `400`).

### Espaços reservados e valores padrão

```text
You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.
```

Os nomes diferenciam maiúsculas de minúsculas e seguem `[A-Za-z_][A-Za-z0-9_]*`. Espaços em branco ao redor
do nome são permitidos; espaços em branco após `|` fazem parte do valor padrão e são
preservados. `{{name|Friend}}` usa `Friend` quando `name` está ausente ou é
`null`; uma string vazia é um valor fornecido explicitamente. Valores ausentes sem
um padrão se tornam strings vazias, e seus nomes aparecem em `unresolved_variables`.
O texto entre chaves duplas que não for um marcador válido será removido. O texto entre chaves duplas
dentro de cada valor fornecido é removido de forma independente; um valor não pode remover
o texto ao redor no prompt nem outro valor. Delimitadores de chaves duplas sem par também
são removidos. Exemplos de JSON em prompts não devem usar `{{`.
Os valores são texto simples e nunca são avaliados
como código nem expandidos recursivamente como modelos.

As variáveis também podem aparecer em prompts de confirmação, mensagens de correio de voz
de saída e no texto do anúncio de consentimento quando esse campo é enviado para uma
chamada telefônica. O agente não tem um campo `first_message` separado: coloque suas instruções
de abertura no prompt. Os marcadores existentes de correio de voz `{agent_name}` e `{org_name}`
continuam funcionando.

### Valores e limites

Os valores podem ser strings, números, booleanos ou `null`; os booleanos são exibidos como `true`
e `false`. Caracteres de controle Unicode (`Cc`), exceto nova linha (`\n`), tabulação (`\t`)
e retorno de carro (`\r`), caracteres de formatação (`Cf`), exceto o não separador e
separador de largura zero (U+200C, U+200D, usados para formar palavras em idiomas índicos
e com escrita árabe), e pontos de código substitutos (`Cs`) são removidos; `\r\n`
é normalizado para `\n`. Cada valor
é limitado a 2.000 caracteres quando exibido. As strings fornecidas também são limpas e
truncadas antes do armazenamento. O objeto original deve caber em **32 KB de
JSON UTF-8**; objetos maiores recebem `400` em solicitações de chamada/sessão, enquanto
importações de campanhas informam linhas inválidas individualmente. Arrays e objetos aninhados não são
aceitos como valores. Chaves de metadados que não correspondem (por exemplo, um cabeçalho CSV com um
espaço) são mantidas e retornadas, mas não podem ser referenciadas por um placeholder.

## Contexto

`context` é uma string de até **20.000 caracteres**. O ThunderPhone a adiciona após
o prompt, quando as variáveis do prompt já foram preenchidas, como um bloco delimitado:

```text
<your prompt, with its variables filled in>

Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>
```

O agente o lê junto com suas instruções, portanto escreva-o como você
orientaria um colega antes da chamada. O contexto não é um modelo:
`{{name}}` dentro dele permanece como está escrito. Se o texto precisar de um valor, insira o valor
você mesmo antes de enviá-lo.

- `null`, uma string vazia ou apenas espaços em branco significa que não há contexto.
- Um valor que não é uma string ou que tem mais de 20.000 caracteres é rejeitado com `400` em solicitações de chamada e sessão; em um webhook de configuração, ele falha na troca como `variables` inválidas (veja abaixo).
- Espaços em branco no início e no fim são removidos, assim como os mesmos caracteres de controle e formatação usados nos valores de variáveis.
- O contexto faz parte do prompt da chamada, portanto conta para o [tamanho do prompt](/pt/guides/pricing) da chamada.

Em um agente de [etapas](/pt/guides/agent-steps), o contexto vem após o prompt de
cada agente na chamada, e não após as instruções de cada etapa.

## De onde vêm os valores

### API de saída

Envie `variables` e `context` em `POST /v1/call`:

```json
{
  "from_number": "+15551234567",
  "to_number": "+14155552671",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  },
  "context": "Ada asked to be called back about the late fee on her March invoice."
}
```

Ambos também funcionam com o agente de saída padrão do número de telefone ou com um `config.prompt` embutido. Com uma configuração embutida, `context` também pode ficar dentro de `config`, o mesmo campo retornado por um webhook de configuração; se você enviar ambos, eles deverão ter o mesmo texto. Uma chave de idempotência não pode ser reutilizada com variáveis diferentes ou um contexto diferente.

### CSV de campanha

As colunas de CSV que não são de telefone já são armazenadas como variáveis de contato. Cada discagem agora as usa automaticamente. Use cabeçalhos como `name`, `account_id` e `appointment_slot` para corresponder aos seus placeholders. O mapeamento de nome existente pode combinar colunas de nome e sobrenome na variável `name`. Os contatos da campanha não têm contexto por contato.

### Webhook de configuração dinâmica

No caminho do webhook de configuração bloqueante, retorne um agente salvo na sua organização, além de quaisquer valores por chamada. Para um agente Full duplex, a chamada mantém a voz do agente mesmo quando começa em outro idioma compatível: os mapeamentos de voz por idioma e a troca nativa de voz não se aplicam a essa chamada.

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "[REDACTED_LITERAL]"
}
```

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}
```

As variáveis da resposta substituem as variáveis no nível da solicitação, enquanto as outras
chaves da solicitação permanecem. Um valor de resposta `null` seleciona o padrão do placeholder.
O objeto mesclado também deve caber em 32 KB. As respostas de agente salvo aceitam apenas
`agent_id`, `variables`, `context`, `language` e um [`timezone`](/pt/guides/dynamic-call-config) por chamada; retorne uma configuração inline quando precisar
substituir o prompt ou outras configurações. As respostas de webhook de agente salvo
usam a divisão A/B implantada do agente tanto em chamadas telefônicas quanto em chamadas pelo widget;
as variáveis são renderizadas após a seleção da variante. Quando a resposta define `language` para um
agente que não é Full duplex, a chamada também usa a voz desse idioma se o
agente tiver uma configurada para ele. Uma resposta que contém `prompt` sempre usa configuração inline:
qualquer `agent_id` nessa resposta é ignorado, incluindo metadados nulos ou
não inteiros. O prompt inline ainda precisa passar pela validação normal.
Respostas inline de webhook também podem incluir `variables` e `context`. Um `context`
que não seja uma string ou seja longo demais faz a troca falhar: uma chamada telefônica é
rejeitada, e uma solicitação de sessão do widget falha com `400`. As respostas de webhook de agente salvo
usam a divisão A/B implantada do agente tanto em chamadas telefônicas quanto em chamadas pelo widget;
as variáveis são renderizadas após a seleção da variante. Em chamadas telefônicas recebidas, use um número sem agente
de entrada atribuído e configure o webhook do número de telefone ou da organização; as chaves do widget usam
`mode="webhook"`. As notificações recebidas do sistema de endpoint não fornecem respostas de configuração bloqueantes.

### Webhook de configuração de chamada do agente

Para manter um número atribuído ao seu agente e preencher apenas os valores da chamada,
forneça ao agente um [webhook de configuração de chamada](/pt/webhooks/call-incoming).
Antes de cada chamada recebida que o agente atende em um número, o webhook recebe a
chamada e o ID, o nome e a versão do agente, e responde com as mesmas
`variables`, `context`, `language` e `timezone` por chamada descritas acima, sem precisar de um `agent_id`. Um agente
cujas configurações usam um placeholder sem valor padrão precisa desse webhook para atender
um número de telefone: a chamada não começa quando o webhook falha. Placeholders
com um valor padrão, como `{{name|there}}`, permitem que o agente atenda sem ele.

### Cabeçalhos SIP

Chamadas que chegam a um agente por tronco SIP (um [endereço SIP](/pt/guides/sip-addresses) ou
um número em uma conexão SIP manual) podem transportar contexto nos cabeçalhos
`X-*` e `User-to-User`. Cada um se torna uma variável `sip_`, como
`{{sip_x_amzn_connectcontactid}}` ou `{{sip_uui}}`, com a menor
precedência: um valor com o mesmo nome da API ou de um webhook prevalece. Consulte
[Transmitir contexto da chamada em cabeçalhos SIP](/pt/guides/sip-addresses).
Os valores dos cabeçalhos são definidos pelo remetente, portanto trate-os como não confiáveis,
assim como qualquer valor fornecido pelo navegador.

### API de sessão do widget

`POST /v1/widget/session` aceita `variables` e `language` de nível superior. A chave publicável
seleciona o agente salvo. Chaves no modo webhook encaminham esses valores ao
webhook de configuração e mesclam a resposta conforme descrito acima.
As `variables` do widget fornecidas pelo navegador são controladas pelo cliente, encaminhadas
literalmente em `web.incoming` após a validação e a limpeza de strings descritas
acima, e replicadas nos webhooks de conclusão e no histórico de chamadas. Não as trate
como dados confiáveis de identidade ou autorização.

O próprio campo `context` do navegador no widget é diferente: ele transporta texto da
página em que o visitante está, que o agente trata como conteúdo do site (consulte
[Incorporar o widget da web](/pt/guides/embed-web-widget)). O contexto por chamada de uma chamada do widget
vem do webhook de configuração de uma chave no modo webhook, conforme acima. Quando uma
chamada tem ambos, o contexto por chamada vem primeiro, seguido pelo conteúdo da página.

### API de sessão em tempo real

`POST /v1/realtime/sessions` aceita `variables`, `context` e `language` de nível superior
junto com `agent_id` ou uma `config` embutida:

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada"},
  "context": "Ada is calling from the front desk about a guest's lost key card."
}
```

`context` deve ficar apenas no nível superior; uma `config` embutida o rejeita como um
campo desconhecido.

### WebSocket em tempo real

Com um agente salvo, o prompt implantado do agente salvo continua sendo o prompt dele.
`session.instructions` se torna o contexto da chamada, `session.prompt.variables`
(ou `session.config.variables`) se tornam as variáveis dele, e `session.language`
se torna o idioma por chamada. Escolha o agente com
`session.prompt.id` no primeiro `session.update`, que inicia a sessão assim que
essa atualização chega:

```json
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {"id": "12", "variables": {"name": "Ada"}},
    "instructions": "Ada asked for a callback about her delivery window."
  }
}
```

`?agent_id=12` na URL de conexão inicia o agente assim que o socket
se conecta, antes de qualquer `session.update`, portanto não inclui dados por chamada. Adicione
`&wait_for_session_update=1` para aguardar o primeiro `session.update` e usar suas
instruções e variáveis.

Em uma sessão inline (sem um agente salvo), `session.instructions` é o próprio prompt, como antes. As chamadas de teste no navegador e as simulações resolvem valores padrão e placeholders ausentes. Para testar com valores, salve um [exemplo de configuração de chamada](/pt/webhooks/call-incoming) no agente e selecione-o ao iniciar o teste; a chamada é executada como se o webhook de configuração de chamada tivesse respondido com ele.

## Após a chamada

`GET /v1/calls`, `GET /v1/calls/{call_id}`, `telephony.complete` e `web.complete` incluem as `variables` finais mescladas e `unresolved_variables`. Cargas úteis legadas de conclusão que incluem `data.history` também as incluem:

```json
{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}
```

O `prompt_snapshot` da chamada (`GET /v1/calls/{call_id}`) mostra o prompt do agente
com suas variáveis preenchidas e o bloco de contexto adicionado.

Armazene o identificador do CRM ou da tarefa no objeto de variáveis para vincular a
chamada concluída ao registro de origem. As variáveis e o contexto são mantidos com o
registro da chamada; envie apenas informações apropriadas para reter no histórico de chamadas e
nos webhooks.

As reproduções de uma chamada, em [conjuntos de validação](/api-reference/validation-sets),
[execuções de reprodução](/api-reference/replay-runs) e
[investigações](/api-reference/investigations), usam as variáveis e o contexto dessa chamada
com o prompt em teste. Assim, uma reprodução testa o que teria sido informado ao agente naquela
chamada.

## Compatibilidade com prompts existentes

A renderização também se aplica a prompts existentes de agentes salvos e variantes A/B, configurações inline de chamadas de saída e em tempo real, e prompts retornados por webhooks de configuração. Placeholders `{{name}}` desconhecidos tornam-se texto em branco, mesmo quando nenhuma `variables` é fornecida. Verifique os prompts existentes antes da implementação, incluindo prompts inline/de webhook fornecidos externamente que o ThunderPhone não consegue inventariar. Chamadas de teste no navegador e simulações aplicam o mesmo comportamento padrão/em branco, a menos que você escolha uma amostra de configuração de chamada salva.
