The Robo Voice Call API enables automated outbound voice calls for delivering pre-recorded or dynamically generated messages. Perfect for appointment reminders, notifications, alerts, and promotional campaigns.
Overview
Unlike conversational calls, robo calls deliver a specific message without complex AI interaction. They’re ideal for:
- Appointment reminders
- Delivery notifications
- Emergency alerts
- Survey invitations
- Promotional messages
Endpoint
POST https://voice.intron.io/api/v1/voice-bot/call
Authentication
Authorization: Bearer YOUR_API_KEY
Request
| Header | Value | Required |
|---|
Authorization | Bearer YOUR_API_KEY | Yes |
Content-Type | application/json | Yes |
Body Parameters
| Parameter | Type | Required | Description |
|---|
phone_number | string | Yes | Destination phone number (E.164 format) |
message | string | Yes* | Text message to speak (TTS) |
audio_url | string | Yes* | URL to pre-recorded audio file |
voice | string | No | Voice ID for TTS (default: ‘en-female-1’) |
caller_id | string | No | Caller ID to display |
language | string | No | Language code (default: ‘en’) |
retry_count | integer | No | Number of retry attempts (default: 0, max: 3) |
retry_delay | integer | No | Delay between retries in minutes (default: 5) |
callback_url | string | No | Webhook URL for call events |
schedule_at | string | No | ISO 8601 timestamp to schedule the call |
variables | object | No | Variables for message templating |
Either message or audio_url is required, but not both.
Example Requests
Using TTS Message
curl -X POST https://voice.intron.io/api/v1/voice-bot/call \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+1234567890",
"message": "Hello {{name}}, this is a reminder that your appointment is scheduled for {{date}} at {{time}}. Press 1 to confirm or 2 to reschedule.",
"voice": "en-female-1",
"variables": {
"name": "John",
"date": "January 20th",
"time": "2:30 PM"
},
"callback_url": "https://yourapp.com/webhooks/voice"
}'
Using Pre-recorded Audio
curl -X POST https://voice.intron.io/api/v1/voice-bot/call \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+1234567890",
"audio_url": "https://yourserver.com/audio/reminder.mp3",
"callback_url": "https://yourapp.com/webhooks/voice"
}'
Scheduled Call
curl -X POST https://voice.intron.io/api/v1/voice-bot/call \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+1234567890",
"message": "Good morning! This is your scheduled wake-up call.",
"schedule_at": "2024-01-20T07:00:00Z"
}'
Response
Success Response (200 OK)
{
"status": "success",
"call_id": "robo_abc123def456",
"message": "Call queued",
"scheduled_at": null,
"estimated_start": "2024-01-15T10:30:05Z"
}
Scheduled Call Response
{
"status": "success",
"call_id": "robo_abc123def456",
"message": "Call scheduled",
"scheduled_at": "2024-01-20T07:00:00Z"
}
{
"phone_number": "+1234567890",
"message": "Press 1 to confirm your appointment, or press 2 to cancel.",
"dtmf_config": {
"enabled": true,
"timeout": 10,
"max_digits": 1,
"actions": {
"1": {
"action": "webhook",
"url": "https://yourapp.com/confirm",
"response_message": "Your appointment has been confirmed. Thank you!"
},
"2": {
"action": "webhook",
"url": "https://yourapp.com/cancel",
"response_message": "Your appointment has been cancelled. Goodbye."
}
}
}
}
Batch Calls
Send multiple calls in a single request:
POST https://voice.intron.io/api/v1/voice-bot/call/batch
{
"calls": [
{
"phone_number": "+1234567890",
"message": "Hello {{name}}, reminder for {{date}}.",
"variables": {"name": "John", "date": "Monday"}
},
{
"phone_number": "+0987654321",
"message": "Hello {{name}}, reminder for {{date}}.",
"variables": {"name": "Jane", "date": "Tuesday"}
}
],
"voice": "en-female-1",
"callback_url": "https://yourapp.com/webhooks/voice"
}
Batch Response
{
"status": "success",
"batch_id": "batch_xyz789",
"total_calls": 2,
"calls": [
{"call_id": "robo_abc123", "phone_number": "+1234567890", "status": "queued"},
{"call_id": "robo_def456", "phone_number": "+0987654321", "status": "queued"}
]
}
Get Call Status
GET https://voice.intron.io/api/v1/voice-bot/call/{call_id}
Response
{
"call_id": "robo_abc123def456",
"status": "completed",
"phone_number": "+1234567890",
"duration": 25,
"created_at": "2024-01-15T10:30:00Z",
"started_at": "2024-01-15T10:30:05Z",
"ended_at": "2024-01-15T10:30:30Z",
"dtmf_input": "1",
"call_result": "answered"
}
Webhook Events
Call Answered
{
"event": "robo_call.answered",
"call_id": "robo_abc123def456",
"phone_number": "+1234567890",
"timestamp": "2024-01-15T10:30:05Z"
}
DTMF Received
{
"event": "robo_call.dtmf",
"call_id": "robo_abc123def456",
"digit": "1",
"timestamp": "2024-01-15T10:30:20Z"
}
Call Completed
{
"event": "robo_call.completed",
"call_id": "robo_abc123def456",
"phone_number": "+1234567890",
"duration": 25,
"result": "answered",
"dtmf_input": "1",
"timestamp": "2024-01-15T10:30:30Z"
}
Call Results
| Result | Description |
|---|
answered | Call was answered |
voicemail | Call went to voicemail |
busy | Line was busy |
no_answer | No answer after timeout |
failed | Call failed to connect |
rejected | Call was rejected |
Cancel a Call
Cancel a scheduled or queued call:
DELETE https://voice.intron.io/api/v1/voice-bot/call/{call_id}
Response
{
"status": "success",
"message": "Call cancelled",
"call_id": "robo_abc123def456"
}
Rate Limits
| Plan | Calls/minute | Concurrent Calls |
|---|
| Free | 10 | 2 |
| Pro | 100 | 20 |
| Enterprise | Custom | Custom |
Best Practices
Ensure compliance with local telecommunications regulations (TCPA, GDPR, etc.) before making automated calls.
- Respect Time Zones: Schedule calls during appropriate hours
- Provide Opt-out: Include an option to stop receiving calls
- Keep Messages Concise: Short, clear messages have better engagement
- Handle Failures: Implement retry logic for important notifications
- Monitor Results: Track call outcomes to optimize delivery rates
