Variáveis por chamada

Personalize um agente salvo para cada chamada sem alterar seu prompt, suas ferramentas ou configurações implantados.

Coloque marcadores no prompt do seu agente salvo e, em seguida, forneça um objeto variables ao iniciar uma chamada. A configuração salva e o histórico de versões permanecem inalterados. O ThunderPhone renderiza o texto antes de enviar a configuração da chamada ao runtime de voz.

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

Marcadores e valores padrão

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.

Os valores podem ser strings, números, booleanos ou null; os booleanos são renderizados como true e false. Caracteres de controle Unicode (Cc), exceto nova linha (\n), tabulação (\t) e retorno de carro (\r), todos os caracteres de formatação (Cf) e pontos de código substitutos (Cs) são removidos; \r\n é normalizado para \n. Cada valor é limitado a 2.000 caracteres quando renderizado. 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 não correspondentes (por exemplo, um cabeçalho CSV com um espaço) são mantidas e repetidas, mas não podem ser referenciadas por um marcador.

De onde vêm os valores

API de saída

Envie variables junto com agent_id em POST /v1/call:

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

Também funciona com o agente de saída padrão do número de telefone ou com um config.prompt inline. Uma chave de idempotência não pode ser reutilizada com variáveis diferentes.

CSV de campanha

As colunas do 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.

Webhook de configuração dinâmica

No caminho do webhook de configuração bloqueante, retorne um agente salvo na sua organização junto com quaisquer valores por chamada:

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

As chaves da resposta substituem as variáveis do nível da solicitação, enquanto as demais 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. Respostas de agentes salvos aceitam apenas agent_id e variables; retorne uma configuração inline quando precisar substituir o prompt ou as configurações. Uma resposta que contém prompt sempre usa configuração inline: qualquer agent_id nessa resposta é ignorado, incluindo metadados nulos ou que não sejam inteiros. O prompt inline ainda deve passar pela validação normal. Respostas inline do webhook também podem incluir variables. Respostas do webhook de agente salvo usam a divisão A/B implantada do agente em chamadas telefônicas e de 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 de widget usam mode="webhook". As notificações de entrada do sistema de endpoint não fornecem respostas de configuração bloqueante.

POST /v1/widget/session aceita um objeto variables de nível superior. Sua 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 de widget/realtime 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 incluídas nas respostas dos webhooks de conclusão e no histórico de chamadas. Não as trate como dados confiáveis de identidade ou autorização.

POST /v1/realtime/sessions aceita variables junto com agent_id (ou config inline). Esses são campos da API de criação de sessão. A ponte WebSocket do Realtime não encaminha uma opção de variáveis; forneça-a diretamente à API de criação de sessão. Clientes de widget devem incluir variables na carga útil de sessão enviada; o encaminhamento pelo SDK não faz parte desta alteração de API. Chamadas de teste simuladas e com microfone do Builder resolvem padrões e placeholders ausentes, mas não têm entrada de variáveis por chamada.

Valores retornados 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:

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

Armazene o identificador do seu CRM ou da tarefa no objeto de variáveis para associar a chamada concluída ao registro de origem. Esses campos são retidos com o registro da chamada; envie apenas informações apropriadas para retenção no histórico de chamadas e nos webhooks.

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 se tornam texto em branco, mesmo quando nenhum variables é fornecido. Verifique os prompts existentes antes da implementação, incluindo prompts inline/de webhook fornecidos externamente que o ThunderPhone não consegue inventariar. As chamadas de microfone e simulação no Builder aplicam o mesmo comportamento padrão/em branco.