Skip to main content
POST
/
sip
/
call
Handler for POST /sip/call endpoint
curl --request POST \
  --url https://api.sayna.ai/sip/call \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from_phone_number": "+15105550123",
  "participant_identity": "caller-456",
  "participant_name": "John Doe",
  "room_name": "call-room-123",
  "to_phone_number": "+15551234567",
  "sip": "<unknown>"
}
'
{
  "participant_id": "PA_abc123",
  "participant_identity": "caller-456",
  "room_name": "call-room-123",
  "sip_call_id": "SC_xyz789",
  "status": "initiated"
}
Initiate an outbound SIP call through LiveKit. The call is connected to the specified room as a SIP participant, enabling real-time voice interactions with external phone numbers.
Requires SIP configuration with an outbound_address and a valid SIP trunk. The room is created automatically if it doesn’t exist, with metadata.auth_id set for tenant isolation.

​
Request fields

FieldTypeRequiredDescription
room_namestringYesThe LiveKit room to connect the call to.
participant_namestringYesDisplay name for the SIP participant in the room.
participant_identitystringYesUnique identity for the SIP participant.
from_phone_numberstringYesCaller ID phone number (must be configured in your SIP provider).
to_phone_numberstringYesDestination phone number to dial.
sipobjectNoPer-request SIP configuration overrides. See SIP configuration overrides.

​
SIP configuration overrides

The optional sip object allows you to override global SIP configuration on a per-request basis. This is useful when you need to use different SIP providers or credentials for specific calls.
FieldTypeDescription
outbound_addressstring|nullSIP server address override. Format: hostname or hostname:port.
auth_usernamestring|nullSIP authentication username override.
auth_passwordstring|nullSIP authentication password override.
Existing requests without the sip object continue to work unchanged. The global server configuration is used when per-request overrides are not provided.

​
Configuration priority

When the sip object is provided, its fields take priority over global server configuration: Request body sip config > Global server config
Request Body FieldOverrides Global Config
sip.outbound_addresssip.outbound_address
sip.auth_usernamesip.outbound_auth_username
sip.auth_passwordsip.outbound_auth_password
If neither the request body nor global config provides an outbound_address, the call will fail with an OUTBOUND_ADDRESS_NOT_CONFIGURED error.

​
Example requests

{
  "room_name": "call-room-123",
  "participant_name": "John Doe",
  "participant_identity": "caller-456",
  "from_phone_number": "+15105550123",
  "to_phone_number": "+15551234567"
}

​
Authorization

Access is controlled via room metadata:
  • When auth.id is present and the room exists: requires room.metadata.auth_id == auth.id
  • When auth.id is present and room doesn’t exist: room is created with metadata.auth_id set
  • When auth.id is absent: access is allowed (backward-compatible mode)

​
Error responses

StatusCondition
400 Bad RequestInvalid phone number format or empty required fields.
404 Not FoundRoom exists with a different tenant’s auth_id (masked as not found).
500 Internal Server ErrorLiveKit not configured, outbound address missing, or call failed.
Phone numbers support international format (+1234567890), national format (07123456789), or internal extensions (1234).

Authorizations

​
Authorization
string
header
required

JWT token obtained from the authentication service. Required when AUTH_REQUIRED is enabled.

Body

application/json

Request body for initiating an outbound SIP call

Example

{
  "room_name": "call-room-123",
  "participant_name": "John Doe",
  "participant_identity": "caller-456",
  "from_phone_number": "+15105550123",
  "to_phone_number": "+15551234567",
  "sip": {
    "outbound_address": "sip.provider.com",
    "auth_username": "user123",
    "auth_password": "secret"
  }
}

SIP Configuration Priority

The sip object is optional. When provided, its fields take priority over global server configuration values. This allows per-request customization of SIP settings.

Priority order: Request body sip config > Global server config

  • outbound_address: Overrides sip.outbound_address from config
  • auth_username: Overrides sip.outbound_auth_username from config
  • auth_password: Overrides sip.outbound_auth_password from config

If neither the request body nor global config provides an outbound_address, the call will fail with OUTBOUND_ADDRESS_NOT_CONFIGURED error.

​
from_phone_number
string
required

Phone number the call will originate from. Must be configured in your SIP provider. Supports international format (+1234567890).

Example:

"+15105550123"

​
participant_identity
string
required

Identity for the SIP participant in the room

Example:

"caller-456"

​
participant_name
string
required

Display name for the SIP participant in the room

Example:

"John Doe"

​
room_name
string
required

The LiveKit room name to connect the call to

Example:

"call-room-123"

​
to_phone_number
string
required

Phone number to dial. Supports international format (+1234567890), national format (07123456789), or extensions (1234).

Example:

"+15551234567"

​
sip
object

Optional per-request SIP configuration overrides. When provided, these values take priority over the global server configuration. This allows using different SIP providers or credentials for specific calls.

Response

Call initiated successfully

Response for a successful SIP call initiation

Example

{
  "status": "initiated",
  "room_name": "call-room-123",
  "participant_identity": "caller-456",
  "participant_id": "PA_abc123",
  "sip_call_id": "SC_xyz789"
}
​
participant_id
string
required

The unique participant ID assigned by LiveKit

Example:

"PA_abc123"

​
participant_identity
string
required

The identity of the SIP participant in the room

Example:

"caller-456"

​
room_name
string
required

The room name where the call was connected

Example:

"call-room-123"

​
sip_call_id
string
required

The unique SIP call ID for tracking

Example:

"SC_xyz789"

​
status
string
required

Status of the call request ("initiated")

Example:

"initiated"