Integrate voice capabilities into your application using the thinnestAI Voice API for programmatic call control.

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:

Field	Type	Required	Description
`agent_id`	string	Yes	Voice agent to use
`to_number`	string	Yes	Destination number (E.164)
`from_number`	string	Yes	Caller ID (must be verified)
`context`	object	No	Data passed to agent's prompt
`max_duration`	integer	No	Max call length in seconds (default: 600)
`recording`	boolean	No	Record the call
`scheduled_at`	string	No	ISO 8601 timestamp for scheduled call
`webhook_url`	string	No	URL 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:

Parameter	Type	Description
`agent_id`	string	Filter by agent
`status`	string	Filter by status (completed, failed, in_progress)
`limit`	integer	Results per page (default: 20, max: 100)
`offset`	integer	Pagination offset
`start_date`	string	Filter from date (ISO 8601)
`end_date`	string	Filter 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

Event	Description
`call.initiating`	Call is being set up
`call.ringing`	Phone is ringing
`call.in_progress`	Call connected, conversation active
`call.completed`	Call ended normally
`call.failed`	Call failed to connect
`call.no_answer`	No 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

Endpoint	Rate
Start call	10/min
Voice session	30/min
Get status	60/min
List sessions	30/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)

Voice API

On this page