Calls Endpoints

Endpoints for initiating voice calls (VoIP and SIP) and monitoring their status and transcripts.

Call Types

Agent Studio supports two types of calls:

Type	Protocol	Description
`voip`	WebRTC	In-app calls via browser/mobile microphone
`sip`	SIP/RTP	Phone calls via PSTN through Twilio

Initiate Call

POST /api/v1/calls

Start a new voice call using a workflow.

Request Body:

{
  "workflow_slug": "daily-call",
  "user_id": "user-123",
  "call_type": "voip",
  "user_context": {
    "name": "John Doe",
    "language": "en"
  },
  "metadata": {
    "session_id": "abc123",
    "source": "mobile-app"
  }
}

Required Fields:

Field	Type	Description
`workflow_slug`	string	Workflow to use for this call

Optional Fields:

Field	Type	Default	Description
`user_id`	string	null	External user identifier
`call_type`	string	`voip`	Call type: `voip` or `sip`
`phone_number`	string	null	Phone number for SIP calls (E.164 format)
`user_context`	object		Context data available as `{{user.*}}` in templates
`metadata`	object		Additional metadata stored with call

VoIP Call Example

User joins via WebRTC (browser/app microphone):

{
  "workflow_slug": "daily-call",
  "user_id": "user-123",
  "call_type": "voip",
  "user_context": {
    "name": "John Doe"
  }
}

SIP Call Example

Outbound phone call via Twilio:

{
  "workflow_slug": "welcome-call",
  "user_id": "user-456",
  "call_type": "sip",
  "phone_number": "+919876543210",
  "user_context": {
    "name": "Jane Smith",
    "onboarding_status": "new"
  }
}

For SIP calls, phone_number is required and must be in E.164 format (e.g., +919876543210).

Response:

{
  "call_id": "uuid",
  "room_name": "call-uuid",
  "url": "wss://livekit.example.com",
  "token": "eyJ...",
  "status": "pending"
}

Field	Description
`call_id`	Unique call identifier
`room_name`	LiveKit room name for connection
`url`	LiveKit server WebSocket URL
`token`	JWT token for LiveKit authentication
`status`	Initial call status

For VoIP calls, the client uses the token and url to join via WebRTC. For SIP calls, the worker handles the phone dial-out automatically.

Test Agent Call

POST /api/v1/calls/test-agent

Start a test call with a single agent (no workflow). Useful for testing agents before adding to workflows.

Request Body:

{
  "agent_name": "greeter-agent",
  "user_id": "test-user",
  "user_context": {
    "name": "Tester"
  }
}

Response: Same as Initiate Call.

Test agent calls are always VoIP. SIP calls require a workflow.

Get Call

GET /api/v1/calls/{id}

Get call status and details.

Path Parameters:

Parameter	Type	Description
`id`	uuid	Call ID

Response:

{
  "id": "uuid",
  "workflow_id": "uuid",
  "workflow_slug": "daily-call",
  "user_id": "user-123",
  "status": "completed",
  "direction": "outbound",
  "call_type": "sip",
  "phone_number": "+919876543210",
  "duration_seconds": 180,
  "agent_history": ["greeter-agent", "meal-agent", "feedback-agent"],
  "current_agent": null,
  "metrics": {
    "duration_seconds": 180,
    "stt_latency_ms": 120,
    "llm_latency_ms": 280,
    "tts_latency_ms": 85,
    "total_tokens": 1500,
    "agent_handoffs": 2
  },
  "started_at": "2026-01-17T10:30:00Z",
  "ended_at": "2026-01-17T10:33:00Z",
  "created_at": "2026-01-17T10:29:55Z"
}

Get Call Transcript

GET /api/v1/calls/{id}/transcript

Get the full transcript of a call.

Path Parameters:

Parameter	Type	Description
`id`	uuid	Call ID

Response:

[
  {
    "role": "system",
    "content": "Call started",
    "timestamp": "2026-01-17T10:30:00Z",
    "agent_name": "greeter-agent"
  },
  {
    "role": "assistant",
    "content": "Hello! How are you today?",
    "timestamp": "2026-01-17T10:30:05Z",
    "agent_name": "greeter-agent"
  },
  {
    "role": "user",
    "content": "I'm doing well, thanks!",
    "timestamp": "2026-01-17T10:30:10Z",
    "agent_name": "greeter-agent"
  },
  {
    "role": "assistant",
    "content": "Great! What did you have for breakfast?",
    "timestamp": "2026-01-17T10:30:15Z",
    "agent_name": "meal-agent",
    "tool_call": {
      "name": "save_meal",
      "arguments": { "meal_type": "breakfast" }
    }
  }
]

Get Call Metrics

GET /api/v1/calls/{id}/metrics

Get performance metrics for a call.

Response:

{
  "duration_seconds": 180,
  "stt_latency_ms": 120,
  "llm_latency_ms": 280,
  "tts_latency_ms": 85,
  "total_tokens": 1500,
  "agent_handoffs": 2
}

List Calls

GET /api/v1/calls

List calls with filtering and pagination.

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`page_size`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter by status
`workflow_id`	uuid	Filter by workflow
`user_id`	string	Filter by user
`started_after`	datetime	Filter by start time (after)
`started_before`	datetime	Filter by start time (before)

Response:

{
  "items": [
    {
      "id": "uuid",
      "workflow_id": "uuid",
      "workflow_slug": "daily-call",
      "user_id": "user-123",
      "status": "completed",
      "call_type": "sip",
      "duration_seconds": 180,
      "agent_history": ["greeter-agent", "meal-agent"],
      "started_at": "2026-01-17T10:30:00Z",
      "ended_at": "2026-01-17T10:33:00Z"
    }
  ],
  "total": 100,
  "page": 1,
  "page_size": 20,
  "pages": 5
}

List Active Calls

GET /api/v1/calls/active

List currently active calls.

Query Parameters:

Parameter	Type	Description
`limit`	integer	Max results (default: 50, max: 100)

Response:

[
  {
    "id": "uuid",
    "workflow_slug": "daily-call",
    "user_id": "user-456",
    "status": "active",
    "call_type": "voip",
    "current_agent": "meal-agent",
    "started_at": "2026-01-17T10:35:00Z"
  }
]

Call Status Values

Status	Description
`pending`	Call initiated, waiting for connection
`connecting`	Establishing connection
`active`	Call in progress
`completed`	Call ended normally
`failed`	Call failed to connect
`disconnected`	Call dropped unexpectedly
`timeout`	Call timed out

Call Type Values

Type	Description
`voip`	WebRTC-based in-app call
`sip`	Phone call via SIP/PSTN

Call Direction

Direction	Description
`inbound`	User initiated the call
`outbound`	System initiated the call

SIP Call Flow

For SIP calls, the flow is:

API receives call request with call_type: "sip" and phone_number
LiveKit room is created
Worker is dispatched with phone number in metadata
Worker creates SIP participant via LiveKit SIP service
LiveKit SIP dials out through Twilio trunk
When user answers, audio flows through LiveKit room
Agent interacts with user via voice
Call ends, room is cleaned up

API Request → LiveKit Room → Worker → SIP Server → Twilio → PSTN → Phone

Provider Keys Endpoints

List Provider Keys

GET /api/v1/provider-keys

List configured BYOK provider keys (key values are masked).

Response:

{
  "items": [
    {
      "id": "uuid",
      "provider_type": "stt",
      "provider_name": "deepgram",
      "is_default": true,
      "created_at": "2026-01-17T10:30:00Z"
    }
  ]
}

Create Provider Key

POST /api/v1/provider-keys

Add a BYOK provider key.

Request Body:

{
  "provider_type": "stt",
  "provider_name": "deepgram",
  "api_key": "dg_xxxxx",
  "is_default": true
}

Delete Provider Key

DELETE /api/v1/provider-keys/{id}

Delete a provider key. Returns 204 on success.

Calls Endpoints

On this page