Overview
The Calls API allows you to initiate outbound calls, create web call tokens, and access call logs and recordings.
List Calls
Get call logs with optional filtering.
curl -X GET "https://api.getsmartalex.com/v1/calls" \
-H "Authorization: Bearer YOUR_API_KEY"
Query Parameters
| Parameter | Type | Description |
|---|
agent_id | string | Filter by agent |
campaign_id | string | Filter by campaign |
direction | string | inbound, outbound, or web |
status | string | completed, voicemail, no_answer, failed |
sentiment | string | positive, neutral, negative |
from_date | string | Start date (ISO 8601) |
to_date | string | End date (ISO 8601) |
page | integer | Page number |
per_page | integer | Items per page |
Response
{
"data": [
{
"id": "call_abc123",
"direction": "inbound",
"agent_id": "agent_def456",
"phone_number": "+15551234567",
"contact": {
"id": "contact_xyz789",
"first_name": "John",
"last_name": "Smith"
},
"status": "completed",
"duration": 245,
"sentiment": "positive",
"cost": 0.45,
"created_at": "2024-01-15T14:30:00Z"
}
],
"meta": {
"total": 150,
"page": 1,
"per_page": 20
}
}
Get Call
Retrieve detailed information about a specific call.
curl -X GET "https://api.getsmartalex.com/v1/calls/call_abc123" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"data": {
"id": "call_abc123",
"direction": "inbound",
"agent_id": "agent_def456",
"campaign_id": null,
"phone_number": "+15551234567",
"contact": {
"id": "contact_xyz789",
"first_name": "John",
"last_name": "Smith",
"email": "john@example.com"
},
"status": "completed",
"duration": 245,
"sentiment": "positive",
"cost": 0.45,
"recording_url": "https://recordings.getsmartalex.com/call_abc123.mp3",
"transcript": [
{
"speaker": "agent",
"text": "Hello, thank you for calling ABC Company. This is Alex, how can I help you today?",
"timestamp": 0
},
{
"speaker": "caller",
"text": "Hi, I'd like to schedule an appointment.",
"timestamp": 5
}
],
"summary": "Caller requested to schedule an appointment for next Tuesday at 2pm. Collected contact information and confirmed booking.",
"created_at": "2024-01-15T14:30:00Z",
"ended_at": "2024-01-15T14:34:05Z"
}
}
Create Outbound Call
Initiate an outbound call to a phone number.
curl -X POST "https://api.getsmartalex.com/v1/calls" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent_def456",
"phone_number": "+15551234567",
"contact": {
"first_name": "John",
"last_name": "Smith"
}
}'
Parameters
| Parameter | Type | Required | Description |
|---|
agent_id | string | Yes | Agent to make the call |
phone_number | string | Yes | Number to call (E.164 format) |
contact | object | No | Contact information for personalization |
contact.first_name | string | No | Contact first name |
contact.last_name | string | No | Contact last name |
metadata | object | No | Custom data to attach to call |
Response
{
"data": {
"id": "call_new789",
"direction": "outbound",
"agent_id": "agent_def456",
"phone_number": "+15551234567",
"status": "initiating",
"created_at": "2024-01-16T10:00:00Z"
}
}
Create Web Call Token
Generate a token for initiating web-based calls (for widgets and embedded calling).
curl -X POST "https://api.getsmartalex.com/v1/calls/web-token" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_id": "agent_def456",
"expires_in": 3600
}'
Parameters
| Parameter | Type | Required | Description |
|---|
agent_id | string | Yes | Agent to handle the call |
expires_in | integer | No | Token validity in seconds (default: 3600) |
metadata | object | No | Custom data for the session |
Response
{
"data": {
"token": "wct_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_at": "2024-01-16T11:00:00Z",
"websocket_url": "wss://calls.getsmartalex.com/v1/connect"
}
}
End Call
Terminate an active call.
curl -X POST "https://api.getsmartalex.com/v1/calls/call_abc123/end" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"data": {
"id": "call_abc123",
"status": "completed",
"ended_at": "2024-01-16T10:05:00Z"
}
}
Get Call Recording
Get the recording URL for a completed call.
curl -X GET "https://api.getsmartalex.com/v1/calls/call_abc123/recording" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"data": {
"url": "https://recordings.getsmartalex.com/call_abc123.mp3",
"duration": 245,
"expires_at": "2024-01-16T12:00:00Z"
}
}
Recording URLs are temporary and expire after 1 hour. Request a new URL if the previous one has expired.
Get Call Transcript
Get the full transcript for a completed call.
curl -X GET "https://api.getsmartalex.com/v1/calls/call_abc123/transcript" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"data": {
"call_id": "call_abc123",
"transcript": [
{
"speaker": "agent",
"text": "Hello, thank you for calling ABC Company. This is Alex, how can I help you today?",
"timestamp": 0
},
{
"speaker": "caller",
"text": "Hi, I'd like to schedule an appointment for next week.",
"timestamp": 5
},
{
"speaker": "agent",
"text": "Of course! I'd be happy to help you schedule an appointment. What day works best for you?",
"timestamp": 8
}
],
"summary": "Caller requested to schedule an appointment. Booked for Tuesday at 2pm."
}
}
Call Status
| Status | Description |
|---|
initiating | Call is being set up |
ringing | Phone is ringing |
in_progress | Call is connected and active |
completed | Call ended normally |
voicemail | Reached voicemail |
no_answer | No one answered |
busy | Line was busy |
failed | Call could not be completed |
Error Codes
| Code | Description |
|---|
call_not_found | Call ID doesn’t exist |
agent_not_found | Specified agent doesn’t exist |
agent_not_ready | Agent is not in ready status |
invalid_phone_number | Phone number is invalid |
no_available_slots | No call slots available |
recording_not_available | Recording doesn’t exist or has expired |
