ThunderPhone v3 já está no ar.Contrate online, a partir de 2¢/min.Leia o anúncio

Developer cookbook

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

{
  "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 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.