VoiceAgents para chamadas de saída

Neste artigo, vai aprender a configurar e utilizar a funcionalidade VoiceAgent da CloudTalk para chamadas de saída. O guia explica como acionar chamadas automatizadas e gerir conversas sem envolver agentes humanos.

Nível de utilizador: Admin

O VoiceAgent para chamadas de saída permite às equipas automatizar as interações de saída com os clientes, iniciando chamadas através de agentes com IA. É ideal para tarefas como seguimentos, confirmações de marcações, inquéritos ou notificações proativas — libertando os agentes humanos para conversas mais complexas e aumentando a eficiência operacional.

💡 Pretende antes gerir chamadas recebidas com automatização? Consulte o guia VoiceAgent para chamadas recebidas para explorar como utilizar os VoiceAgents em cenários de chamadas recebidas.

Como funciona

As chamadas de saída com VoiceAgent são iniciadas através do endpoint VoiceAgents da API da CloudTalk. Quando é necessário executar uma chamada, é normalmente enviado um pedido de uma ferramenta externa ou de um CRM para a API, incluindo os dados necessários sobre a pessoa a contactar. Estes dados incluem habitualmente o número de telefone do destinatário e qualquer informação contextual que o VoiceAgent deva utilizar durante a conversa. Os dados relativos à chamada enviados no pedido à API são consultados pelo VoiceAgent durante a interação, permitindo-lhe responder e comportar-se de acordo com o que está definido na configuração do VoiceAgent. Todo o processo é automatizado e não exige a intervenção de um agente humano, permitindo uma comunicação de saída eficiente e escalável.

Acionar chamadas de saída do VoiceAgent através da API

Esta secção explica como acionar chamadas de saída do VoiceAgent através da API da CloudTalk, incluindo os principais passos de configuração necessários para garantir a execução correta e o tratamento adequado dos dados.

Pré-requisitos

Funcionalidade VoiceAgents ativada no seu CloudTalk Dashboard.
Um VoiceAgent para chamadas de saída configurado na sua conta. Pode criá-lo das seguintes formas:
- selecionar um modelo que inclua Direção da chamada de saída
- criar um VoiceAgent personalizado e selecionar Direção da chamada de saída.

Implementação

Em vez de iniciar as chamadas manualmente, as chamadas de saída do VoiceAgent são iniciadas através da API da CloudTalk, normalmente no âmbito de uma automação de fluxo de trabalho que utiliza:

HubSpot Workflows
Zapier
Make
Os seus sistemas internos
Automações baseadas em Webhooks

Configure o seu pedido à API seguindo estas instruções:

Na ferramenta à sua escolha defina o endpoint do pedido à API. Comece por especificar o endpoint de destino do pedido:
POST https://api.cloudtalk.io/v1/voice-agent/calls
Nos cabeçalhos da configuração configure o cabeçalho Authorization.
Authorization: Basic BASE64(api_key_id:api_key)
A API da CloudTalk utiliza Autenticação Básica, em que
- api_key_id : é o ID da sua chave de API em CloudTalk Dashboard > Definições > Chaves da API > Detalhe da chave de API > ID
- api_key é a sua chave de API em bruto em CloudTalk Dashboard > Definições > Chaves da API > Detalhe da chave de API > Chave
No corpo do pedido, configure os campos obrigatórios.
1. call_number - Número de telefone a contactar pelo voiceagent no formato E.164
2. voice_agent_id - O ID do VoiceAgent. Pode obtê-lo no CloudTalk Dashboard → VoiceAgents -> Agentes. Abra o detalhe do VoiceAgent pretendido e copie o ID do URL dessa página.
3. call_properties que contém
  1. variáveis de system_prompt - transmitidas ao system prompt do VoiceAgent e visíveis para a IA durante a chamada. Utilize-as para personalizar a chamada (por exemplo, #{{name}}, #{{order_id}}). Só são necessárias se utilizar variáveis na configuração do VoiceAgent.
  2. variáveis de output - incluídas no payload do Webhook de análise da chamada.

⚠️ Inclua o objeto system_prompt e o objeto output no pedido à API apenas se estiver efetivamente a utilizar variáveis no prompt do VoiceAgent.

Exemplo de pedido à API:

curl \--location 'https://api.cloudtalk.io/v1/voice-agent/calls' \--header 'Content-Type: application/json' \--header 'Authorization: Basic dfjag57df********f5gdf4gs4dgd' \--data '{  "call_number": "+421 903 123 123",  "voice_agent_id": "67eaa636148d700a8dmckaf1",  "call_properties": {    "system_prompt": {      "variables": {        "name": "John"      }    },    "output": {      "variables": {        "customer_id": 12345      }    }  }}'

Variáveis de system prompt vs. variáveis de output

Ao configurar uma chamada de VoiceAgent através da API, pode incluir dois tipos de variáveis para enriquecer a conversa e apoiar o processamento após a chamada:

variáveis de system prompt
variáveis de output.

Estas variáveis têm finalidades diferentes no fluxo de trabalho do VoiceAgent e devem ser utilizadas em conformidade.

Variáveis de system prompt

⚠️ As variáveis de contacto não funcionam em agentes de chamadas de saída. Variáveis como #{{contact.name}} ou #{{caller_number}} são preenchidas automaticamente apenas em agentes de chamadas recebidas. Nos agentes de chamadas de saída, define as suas próprias variáveis personalizadas e transmite os respetivos valores no pedido à API, conforme descrito abaixo. Consulte VoiceAgents para chamadas recebidas para saber como personalizar as chamadas recebidas.

As variáveis de system prompt são visíveis para a IA durante a chamada e ajudam a personalizar a conversa ou a fornecer contexto essencial ao VoiceAgent. Insira as variáveis no seu prompt utilizando chavetas duplas (#{{ }}). Exemplo de saudação:

Hello #{{name}}, I'm calling to confirm your order number #{{order_id}} placed on #{{order_date}}.

Ao enviar o pedido à API, certifique-se de que estas variáveis estão incluídas no objeto system_prompt.variables no corpo do pedido. Por exemplo:

"system_prompt": {
  "variables": {
    "name": "Alex",
    "order_id": "123456",
    "order_date": "2025-05-18"
  }
}

Se uma variável for referenciada no prompt mas não for enviada no pedido à API, o VoiceAgent não a poderá utilizar, o que pode originar erros ou uma experiência de utilizador degradada.

Variáveis de output

As variáveis de output não são visíveis para a IA durante a chamada. Em vez disso, servem para associar metadados ou contexto à conversa, que ficarão disponíveis na análise da chamada e na extração de informações depois de a chamada terminar. Estas variáveis são enviadas com o pedido à API e são incluídas no payload do webhook, permitindo que os seus sistemas processem o resultado da chamada com contexto completo, mesmo que o VoiceAgent não tenha utilizado estes dados na conversa. Exemplo Imagine que a sua competência Extrair informações está configurada assim:

No seu pedido à API, inclui uma variável de output para transmitir contexto externo (neste caso, customer_id):

"output": {  "variables": {    "customer_id": 12345  }}

Este valor não é visível para o VoiceAgent durante a chamada, mas é incluído no payload do webhook enviado depois de a chamada terminar. O payload completo do webhook tem este aspeto:

{  "data": {    "ct_call_context": {      "uuid": "160f677d-d2f2-419d-822d-b45f33e4fe6c",      "status": "Connected",      "datetime": "2026-06-17T08:38:31Z",      "duration": 23    },    "message_left_by_caller": {      "caller_name": null,      "content": null    },    "customer_id": 12345,    "Summary": "The caller confirmed they want a callback tomorrow morning.",    "Callback_Confirmed": true  }}

💡 Todos os payloads de webhook incluem agora um objeto ct_call_context com o UUID, o estado, a hora de início e a duração da chamada. Pode utilizar o campo uuid para localizar a chamada na CloudTalk ou associá-la a registos no seu CRM ou data warehouse. Consulte Competências do VoiceAgent – Extrair informações para ver a referência completa do payload.

Isto permite-lhe enriquecer a automação ou os relatórios pós-chamada com contexto adicional que nunca fez parte da conversa falada.

Ao combinar os dois tipos de variáveis, pode criar conversas altamente personalizadas durante a chamada e manter todo o contexto operacional depois — sem sobrecarregar a IA com dados desnecessários.

Precisa de ajuda ou tem alguma questão? Contacte-nos através do nosso portal de Suporte — estamos aqui para si.

Primeiros passos

Números e portabilidade

IA

AI Sales Dialer

CloudTalk Phone e Go

Mensagens

Dashboard

Integrações

Faturação e subscrição

Notícias e atualizações técnicas

Dashboard antigo

VoiceAgents para chamadas de saída