API/Voicebot/Call
Place a Robo call request to a specified phone number.
- Send a voice call request and receive a call ID
- Get the status of the call using the call ID Get call processing status
Authentication
All API requests require an API key to be included in the headers:
Authorization: Bearer [access-key]
Endpoint
POST
https://voicebot.intron.health/voicebot/v1/robocall/call
Request Body JSON
| Field | Type | Description | Required | Options | Default |
|---|---|---|---|---|---|
workflow_id |
String | Unique identifier for the workflow to be executed | yes | ||
workflow_params |
Array | Array of objects containing phone numbers and workflow variables. Phone number is required for each entry. | yes | ||
tts_voice_accent |
String | Accent for the voice used on the call | no |
|
|
tts_voice_gender |
String | Gender of the voice used on the call | no | male | female |
Basic request and response sample
curl --location 'https://voicebot.intron.health/voicebot/v1/call' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer api-key' \
--data '{
"tts_voice_accent": "igbo",
"tts_voice_gender": "female",
"workflow_id": "9b643eb4-0799-4761-bd34-9580eb315aaf",
"workflow_params": [
{
"phone_number": "+2348076960623",
"user_tag_identifiers": {"customer_id": "CUST001"},
"workflow_variables": {
"name": "James"
}
}
]
}'
import requests
url = "https://voicebot.intron.health/voicebot/v1/call"
payload = {
"tts_voice_accent": "igbo",
"tts_voice_gender": "female",
"workflow_id": "9b643eb4-0799-4761-bd34-9580eb315aaf",
"workflow_params": [
{
"phone_number": "+2348076960623",
"user_tag_identifiers": {"customer_id": "CUST001"},
"workflow_variables": {
"name": "James"
}
}
]
}
headers = {
"Authorization": "Bearer api-key"
}
response = requests.request("POST", url, headers=headers, json=payload)
print(response.json)
const requestOptions = {
method: "POST",
headers: {
'Authorization': 'Bearer api-Key'
},
body: JSON.stringify(
{
"tts_voice_accent": "igbo",
"tts_voice_gender": "female",
"workflow_id": "9b643eb4-0799-4761-bd34-9580eb315aaf",
"workflow_params": [
{
"phone_number": "+2348076960623",
"user_tag_identifiers": {"customer_id": "CUST001"},
"workflow_variables": {
"name": "James"
}
}
]
}
)
};
fetch("https://voicebot.intron.health/voicebot/v1/call", requestOptions)
.then((response) => response.text())
.then((result) => console.log(result))
.catch((error) => console.error(error));
{
"data": {
"batch_id": "c4971df1-2978-4c06-b32c-7d5ea47256e1"
},
"message": "batch request created successfully",
"status": "Ok"
}
{
"data": {
"call_id": "12a9767f-b865-4404-91d0-a65d4cdt78fs",
"processing_status": "VOICE_CALL_PROCESSED"
},
"message": "call status found",
"status": "Ok"
}
Callback URL on Request Completion
When a workflow request is completed, Intron makes a POST request to your configured callback URL with the following JSON payload. This allows you to receive real-time updates about the status and results of your workflow requests.
Request Payload
{
"request_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "COMPLETED",
"integrator_id": "456e7890-e12b-34d5-b678-526614174111",
"stats": {
"total_calls": 2,
"completed_calls": 2,
"timeout_calls": 0,
"replied_calls": 2,
"response_options_counts": 2,
"avg_duration": 30.0,
"success_rate": 100.0
},
"request_calls": [
{
"id": "aaa111bb-2222-3333-4444-555555555555",
"status": "COMPLETED",
"phone_number": "+23480xxxxxxxx",
"user_tag_identifiers": {"customer_id": "CUST001"},
"call_result_duration": 32,
"call_result_options_selected": "1",
"created_at": "2024-06-21T10:00:00.000000"
},
{
"id": "bbb222cc-3333-4444-5555-666666666666",
"status": "COMPLETED",
"phone_number": "+23480xxxxxxxx",
"user_tag_identifiers": {"customer_id": "CUST002"},
"call_result_duration": 28,
"call_result_options_selected": "2",
"created_at": "2024-06-21T10:01:00.000000"
}
]
}
Expected Response: Your server should return HTTP 200 to acknowledge receipt of the callback.
Workflow Message Requirements
- The message length after replacing variables must not exceed 1000 characters
- Use [parameter_name] syntax to insert dynamic values in your message
- Example: "Hello [name], your appointment is scheduled for [date] at [time]"
- To accept a reply, include a reply instruction at the end of your message template (e.g. Send 1 to confirm, 2 to cancel). Reply can either be the number 1 or 2.
Premium Voices
Premium voices offer enhanced quality and more natural-sounding speech synthesis for your robocalls. These voices are marked with a Premium badge in the voice selection.
Available Premium Voice Combinations:
Ibibio (Female) Premium
Hausa (Male) Premium
French (Male) Premium
Igbo (Female) Premium
Fulani (Male) Premium
Afrikaans (Male) Premium
Arabic (Female) Premium
Yoruba (Female) Premium
Urhobo (Male) Premium
Igala (Male) Premium
Chichewa (Female) Premium
Igala (Female) Premium
Epie (Male) Premium
Isoko (Male) Premium
Nyandang (Female) Premium
Luhya (Male) Premium
Ebira (Male) Premium
Bette (Male) Premium
Zulu (Female) Premium
Tswana (Female) Premium
Sesotho (Male) Premium
Twi (Female) Premium
Bette (Female) Premium
Ibibio (Male) Premium
Afrikaans (Female) Premium
Bajju (Female) Premium
Amharic (Female) Premium
Kanuri (Female) Premium
Ebira (Female) Premium
Benefits for Robocalls:
- Enhanced audio quality for better call clarity
- More natural-sounding speech synthesis
- Improved customer experience and engagement
- Professional voice quality for business communications
Quotas and Limits
- Rate limit: 5 requests per second