In this article, you'll learn how to set up and use CloudTalk’s VoiceAgent feature for outbound calls. The guide covers how to trigger automated calls and manage conversations without involving live agents.

User level:

Admin

VoiceAgents for Outbound Calls

VoiceAgent for Outbound Calls enables teams to automate outbound customer interactions by initiating calls through AI-driven agents. It’s ideal for tasks such as follow-ups, appointment confirmations, surveys, or proactive notifications - freeing up live agents for more complex conversations and increasing operational efficiency.

💡 Looking to handle incoming calls with automation instead? Check out the VoiceAgent for Inbound Calls guide to explore how to use VoiceAgents for inbound scenarios.

How it works

Outbound calls using VoiceAgent are initiated through the CloudTalk API. When a call needs to be executed, a request is typically sent from an external tool or CRM to the API, including the necessary details of the person to be contacted. These details typically include data such as the recipient’s phone number and any contextual information the VoiceAgent should use during the conversation.

Call-related data passed within API request is referenced by the VoiceAgent during the interaction, allowing it to respond and behave according to the configuration defined in the VoiceAgent prompt. Additionally, the same data is used in the Call Analysis step to evaluate the outcome of the conversation, following the rules set in the analysis configuration.

The entire process is automated and does not require involvement from a human agent, enabling efficient and scalable outbound communication.

Triggering Outbound VoiceAgent Calls via API

This section explains how to trigger outbound VoiceAgent calls using CloudTalk’s API, including the key configuration steps required to ensure proper execution and data handling.

Prerequisities

VoiceAgents functionality available in CloudTalk Dashboard
Outbound VoiceAgent configured following general VoiceAgents Configuration guide, specifically make sure:
- call direction is set to Outbound in the VoiceAgent configuration.
- outbound number is configured according to your specific requirements, such as branding, region, or campaign goals.

Implementation

Rather than starting calls manually, outbound VoiceAgent calls are initiated through the CloudTalk API, typically as part of a workflow automation using:

HubSpot Workflows
Zapier
Make
Your internal systems
Webhook-based automations

Configure your API Request following these instructions:

In the tool of your choice define the API Request Endpoint. Start by specifying the target endpoint for the request:
```
POST https://api.cloudtalk.io/v1/voice-agent/calls
```
In the headers of configuration configure Authorization header.
```
Authorization: Basic BASE64(api_key_id:api_key)
```
Cloudtalk API is using Basic Authentication, where
- api_key_id : is your API Key ID from CloudTalk Dashboard > Settings > API Keys > API Key Detail > ID
- api_key is your raw API key from CloudTalk Dashboard > Settings > API Keys > API Key Detail > Key
In the request body, configure required fields.
1. call_number - Phone number to be called by voiceagent in E.164 format
2. voice_agent_id - ID of VoiceAgent retrieved from Cloudtalk Dashboard > VoiceAgents
3. call_properties containing
  1. system_prompt variables - passed to the VoiceAgent’s system prompt and visible to the AI during the call. Use them to personalize the call (e.g., {{name}}, {{order_id}}). Only required if you use variables in the VoiceAgent prompt.
  2. output variables - included in the Call Analysis Webhook payload.

⚠️ Only include system_prompt object and output object in the API request if you are actually using variables in the VoiceAgent’s prompt.

Sample API Request:

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
    }
   }
  }
 }'

Understanding System Prompt Variables vs. Output Variables

When configuring a VoiceAgent call via API, you can include two types of variables to enrich the conversation and support post-call processing:

system prompt variables
output variables.

These variables serve different purposes in the VoiceAgent workflow and should be used accordingly.

System Prompt Variables

System prompt variables are visible to the AI during the call and help personalize the conversation or provide essential context for the VoiceAgent. Insert variables into your prompt using double curly brackets ({{ }}).

Prompt Example:

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

When sending the API request, make sure these variables are included in the prompt_variables object in the request body. For instance:

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

If a variable is referenced in the prompt but not passed in the API request, the VoiceAgent will not be able to use it, which may result in errors or a degraded user experience.

Output Variables

Output variables are not visible to the AI during the call. Instead, they are used to attach metadata or context to the conversation that will be available in the Call Analysis Webhook payload after the call ends.

These variables are submitted with the API request and are included in the webhook payload, allowing your systems to process the call outcome with full context, even though the VoiceAgent did not use this data in the conversation.

Example

Let’s say your Call Analysis Prompt is defined like this:

You are an AI assistant that analyzes sales call transcripts. Your task is to extract key information and return it in a specific JSON format:

{
    "is_interested": boolean,
    "user_goals": string,
   
}

In your API request, you include an output variable to pass along external context (in this case customer_id):

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

This value is not visible to the VoiceAgent during the call, but it is included in the Call Analysis webhook payload sent to your external endpoint. The output might look like this:

{
  "call_id" : "52de6f79-8dd4-43e6-8df5-f2a738a0cc55",
  "customer_id" : 12345,
  "is_interested": true,
  "user_goals": "To use CloudTalk to call clients with Voiceagent."
}

This allows you to enrich post-call automation or reporting with additional context that was never part of the spoken conversation.

By combining both types of variables, you can create highly personalized conversations during the call and maintain full operational context afterward - without overloading the AI with unnecessary data.

If you need any further assistance please do not hesitate to reach out to our Support team, we are always happy to help!

Getting Started with CloudTalk guide

Getting Started with VoiceAgents

Tools for VoiceAgent

VoiceAgent Data Capture & Output

VoiceAgents for Inbound Calls