Ações e Ferramentas

A aba Actions é onde gere tudo o que o seu agente pode fazer para além da conversa — ferramentas que o agente chama durante uma conversa ao vivo, hooks de prefetch que correm antes de a chamada começar, e ações pós-chamada que são acionadas assim que a chamada termina. As Variáveis de Recolha (os campos de dados que o agente extrai de cada conversa) vivem na mesma aba.

Todos os Planos

Todas as ferramentas, ações e o novo hook de pre-fetch estão disponíveis em todos os planos, incluindo Free.

As Três Fases

Cada entrada na aba Actions pertence a uma de três fases do ciclo de vida. O dropdown Add Tool agrupa-as para que seja claro quando cada coisa é acionada:

Fase	Quando	Exemplos
Pre fetch	Antes de o agente dizer olá	Procurar o interlocutor no seu CRM por telefone, obter a última encomenda, buscar uma saudação personalizada do seu backend
Live call	Durante a conversa, acionado pela IA quando o momento é o certo	Encaminhar a chamada para um humano, verificar disponibilidade de calendário, transferir para outro agente, consultar uma API externa para dados
Post call	Depois de a chamada terminar	Enviar um email de resumo, disparar uma confirmação por SMS, enviar o payload da chamada para o seu CRM

O dropdown abre com Pre fetch no topo porque todas as outras fases já têm muitas opções — a nova entrada de pre-fetch é o mais provável que esteja a procurar.

Pre fetch

Os hooks de pre-fetch permitem que o seu agente comece a chamada já sabendo quem está a ligar. Correm em paralelo com o setup da chamada e injetam a resposta no prompt de sistema do agente antes de a primeira palavra ser dita.

Quando usá-lo

Reconhecer um cliente recorrente pelo número de telefone e cumprimentá-lo pelo nome
Obter a encomenda em aberto do interlocutor, o último compromisso ou o nível de adesão
Pré-carregar contexto de negócio que depende da linha que foi marcada
Injetar notas de CRM para que o agente saiba a etapa e o histórico da lead

Como funciona

A plataforma resolve o telefone do interlocutor (do SIP para inbound, do alvo de marcação para outbound).
Cada ação Pre fetch ativa dispara em paralelo com um timeout rígido de 1,5 s por pedido e um orçamento global de 2 s.
As respostas bem-sucedidas são concatenadas no prompt de sistema do agente como blocos nomeados — o agente lê-os no seu primeiro turno.
As falhas são silenciosas — um endpoint lento ou avariado nunca bloqueia a saudação. O agente simplesmente começa a falar sem esse bloco.

Configuração

Campo	Descrição
Name	Obrigatório. Rótulo interno e o nome do bloco no prompt — mantenha-o curto e descritivo (ex.: `crm_lookup`, `vip_check`).
API URL	Obrigatório. Endpoint de onde buscar. Suporta os placeholders `{phone}`, `{direction}`, `{agent_id}`, `{user_id}`, `{call_id}`.
HTTP Method	`GET` é o padrão e o mais adequado. `POST` / `PUT` / `PATCH` / `DELETE` também funcionam.
Headers	Opcional. Estáticos ou com template (os placeholders também funcionam aqui).
Query Parameters	Opcional. Vem pré-preenchido com `phone={phone}` para novas ações de pre-fetch.

Variáveis disponíveis

Estes tokens são substituídos no URL, headers e parâmetros de query/body no momento do pedido:

Variável	Fonte	Valor de exemplo
`{phone}`	Telefone do interlocutor (E.164) — para outbound, o número de destino	`+431234567890`
`{direction}`	`inbound` ou `outbound`	`inbound`
`{agent_id}`	ID interno do agente	`65f1a2b3c4...`
`{user_id}`	ID do proprietário do workspace	`65e0b1c2d3...`
`{call_id}`	ID da chamada (permite ao seu backend correlacionar mais tarde o payload pós-chamada)	`65f1f2c4d5...`

Placeholders desconhecidos são deixados literalmente — um mau templating nunca faz uma chamada falhar.

O que chega ao prompt

Se o seu endpoint em https://crm.example.com/lookup?phone={phone} retornar:

{ "name": "Sarah Johnson", "tier": "Gold", "open_orders": 1 }

O prompt de sistema do agente é acrescentado com um bloco embrulhado em XML com o nome da ação:

<call_context>
  <block name="crm_lookup">
  { "name": "Sarah Johnson", "tier": "Gold", "open_orders": 1 }
  </block>
</call_context>

Não precisa de dizer ao agente como usá-lo — o LLM capta o contexto naturalmente. Opcionalmente, mencione o pre-fetch no seu prompt de sistema: "If <call_context> contains a customer name, greet them by name."

Restrições importantes

Apenas chamadas de telefone. O pre-fetch não corre para chamadas de widget (web) — não há número de telefone contra o qual criar o template.
Limite de 8 KB no corpo da resposta — qualquer coisa mais longa é truncada antes da injeção. O limite protege o seu orçamento de tokens do prompt e delimita o raio de ação de um endpoint malicioso.
Sem avaliação de condition — o pre-fetch dispara sempre quando ativo. Ainda não há transcrição para avaliar.

dica

Use GET com um endpoint de consulta indexado por telefone. Mantenha as respostas pequenas e estruturadas (objeto JSON com 3-5 campos). O agente não precisa do seu registo completo de cliente — apenas das partes que mudam a conversa.

Ferramentas de Chamada ao Vivo

Estas correm durante a conversa. A IA decide quando chamar cada ferramenta com base na sua descrição e no diálogo atual.

Ferramentas Disponíveis

Ferramenta	Finalidade	Quando usar
Call Forwarding	Transferir para um operador humano	O cliente pede uma pessoa, problemas complexos
Google Calendar	Verificar disponibilidade e marcar compromissos	O cliente quer agendar uma reunião
Outlook Calendar	Igual, via Microsoft Outlook	O cliente quer agendar uma reunião
API Tool RAG	Buscar dados ao vivo de uma API externa	Precisa de info em tempo real (encomendas, stock, estado de conta)
Agent Transfer	Transferir para outro agente de voz	O interlocutor precisa de um departamento ou especialista diferente
HubSpot CRM	Ler/escrever contactos e negócios no HubSpot	Registar a chamada no HubSpot, procurar uma lead
MCP servers	Expor ferramentas de qualquer um dos seus servidores MCP registados	Executa um servidor de ferramentas compatível com MCP e quer que o agente use as suas ferramentas a meio da conversa

Call Forwarding

Transfere chamadas para um humano quando condições específicas são cumpridas.

Definição	Descrição	Exemplo
Name	Obrigatório. Nome da pessoa ou departamento	`"Sales Manager"`
Forwarding Number	Número de telefone padrão para onde transferir	`"+49 123 456 789"`
Trigger Condition	Quando o agente deve transferir	`"Customer asks for manager or issue cannot be resolved"`
Conditional Routing Numbers	Mapeamento condição-para-número para encaminhamento	`{"billing": "+49 111 222", "technical": "+49 333 444"}`

Como funciona:

Durante uma conversa, a IA avalia a Trigger Condition.
Se os números de encaminhamento condicional estiverem definidos, a condição correspondente determina que número chamar.
Caso contrário, é usado o Forwarding Number.
O agente informa o interlocutor sobre a transferência.
A chamada é encaminhada — se não houver resposta, regressa ao agente.

dica

Pode adicionar várias ferramentas Call Forwarding para departamentos diferentes — uma para "Vendas" e outra para "Suporte Técnico" com condições e números diferentes.

Google Calendar

Ligue o seu Google Calendar para que o agente possa verificar disponibilidade e marcar compromissos durante as chamadas.

Configuração:

Vá a Integration → Calendars e ligue primeiro a sua conta Google.
Adicione a ferramenta Google Calendar na aba Actions do agente.
Selecione o calendário a usar.
Configure as suas definições de disponibilidade.

Definição	Descrição	Padrão
Calendar	Obrigatório. Que calendário usar	O seu calendário principal
Timezone	Fuso horário para compromissos (formato IANA)	Detetado automaticamente
Work Start Time	Início do horário de trabalho	9:00 AM
Work End Time	Fim do horário de trabalho	6:00 PM
Slot Duration	Duração do compromisso em minutos	30
Working Days	Dias disponíveis da semana	Segunda–Sexta
Buffer Between Appointments	Margem entre compromissos (0–60 min)	0

Durações de slot suportadas: 15, 30, 45, 60, 75, 90, 105, 120 minutos.

dica

Configure com precisão o seu horário e dias de trabalho — o agente só oferecerá horários dentro da disponibilidade que configurou.

Outlook Calendar

Ligue o seu Outlook Calendar para agendamento de compromissos durante as chamadas. Funciona da mesma forma que o Google Calendar.

Configuração:

Vá a Integration → Calendars e ligue primeiro a sua conta Outlook.
Adicione a ferramenta Outlook Calendar na aba Actions do agente.
Selecione o calendário a usar.
Configure as suas definições de disponibilidade.

As definições são idênticas ao Google Calendar (fuso horário, horas de trabalho, duração de slot, dias de trabalho, buffer).

Agent Transfer

Transfere uma chamada para outro agente de voz na sua conta. Útil quando tem agentes especializados para departamentos diferentes.

Definição	Descrição
Target Agent	Obrigatório. Selecione para que agente transferir
Trigger Condition	Quando transferir (ex.: "O interlocutor pergunta sobre suporte técnico")

Exemplo: Um agente rececionista transfere interlocutores para um agente de vendas quando perguntam sobre preços, ou para um agente de suporte quando têm um problema técnico.

HubSpot CRM

Leia e escreva no seu HubSpot CRM durante a chamada. Permite que o agente registe interações, procure um contacto por telefone ou envie atualizações de negócios sem que tenha de escrever as chamadas de API.

Configuração:

Vá à página Integrations e ligue a sua conta HubSpot.
Adicione a ferramenta HubSpot CRM na aba Actions do agente.
Selecione que pipeline e propriedades o agente deve poder tocar.

Depois de a ferramenta ser adicionada, a IA pode corresponder o interlocutor a um contacto HubSpot por telefone, obter a etapa do negócio e atualizar campos — tudo a partir da conversa ao vivo.

MCP servers

Exponha ferramentas de qualquer servidor compatível com MCP que tenha ligado à Hanc.AI. Um agente pode puxar de vários servidores MCP; um servidor MCP pode servir vários agentes.

Configuração:

Ligue o(s) seu(s) servidor(es) MCP uma vez em Integration → MCP servers. Veja a página dedicada de Servidores MCP para os passos completos de registo.
Adicione a entrada MCP servers à aba Actions deste agente — está agrupada em Live call no dropdown Add Action.
Ative quais das suas ligações registadas este agente deve poder aceder.
Adicione uma breve instrução "When to use it" para que o agente saiba quando recorrer a estas ferramentas.

O agente redescobre o conjunto de ferramentas de cada servidor MCP ativado no início de cada chamada, por isso as alterações que faz do lado do servidor aparecem automaticamente na chamada seguinte. As ferramentas são renomeadas com o rótulo da ligação como prefixo, para que ferramentas com nomes semelhantes de servidores diferentes não colidam.

API Tool RAG

Ligue a APIs externas para buscar informação em tempo real durante as chamadas — consultar encomendas, verificar inventário, validar contas ou aceder a quaisquer dados disponíveis via API.

Definição	Descrição	Exemplo
Name	Obrigatório. Nome da ferramenta	`"Order Lookup"`
Description / When to Use	Obrigatório. Quando consultar a API	`"Customer asks about order status"`
API URL	Obrigatório. Endpoint da API. Pode incluir tokens `{placeholder}` que serão substituídos por valores do Body Parameters Schema (ver abaixo).	`"https://api.yourshop.com/orders/{order_id}"`
HTTP Method	Obrigatório. Método HTTP	`GET`, `POST`, `PUT`, `DELETE`, `PATCH`
Loading Message	O que o agente diz enquanto espera	`"Let me check that for you..."`
Timeout	Tempo máximo de espera (ms)	`5000` (padrão)
Headers	Headers HTTP estáticos enviados com cada pedido	`{"Authorization": "Bearer KEY"}`
Query Parameters	Parâmetros de query string estáticos adicionados a cada pedido	`{"apiVersion": "v2"}`
Body Parameters Schema	Obrigatório. JSON Schema que descreve os argumentos que a IA deve extrair da conversa e passar à ferramenta. Veja Escrever o Body Parameters Schema.	Objeto JSON Schema

dica

Defina sempre uma Loading Message — o silêncio durante as chamadas de API parece avariado ao interlocutor.

observação

A antiga checkbox "Run on call start" no API Tool RAG foi substituída pela entrada dedicada Pre fetch. Use Pre fetch quando quer os dados antes de a conversa começar; use API Tool RAG quando o agente deve decidir durante a chamada se deve buscar.

Escrever o Body Parameters Schema

Apesar do nome, o Body Parameters Schema não é um corpo de pedido em bruto. É um JSON Schema que descreve o que a IA deve extrair da conversa e passar à sua ferramenta. Dependendo do método HTTP e do template de URL, estes valores acabam no URL, na query string ou no corpo JSON:

Método HTTP	Onde vão os valores extraídos
URL contém `{name}`	O valor correspondente é substituído no URL
`GET`, `DELETE`	Os valores restantes são anexados ao URL como `?key=value`
`POST`, `PUT`, `PATCH`	Os valores restantes são enviados como corpo JSON

Estrutura mínima

{
  "type": "object",
  "properties": {
    "param_name": {
      "type": "string",
      "description": "What this value is and how the AI should pick it"
    }
  },
  "required": ["param_name"]
}

O type raiz é sempre "object". properties lista cada argumento. required marca quais a IA deve fornecer sempre — se o cliente ainda não o disse, a IA perguntará antes de chamar a ferramenta.

Referência de campos

Campo	Finalidade
`type`	Tipo JSON do valor: `"string"`, `"number"`, `"integer"`, `"boolean"`, `"array"`, `"object"`
`description`	O mais importante. Diz à IA o que o valor significa, que formato usar e quando o fornecer. Adicione exemplos sempre que possível.
`enum`	Restringe o valor a um de uma lista fixa. A IA mapeará a fala natural para a opção mais próxima (ex.: `"the blue one"` → `"blue"`).
`minimum`, `maximum`	Limites numéricos. A IA recusará/limitará valores fora do intervalo.
`default`	Valor usado quando a IA não passa este campo. Não obrigatório, mas documenta o valor implícito.
`format`	Dica de validação, ex.: `"email"`, `"date"` (YYYY-MM-DD), `"uri"`.

Exemplos

Pesquisa de produto (apenas palavra-chave):

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Product search keyword — e.g. \"phone\", \"laptop\", \"Apple\", \"Samsung\""
    }
  },
  "required": ["query"]
}

Usado com o URL https://dummyjson.com/products/search?q={query}&limit=5 e GET: o valor query vai para o placeholder do URL. Nada acaba no corpo.

Consulta de encomenda por ID:

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "description": "Order ID the customer is asking about, usually 6 to 10 digits. Ask the customer if not provided."
    }
  },
  "required": ["order_id"]
}

Usado com o URL https://api.example.com/orders/{order_id} e GET.

Marcação com vários campos obrigatórios:

{
  "type": "object",
  "properties": {
    "product_id": {
      "type": "string",
      "description": "Product ID returned by a previous search_products call."
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "How many items to reserve. Default 1."
    },
    "delivery_method": {
      "type": "string",
      "enum": ["pickup", "home_delivery", "locker"],
      "description": "How the customer wants to receive the item."
    },
    "customer_email": {
      "type": "string",
      "format": "email",
      "description": "Customer's email for order confirmation. Ask if not provided."
    }
  },
  "required": ["product_id", "delivery_method", "customer_email"]
}

Usado com POST https://api.example.com/reservations: os quatro valores vão para o corpo JSON. A IA perguntará ao cliente os campos required em falta antes de chamar a ferramenta.

Ferramenta sem parâmetros:

{
  "type": "object",
  "properties": {}
}

Use isto quando o endpoint é totalmente estático (ex.: GET /store/hours) e a IA não precisa de passar nada.

Boas práticas para agentes de voz

Mantenha o schema plano. Objetos e arrays aninhados funcionam, mas a IA pode escorregar ao falar ao telefone. Prefira no máximo 3–5 campos de topo.
Escreva sempre uma description para cada campo. Inclua exemplos (e.g. "phone", "laptop") — os exemplos orientam a IA de forma mais fiável do que definições abstratas.
Use enum sempre que tenha uma lista fixa de valores. Elimina o risco de a IA inventar valores ou enviar "Electronics" em vez de "electronics".
Marque um campo como required apenas se a ferramenta não puder funcionar sem ele. Tudo o resto é opcional, e a IA saltá-lo-á quando o cliente não o mencionar — sem perguntas extra desconfortáveis.
Use nomes em snake_case e faça corresponder exatamente quaisquer tokens {placeholder} no URL.
Documente o comportamento para valores em falta na description — ex.: "Omit if no budget limit", "Default 5".

Ações de Mensagem ao Vivo

(v2.4) Send SMS live e Send Email live permitem que o agente envie uma mensagem de texto ou email a meio da chamada, enquanto ainda fala com o interlocutor — não apenas após a chamada terminar como as suas contrapartes pós-chamada. Use-as para enviar um link, uma confirmação de marcação, um código ou um resumo sobre o qual o interlocutor possa atuar antes de desligar.

A IA dispara estas ações ela própria, no momento, com base na descrição da ação e na conversa — da mesma forma que decide chamar qualquer outra ferramenta ao vivo.

Ação	Dispara	Envia para
Send SMS live	Durante a chamada	O número de telefone do interlocutor
Send Email live	Durante a chamada	O email do interlocutor

Limite de envios por chamada

Cada canal está limitado a 3 envios por canal por chamada. Um agente pode enviar até três SMS ao vivo e até três emails ao vivo numa única chamada; o quarto envio num canal é recusado. Isto impede que uma conversa tagarela ou em loop faça spam ao interlocutor.

Matriz de recusa

Um envio ao vivo é recusado (e o agente é informado do motivo, para que possa recuperar graciosamente) quando:

Condição	Resultado
Email inválido ou em falta (para Send Email live)	Recusado — o agente pede ao interlocutor para confirmar o email
Telefone inválido ou em falta (para Send SMS live)	Recusado — o agente pede ao interlocutor para confirmar o número
Corpo com mais de 160 caracteres	Recusado — a mensagem é demasiado longa para enviar como está
Limite de canal atingido (já 3 envios nesta chamada)	Recusado — sem mais envios nesse canal

Como o agente recebe de volta o motivo da recusa, pode corrigir o problema na conversa ("Pode soletrar-me esse email?") e tentar novamente, em vez de falhar em silêncio.

Registo na timeline do CRM

Cada envio ao vivo é registado na timeline do CRM do contacto, para que a mensagem que o agente enviou a meio da chamada apareça ao lado do registo da chamada — pode ver exatamente o que foi enviado, para que canal e quando.

Encadeamento inteligente formulário-para-canal

Quando um interlocutor web submete o formulário do widget com apenas alguns dados de contacto, o agente só usa o canal que efetivamente tem:

O interlocutor submete apenas um email → o agente dispara Send Email live (nunca SMS).
O interlocutor submete apenas um telefone → o agente dispara Send SMS live (nunca email).
O interlocutor submete ambos → o agente pode usar qualquer canal conforme a conversa exigir.

Isto significa que o agente nunca tenta enviar SMS a um interlocutor que só deu um email, ou email a um que só deu um número — os dados de formulário disponíveis determinam que ação ao vivo está em cima da mesa.

Ações Pós-Chamada

As ações pós-chamada disparam assim que a chamada terminar e a cadeia de análise tiver produzido o resumo, o sentimento e as variáveis extraídas. Consomem dados da chamada — não falam com o cliente.

Ações Disponíveis

Ação	Finalidade
Send Email	Enviar por email um resumo estruturado à sua equipa ou cliente
Send SMS	Confirmação por texto ao interlocutor
Send WhatsApp	Mensagem ou template WhatsApp (funciona dentro e fora da janela de 24 horas)
API Call	Enviar o payload completo da chamada para uma API externa (CRM, webhook, o seu data warehouse)

Send Email

Definição	Descrição
Name	Obrigatório. Identificador da ação
Subject	Obrigatório. Linha de assunto do email
Message Body	Obrigatório. Corpo do email — pode incluir variáveis de recolha
Trigger Condition	Quando enviar (vazio = sempre)
Recipients	Obrigatório. Endereços de email que recebem sempre o email
Conditional Recipients	Mapeamento condição-para-destinatário

Usar variáveis no email:

New lead from phone call:

Name: {{customer_name}}
Email: {{customer_email}}
Interested in: {{selected_plan}}
Notes: {{call_notes}}

Send SMS

Definição	Descrição
Name	Obrigatório. Identificador da ação
Sender Name	Nome de remetente apresentado
Message	Obrigatório. Conteúdo do SMS (pode incluir variáveis)
Trigger Condition	Quando enviar
Recipients	Obrigatório. Números de telefone que recebem sempre o SMS
Conditional Recipients	Mapeamento condição-para-número

Send WhatsApp

A mensagem WhatsApp na HANC usa templates pré-aprovados de uma conta central Twilio Content — não cola um Template SID à mão. O editor de ações mostra um dropdown de cada template atualmente ativo e aprovado, e escolhe um. Os placeholders dentro do template ({{1}}, {{2}}, …) são depois preenchidos inline a partir de variáveis da chamada ou de texto estático que mapeia no editor.

Definição	Descrição
Name	Obrigatório. Identificador da ação
Trigger Condition	Quando enviar
Recipients	Obrigatório. Números de telefone que recebem sempre a mensagem
Conditional Recipients	Mapeamento condição-para-número
Template	Obrigatório. Seletor dropdown de templates WhatsApp pré-aprovados sincronizados da conta central Twilio Content. Cada entrada mostra o nome do template, o idioma e uma pré-visualização do corpo para que saiba qual escolher.
Template Variables	Para o template que escolheu, o editor lista cada placeholder (`{{1}}`, `{{2}}`, …) e permite mapeá-lo para uma variável de chamada (ver abaixo) ou uma string estática.

Variáveis de chamada disponíveis que pode mapear para placeholders de template:

Variável	Descrição
`{{call_from}}`	Número de telefone do interlocutor
`{{call_to}}`	Número que foi chamado
`{{call_summary}}`	Resumo da chamada gerado por IA
`{{call_sentiment}}`	Sentimento (positivo/neutro/negativo)
`{{call_task_achieved}}`	Se a tarefa da chamada foi alcançada
`{{call_transcription}}`	Transcrição completa da chamada

Porquê um seletor, não texto livre

O WhatsApp exige que cada mensagem iniciada pelo negócio fora da janela de 24 horas de serviço ao cliente use um template pré-aprovado. A HANC sincroniza a lista de templates aprovados da conta partilhada Twilio Content, por isso o dropdown mostra sempre exatamente o que é elegível para enviar neste momento — não pode escolher acidentalmente um rascunho, um template rejeitado ou um SID que não existe. Para adicionar um novo template, contacte o suporte; assim que for aprovado pelo WhatsApp, aparece automaticamente no dropdown.

API Call

A ação API Call pós-chamada é o seu webhook genérico para o resto da sua stack. Escolha o método, defina o URL, e nós enviamos o payload completo da chamada — o seu endpoint recebe um objeto JSON estruturado a descrever o que aconteceu.

Definição	Descrição
Name	Obrigatório. Identificador da ação
Trigger Condition	Quando disparar (vazio = cada chamada). Avaliado por um LLM contra a transcrição.
API URL	Obrigatório. URL do endpoint da API
HTTP Method	Obrigatório. `GET`, `POST`, `PUT`, `DELETE`, `PATCH`
Headers	Headers de pedido opcionais
Query Parameters	Parâmetros de query string opcionais

O que o seu endpoint recebe

Para POST / PUT / PATCH, o seu endpoint recebe um objeto JSON no corpo do pedido. Os seus body params configurados são fundidos com o payload completo da chamada:

{
  "call_from": "+431234567890",
  "call_to":   "+439876543210",
  "direction": "inbound",
  "call_type": "phone",
  "call_status": "ended",
  "start_timestamp": 1730000000000,
  "end_timestamp":   1730000187000,
  "duration": 187000,
  "transcription": [
    { "speaker": "agent", "content": "Hello…", "timestamp": 1730000001000 },
    { "speaker": "user",  "content": "Hi…",    "timestamp": 1730000003000 }
  ],
  "call_summary": "Customer asked about pricing…",
  "task_achieved": true,
  "sentiment": { "sentiment": "positive", "explanation": "…" },
  "custom_analysis_data": {
    "name": "John",
    "email": "john@example.com"
  },
  "collected_data": { /* in-call form submissions */ },
  "transfer_history": [ /* if any agent transfer happened */ ],
  "recording_url": "https://…",
  "disconnection_reason": "user_hangup",
  "is_anonymous": false,
  "is_simulation": false,
  "created_at": 1730000000000,
  "updated_at": 1730000187000
}

Para GET / DELETE, os mesmos campos são achatados na query string — mas os valores aninhados como transcription, sentiment e custom_analysis_data são descartados (os URLs não conseguem transportar dados estruturados de forma sensata). Use POST/PUT/PATCH se precisar da transcrição.

Cada pedido também recebe um header X-Correlation-Id para rastreio, e expira após 30 segundos.

Pre-fetch vs API Call pós-chamada

Pre fetch cria template de {phone} etc. no URL/headers/query/body. Retorna para dentro do prompt, antes da chamada.
API Call pós-chamada envia o dump completo da chamada no corpo ou query. Sem templating de URL — o seu endpoint recebe URL estático + corpo dinâmico.

Variáveis de Recolha

As Variáveis de Recolha são campos de dados personalizados que a IA extrai automaticamente das conversas. Por exemplo, o agente pode captar o nome do interlocutor, o email, o número de telefone ou qualquer outra informação que defina.

Variáveis Padrão

Cada novo agente é criado com duas variáveis de recolha padrão:

Variável	Tipo	Descrição
Email	Email	Endereço de email do interlocutor
Phone	Phone	Número de telefone do interlocutor

Estas estão ativadas por padrão e mostradas no formulário do widget de chamada. Pode editá-las ou removê-las, e adicionar as suas próprias variáveis personalizadas.

Tipos de Variável

Tipo	Caso de Uso	Exemplo
Text	Nomes, moradas, notas, input de forma livre	Nome do cliente, morada de entrega
Number	Quantidades, orçamentos, IDs	Quantidade de encomenda, valor do orçamento
Email	Endereços de email com validação	Email do cliente
Phone	Números de telefone com validação	Número de telefone do cliente
Selector	Escolha de opções predefinidas	Plano preferido (Basic/Pro/Enterprise)
Checkbox	Consentimento ou confirmação sim/não	"Concordo em receber emails de marketing"

Configurar uma Variável

Campo	Descrição	Exemplo
Variable Name	Obrigatório. Identificador da variável	`customer_email`
Instructions for AI	Obrigatório. Instruções para a IA sobre quando e como extrair este valor	`"The customer's email address. Ask if not provided."`
Example Format	(Opcional) Exemplo do formato esperado	`"john@example.com"`
Options (for Selector)	(Apenas Selector) Lista de opções permitidas	`["Basic", "Pro", "Enterprise"]`
Show in Form	Se deve mostrar este campo no formulário do widget de chamada	Ativado por padrão

Show in Form

Quando Show in Form está ativado, a variável aparece como um campo de entrada visível no widget web antes e durante a chamada. Isto permite que os interlocutores preencham a sua informação diretamente, além de a IA a extrair da conversa.

dica

A IA pedirá naturalmente a informação em falta durante a conversa. Defina uma descrição clara como "Endereço de email do cliente, peça educadamente se não for fornecido" e o agente tratará disso.

Adicionar Ferramentas e Ações

Navegue até à aba Actions do seu agente.
Clique em Add Tool.
Escolha a fase certa no dropdown — Pre fetch, Live call ou Post call.
Configure as definições.
Guarde — as alterações aplicam-se na chamada seguinte.

Todas as entradas são listadas em conjunto na tabela Actions. Clique em qualquer linha para editar, ou use o ícone do caixote do lixo para eliminar.

Relacionados

Visão Geral dos Agentes de Voz IA
Prompt Engineering — Referencie ferramentas no seu prompt
Base de Conhecimento — Fontes de informação
Integrações — Sistemas externos com que as suas ferramentas podem comunicar

As Três Fases​

Pre fetch​

Quando usá-lo​

Como funciona​

Configuração​

Variáveis disponíveis​

O que chega ao prompt​

Restrições importantes​

Ferramentas de Chamada ao Vivo​

Ferramentas Disponíveis​

Call Forwarding​

Google Calendar​

Outlook Calendar​

Agent Transfer​

HubSpot CRM​

MCP servers​

API Tool RAG​

Escrever o Body Parameters Schema​

Estrutura mínima​

Referência de campos​

Exemplos​

Boas práticas para agentes de voz​

Ações de Mensagem ao Vivo​

Limite de envios por chamada​

Matriz de recusa​

Registo na timeline do CRM​

Encadeamento inteligente formulário-para-canal​

Ações Pós-Chamada​

Ações Disponíveis​

Send Email​

Send SMS​

Send WhatsApp​

API Call​

O que o seu endpoint recebe​

Variáveis de Recolha​

Variáveis Padrão​

Tipos de Variável​

Configurar uma Variável​

Show in Form​

Adicionar Ferramentas e Ações​

Relacionados​

As Três Fases

Pre fetch

Quando usá-lo

Como funciona

Configuração

Variáveis disponíveis

O que chega ao prompt

Restrições importantes

Ferramentas de Chamada ao Vivo

Ferramentas Disponíveis

Call Forwarding

Google Calendar

Outlook Calendar

Agent Transfer

HubSpot CRM

MCP servers

API Tool RAG

Escrever o Body Parameters Schema

Estrutura mínima

Referência de campos

Exemplos

Boas práticas para agentes de voz

Ações de Mensagem ao Vivo

Limite de envios por chamada

Matriz de recusa

Registo na timeline do CRM

Encadeamento inteligente formulário-para-canal

Ações Pós-Chamada

Ações Disponíveis

Send Email

Send SMS

Send WhatsApp

API Call

O que o seu endpoint recebe

Variáveis de Recolha

Variáveis Padrão

Tipos de Variável

Configurar uma Variável

Show in Form

Adicionar Ferramentas e Ações

Relacionados