The Conversation Voice Call API enables you to create interactive, AI-powered voice conversations. Build intelligent voice bots that can handle customer inquiries, schedule appointments, conduct surveys, and more.
Overview
Conversation voice calls allow for natural, bi-directional voice interactions where the AI can:
- Understand and respond to user speech in real-time
- Maintain context throughout the conversation
- Handle complex multi-turn dialogues
- Integrate with your backend systems
Endpoint
POST https://voice.intron.io/api/v1/voice-bot/conversation
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) |
bot_id | string | Yes | ID of the configured voice bot |
context | object | No | Initial context data for the conversation |
caller_id | string | No | Caller ID to display |
language | string | No | Primary language for the call (default: ‘en’) |
max_duration | integer | No | Maximum call duration in seconds (default: 600) |
callback_url | string | No | Webhook URL for call events |
recording | boolean | No | Enable call recording (default: false) |
Example Request
curl -X POST https://voice.intron.io/api/v1/voice-bot/conversation \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+1234567890",
"bot_id": "bot_customer_service",
"context": {
"customer_name": "John Doe",
"account_id": "ACC123",
"reason": "billing_inquiry"
},
"language": "en",
"max_duration": 300,
"callback_url": "https://yourapp.com/webhooks/voice",
"recording": true
}'
Response
Success Response (200 OK)
{
"status": "success",
"call_id": "call_abc123def456",
"message": "Call initiated",
"call_status": "dialing",
"estimated_wait": 5
}
Response Fields
| Field | Type | Description |
|---|
status | string | Request status |
call_id | string | Unique call identifier |
message | string | Status message |
call_status | string | Current call status |
Call Status Values
| Status | Description |
|---|
dialing | Call is being placed |
ringing | Phone is ringing |
in_progress | Call is connected and active |
completed | Call ended normally |
failed | Call failed to connect |
busy | Line was busy |
no_answer | No answer after timeout |
Webhook Events
When you provide a callback_url, you’ll receive POST requests for various call events:
Call Connected
{
"event": "call.connected",
"call_id": "call_abc123def456",
"timestamp": "2024-01-15T10:30:00Z",
"duration": 0
}
Conversation Turn
{
"event": "conversation.turn",
"call_id": "call_abc123def456",
"timestamp": "2024-01-15T10:30:15Z",
"turn": {
"speaker": "user",
"text": "I'd like to check my account balance",
"confidence": 0.95,
"intent": "check_balance"
}
}
Call Completed
{
"event": "call.completed",
"call_id": "call_abc123def456",
"timestamp": "2024-01-15T10:35:00Z",
"duration": 300,
"summary": {
"turns": 12,
"outcome": "resolved",
"recording_url": "https://voice.intron.io/recordings/call_abc123def456.mp3"
},
"transcript": [
{"speaker": "bot", "text": "Hello John, how can I help you today?"},
{"speaker": "user", "text": "I'd like to check my account balance"},
{"speaker": "bot", "text": "Of course. Your current balance is $1,234.56."}
]
}
Get Call Status
Check the status of an ongoing or completed call:
GET https://voice.intron.io/api/v1/voice-bot/conversation/{call_id}
Response
{
"call_id": "call_abc123def456",
"status": "in_progress",
"duration": 120,
"turns": 5,
"current_context": {
"intent": "billing_inquiry",
"resolved": false
}
}
End Call
Programmatically end an active call:
POST https://voice.intron.io/api/v1/voice-bot/conversation/{call_id}/end
Request Body
{
"reason": "user_requested",
"goodbye_message": "Thank you for calling. Goodbye!"
}
Bot Configuration
Voice bots are configured in your dashboard. Each bot includes:
- Personality: The bot’s conversational style and tone
- Instructions: System prompt defining the bot’s behavior
- Intents: Actions the bot can recognize and handle
- Integrations: Backend systems the bot can access
- Fallback: Behavior when the bot can’t handle a request
Example Bot Configuration
{
"bot_id": "bot_customer_service",
"name": "Customer Service Bot",
"voice": "en-female-1",
"personality": "friendly and professional",
"instructions": "You are a customer service representative for Acme Corp. Help customers with billing inquiries, account updates, and general questions.",
"intents": [
{
"name": "check_balance",
"description": "User wants to check account balance",
"action": "api_call",
"endpoint": "https://api.acme.com/balance"
},
{
"name": "make_payment",
"description": "User wants to make a payment",
"action": "transfer",
"transfer_to": "+18001234567"
}
],
"fallback": {
"action": "transfer",
"message": "Let me connect you with a human agent."
}
}
Error Responses
400 Bad Request
{
"status": "error",
"error": {
"code": "INVALID_PHONE_NUMBER",
"message": "Phone number must be in E.164 format"
}
}
404 Bot Not Found
{
"status": "error",
"error": {
"code": "BOT_NOT_FOUND",
"message": "No bot found with the specified ID"
}
}
Best Practices
Always provide relevant context data to personalize the conversation and reduce call handling time.
- Provide Context: Pass customer information to enable personalized interactions
- Set Appropriate Timeouts: Configure
max_duration based on expected call length
- Handle Webhooks: Implement webhook handlers for real-time call monitoring
- Enable Recording: Record calls for quality assurance and training (with appropriate consent)
- Test Thoroughly: Test your bot with various scenarios before production deployment
