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": {
    "auth_password": "secure_password_456",
    "auth_username": "sip_user_123",
    "outbound_address": "sip.provider.com:5060"
  }
}
'

{
  "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

Field	Type	Required	Description
`room_name`	string	Yes	The LiveKit room to connect the call to.
`participant_name`	string	Yes	Display name for the SIP participant in the room.
`participant_identity`	string	Yes	Unique identity for the SIP participant.
`from_phone_number`	string	Yes	Caller ID phone number (must be configured in your SIP provider).
`to_phone_number`	string	Yes	Destination phone number to dial.
`sip`	object	No	Per-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.

Field	Type	Description
`outbound_address`	string\|null	SIP server address override. Format: `hostname` or `hostname:port`.
`auth_username`	string\|null	SIP authentication username override.
`auth_password`	string\|null	SIP 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 Field	Overrides Global Config
`sip.outbound_address`	`sip.outbound_address`
`sip.auth_username`	`sip.outbound_auth_username`
`sip.auth_password`	`sip.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

Status	Condition
`400 Bad Request`	Invalid phone number format or empty required fields.
`404 Not Found`	Room exists with a different tenant’s `auth_id` (masked as not found).
`500 Internal Server Error`	LiveKit 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

Authentication token for protected endpoints. Can be provided as Authorization: Bearer <token> or ?api_key=<token>. 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.

Show child attributes

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"

SIP hooksReturns the current list of SIP hooks from runtime state. This endpoint requires authentication if `AUTH_REQUIRED=true`. # Returns * `200 OK` - List of SIP hooks * `500 Internal Server Error` - If reading the cache fails

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": {
    "auth_password": "secure_password_456",
    "auth_username": "sip_user_123",
    "outbound_address": "sip.provider.com:5060"
  }
}
'

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

​Request fields

​SIP configuration overrides

​Configuration priority

​Example requests

​Authorization

​Error responses

Authorizations

Body

Example

SIP Configuration Priority

Response

Example

Request fields

SIP configuration overrides

Configuration priority

Example requests

Authorization

Error responses