Open in
Variáveis e contexto por chamada
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.
{
"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
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:
<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
400em solicitações de chamada e sessão; em um webhook de configuração, ele falha na troca comovariablesinvá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 da chamada.
Em um agente de etapas, 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:
{
"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.
{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "[REDACTED_LITERAL]"
}{
"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 do 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 por chamada; retorne uma configuração inline quando precisar
substituir o prompt ou outras configurações. Quando a resposta define language para um
agente que não é Full duplex, a chamada também usa a voz própria 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 de widget;
as variáveis são renderizadas após a seleção da variante. Em chamadas telefônicas de entrada, 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 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.
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 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.
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). 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:
{
"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:
{
"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 agente salvo), session.instructions é o próprio
prompt, como antes. As chamadas de teste simuladas e pelo microfone do Builder resolvem valores padrão e
placeholders ausentes, mas não têm variáveis por chamada nem entrada de contexto.
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"]
}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, execuções de reprodução e investigações, 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 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.