> ## Documentation Index
> Fetch the complete documentation index at: https://help.cloudtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# VoiceAgents para chamadas de saída
> Configure e utilize a funcionalidade VoiceAgent da CloudTalk para gerir chamadas de saída de forma eficiente.
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
***
VoiceAgents para chamadas de saída
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](/pt/articles/11399385-voiceagents-for-inbound-calls) para explorar como utilizar os VoiceAgents em cenários de chamadas recebidas.
Como funciona
As chamadas de saída com [VoiceAgent](/pt/articles/11053795-getting-started-with-voiceagents) são i**niciadas através do [endpoint VoiceAgents da API da CloudTalk](/developers#tag/Voice-Agents/operation/createVoiceAgentCall)**[.](/developers#tag/Voice-Agents/operation/createVoiceAgentCall) 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](/developers#tag/Voice-Agents), 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](/developers#tag/Voice-Agents)**[,](/developers#tag/Voice-Agents) 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](/developers#tag/Voice-Agents) seguindo estas instruções:
1. Na ferramenta à sua escolha **defina o endpoint do pedido à API.** Comece por especificar o endpoint de destino do pedido:
```http theme={"system"}
POST https://api.cloudtalk.io/v1/voice-agent/calls
```
2. 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**
3. 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:**
```bash theme={"system"}
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](/pt/articles/11399385-voiceagents-for-inbound-calls) 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](/pt/articles/14072758-voiceagent-skills#h_d5557cb8f7)** 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:
```json theme={"system"}
{ "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](/pt/articles/14072758-voiceagent-skills#h_364d85c8dd) 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](https://support.cloudtalk.io/hc/en-us/requests/new?ticket_form_id=26305535257884) — estamos aqui para si.
## Related topics
- [Primeiros passos com os VoiceAgents](/pt/articles/11053795-getting-started-with-voiceagents.md)
- [VoiceAgents para Chamadas Recebidas](/pt/articles/11399385-voiceagents-for-inbound-calls.md)
- [Conformidade com a TCPA nas chamadas de saída dos VoiceAgents](/pt/articles/17230144-tcpa-compliance-for-voiceagent-outbound-calls.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.