API Reference
Calls API
Access call logs, transcripts, recordings, and quality metrics.
The Calls API allows you to initiate outbound calls and access your call history. Each call record includes metadata, status, duration, transcript, and quality metrics.
API Base URL
Use https://www.nutalk.ai/v1 as the base URL for all API requests. This endpoint is optimized for API access with CORS headers enabled.
Available Endpoints
/v1/calls— Initiate outbound call/v1/calls— List all calls/v1/calls/:id— Get call with transcriptCreate Call
/v1/callsInitiates an outbound call to a phone number using a specified voice channel. The channel must have an agent linked and deployed.
Request Body
Parameters
| Name | Type | Description |
|---|---|---|
channel_idRequired | uuid | The voice channel to use for the call |
toRequired | string | Destination phone number in E.164 format (e.g., +14155551234) |
caller_id | string | Override the caller ID (defaults to channel phone number) |
notes | string | Notes to attach to the call record (max 1000 chars) |
status_callback_url | string | Webhook URL to receive call status updates when the call completes |
Example Request
curl -X POST "https://www.nutalk.ai/v1/calls" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "channel_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "to": "+14155551234", "notes": "Follow-up call for demo scheduling", "status_callback_url": "https://your-app.com/webhooks/call-status"}'Response
{
"success": true,
"data": {
"id": "1ba11348-e440-44de-a5cd-5fe62f4d9df6",
"channel_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"to": "+14155551234",
"from": "+18005550100",
"direction": "outbound",
"status": "queued",
"created_at": "2025-01-05T14:30:00Z"
}
}Webhook Payload
When the call completes, we'll POST the following payload to your status_callback_url:
{
"event": "call.completed",
"call_id": "1ba11348-e440-44de-a5cd-5fe62f4d9df6",
"channel_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"to": "+14155551234",
"from": "+18005550100",
"direction": "outbound",
"status": "completed",
"outcome": "answered",
"duration_seconds": 180,
"completed_at": "2025-01-05T14:33:00Z"
}Error Responses
Your account doesn't have enough credits to place the call.
The channel has no deployed agent version. Deploy an agent first.
You've exceeded your plan's concurrent call limit or hourly call limit.
List Calls
/v1/callsRetrieves a paginated list of calls with filtering options.
Query Parameters
Parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Number of calls to return (1-100, default: 20) |
offset | integer | Number of calls to skip (default: 0) |
status | string | Filter by status: queued, ringing, in-progress, completed, failed, busy, no-answer |
direction | string | Filter by direction: inbound or outbound |
from | string | Filter by caller phone number |
to | string | Filter by recipient phone number |
channel_id | uuid | Filter by channel ID |
started_after | datetime | Filter calls started after this ISO-8601 timestamp |
started_before | datetime | Filter calls started before this ISO-8601 timestamp |
Example Request
curl -X GET "https://www.nutalk.ai/v1/calls?status=completed&direction=inbound&limit=10" \ -H "Authorization: Bearer YOUR_API_KEY"Response
{
"success": true,
"data": [
{
"id": "1ba11348-e440-44de-a5cd-5fe62f4d9df6",
"direction": "inbound",
"status": "completed",
"from_number": "+14155551234",
"to_number": "+18005550100",
"started_at": "2025-01-05T14:30:00Z",
"ended_at": "2025-01-05T14:35:30Z",
"duration_seconds": 330,
"agent_name": "Sales Agent",
"channel_name": "Main Line",
"call_outcome": "appointment_booked",
"is_test": false
}
],
"pagination": {
"total": 1250,
"limit": 10,
"offset": 0,
"has_more": true
}
}Get Call
/v1/calls/:idRetrieves detailed information about a specific call, including the full transcript, recording URL, and quality metrics.
Path Parameters
Parameters
| Name | Type | Description |
|---|---|---|
idRequired | uuid | The call's unique identifier |
Example Request
curl -X GET "https://www.nutalk.ai/v1/calls/1ba11348-e440-44de-a5cd-5fe62f4d9df6" \ -H "Authorization: Bearer YOUR_API_KEY"Response
{
"success": true,
"data": {
"id": "1ba11348-e440-44de-a5cd-5fe62f4d9df6",
"direction": "inbound",
"status": "completed",
"from_number": "+14155551234",
"to_number": "+18005550100",
"started_at": "2025-01-05T14:30:00Z",
"ended_at": "2025-01-05T14:35:30Z",
"duration_seconds": 330,
"agent_name": "Sales Agent",
"channel_name": "Main Line",
"channel_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"call_outcome": "appointment_booked",
"is_test": false,
"transcript": "Agent: Hello, thank you for calling Acme Corp...\nCaller: Hi, I'd like to schedule a demo...",
"transcript_summary": "Customer requested a product demo. Agent scheduled appointment for next Tuesday at 2 PM.",
"recording_url": "https://storage.nutalk.ai/recordings/1ba11348-e440-44de-a5cd-5fe62f4d9df6.mp3",
"metadata": {
"campaign_id": "c3d4e5f6-7890-abcd-ef12-345678901234"
},
"quality_metrics": {
"mos": 4.2,
"jitter_ms": 12.5,
"packet_loss_pct": 0.1
},
"answered_by": "human",
"call_result": "completed",
"credits_charged": 7
}
}Call Statuses
| Status | Description |
|---|---|
| queued | Call is queued and waiting to be initiated |
| ringing | Call is ringing on the recipient's phone |
| in-progress | Call is active and conversation is ongoing |
| completed | Call ended normally after conversation |
| failed | Call failed due to technical error |
| busy | Recipient line was busy |
| no-answer | Call was not answered within timeout |
Quality Metrics
Each completed call includes quality metrics to help you monitor call performance:
| Metric | Description | Good Range |
|---|---|---|
| mos | Mean Opinion Score (voice quality 1-5) | > 4.0 |
| jitter_ms | Network jitter in milliseconds | < 30ms |
| packet_loss_pct | Percentage of lost audio packets | < 1% |
Recording Storage
Recording URLs are signed and expire after 24 hours. Request a fresh URL if you need to access recordings later.