Skip to main content

​
Voice API

The Voice API gives you programmatic control over voice interactions — start calls, check status, retrieve recordings, and manage sessions. Use it to build custom voice experiences in your applications.

​
Authentication

All voice API endpoints require a Bearer token: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.thinnest.ai/voice/...

​
Endpoints

​
Start an Outbound Call

POST /voice/outbound/dial 
curl -X POST "https://api.thinnest.ai/voice/outbound/dial" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_xyz",
    "to_number": "+14155551234",
    "from_number": "+18005551234",
    "context": {
      "customer_name": "Jane Doe",
      "order_id": "ORD-123"
    },
    "max_duration": 300,
    "recording": true,
    "webhook_url": "https://your-app.com/call-events"
  }'
Parameters:
FieldTypeRequiredDescription
agent_idstringYesVoice agent to use
to_numberstringYesDestination number (E.164)
from_numberstringYesCaller ID (must be verified)
contextobjectNoData passed to agent’s prompt
max_durationintegerNoMax call length in seconds (default: 600)
recordingbooleanNoRecord the call
scheduled_atstringNoISO 8601 timestamp for scheduled call
webhook_urlstringNoURL for call status events
Response: 
{
  "call_id": "call_abc123",
  "status": "initiating",
  "agent_id": "agent_xyz",
  "to_number": "+14155551234",
  "created_at": "2026-03-07T10:00:00Z"
}

​
Start a Voice Session (WebRTC)

POST /voice/start Creates a WebRTC session for browser-based voice: 
curl -X POST "https://api.thinnest.ai/voice/start" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_xyz",
    "context": {
      "user_name": "Jane",
      "page": "pricing"
    }
  }'
Response: 
{
  "session_id": "session_abc123",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "websocket_url": "wss://voice.thinnest.ai/ws/session_abc123",
  "livekit_url": "wss://livekit.thinnest.ai"
}
Use the returned token and livekit_url to connect via WebRTC.

​
Get Session Status

GET /voice/status/{session_id} 
curl "https://api.thinnest.ai/voice/status/session_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
{
  "session_id": "session_abc123",
  "status": "completed",
  "duration": 145,
  "agent_id": "agent_xyz",
  "to_number": "+14155551234",
  "from_number": "+18005551234",
  "started_at": "2026-03-07T10:00:05Z",
  "ended_at": "2026-03-07T10:02:30Z",
  "tokens_used": 1250
}

​
List Voice Sessions

GET /voice/sessions 
curl "https://api.thinnest.ai/voice/sessions?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
Query Parameters:
ParameterTypeDescription
agent_idstringFilter by agent
statusstringFilter by status (completed, failed, in_progress)
limitintegerResults per page (default: 20, max: 100)
offsetintegerPagination offset
start_datestringFilter from date (ISO 8601)
end_datestringFilter until date (ISO 8601)

​
Get Session Details

GET /voice/sessions/{session_id} 
curl "https://api.thinnest.ai/voice/sessions/session_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Get Session Transcript

GET /v1/widget/transcript/{session_id} 
curl "https://api.thinnest.ai/v1/widget/transcript/session_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
{
  "call_id": "session_abc123",
  "transcript": [
    { "role": "agent", "text": "Hello, thanks for calling Acme.", "timestamp": 0.5 },
    { "role": "user", "text": "Hi, I need help with my order.", "timestamp": 2.1 },
    { "role": "agent", "text": "Of course! What's your order number?", "timestamp": 3.8 }
  ]
}

​
Get Recording

GET /voice/recording/{recording_id} Returns the recording details: 
curl "https://api.thinnest.ai/voice/recording/rec_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
End a Voice Session

POST /voice/end/{session_id} 
curl -X POST "https://api.thinnest.ai/voice/end/session_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Webhook Events

If you provide a webhook_url when starting a call, you’ll receive POST requests with call status updates: 
{
  "event": "call.completed",
  "call_id": "call_abc123",
  "status": "completed",
  "duration": 145,
  "timestamp": "2026-03-07T10:02:30Z"
}

​
Event Types

EventDescription
call.initiatingCall is being set up
call.ringingPhone is ringing
call.in_progressCall connected, conversation active
call.completedCall ended normally
call.failedCall failed to connect
call.no_answerNo answer after timeout

​
Integration Example: Appointment Reminders

import httpx
from datetime import datetime, timedelta

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.thinnest.ai"

async def send_reminder(customer_phone: str, appointment_time: str):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{BASE_URL}/voice/outbound/dial",
            headers={"Authorization": f"Bearer {API_KEY}"},
            json={
                "agent_id": "agent_reminder",
                "to_number": customer_phone,
                "from_number": "+18005551234",
                "context": {
                    "appointment_time": appointment_time,
                    "purpose": "appointment_reminder"
                },
                "max_duration": 120,
                "webhook_url": "https://your-app.com/call-events",
            },
        )
        return response.json()

# Send a reminder
result = await send_reminder("+14155551234", "March 10 at 2 PM")
print(f"Call ID: {result['call_id']}")

​
Rate Limits

EndpointRate
Start call10/min
Voice session30/min
Get status60/min
List sessions30/min

​
Best Practices

  • Set max_duration to prevent unexpectedly long calls
  • Use context to personalize the agent’s greeting and behavior
  • Enable recording for compliance and quality review
  • Handle webhook events for real-time call tracking
  • Use scheduled calls for time-sensitive outreach (reminders, follow-ups)