Guides

SIP trunks

A SIP trunk record describes a carrier connection you already have: its gateways, how it authenticates, and the phone numbers (DIDs) on it.

In the dashboard: Deploy → SIP Trunks. Creating and changing trunks needs the admin role or an API key; reading needs any role.

Limitation: Today the platform stores and validates trunk configuration and trunk numbers. It does not register with your trunk, and calls are not placed or received over SIP. Live calls go through Twilio, Plivo or Exotel. Use these endpoints to keep your trunk inventory in one place and to prepare agents; do not plan a launch on SIP calling.

Create a trunk

bash

curl -X POST https://api.sevennadi.si/sip-trunks/trunks \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example Carrier Mumbai",
    "provider": "example-carrier",
    "description": "Primary trunk for collections",
    "auth_type": "userpass",
    "auth_username": "trunk-user",
    "auth_password": "<your trunk password>",
    "gateways": [{"gateway_address": "sip.example.test"}],
    "phone_numbers": [{"phone_number": "+912212345678", "name": "Mumbai DID"}]
  }'

Response, 201:

json

{
  "id": "4b3a2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d",
  "name": "Example Carrier Mumbai",
  "provider": "example-carrier",
  "description": "Primary trunk for collections",
  "auth_type": "userpass",
  "auth_username": "trunk-user",
  "gateways": [{"gateway_address": "sip.example.test"}],
  "allow": "ulaw,alaw",
  "disallow": "all",
  "transport": "transport-udp",
  "direct_media": false,
  "rtp_symmetric": true,
  "force_rport": true,
  "media_encryption": "no",
  "media_encryption_optimistic": false,
  "qualify_frequency": 60,
  "inbound_enabled": true,
  "outbound_leading_plus_enabled": true,
  "phone_numbers": [
    {"id": "6c5d4e3f-2a1b-4c0d-9e8f-7a6b5c4d3e2f", "phone_number": "+912212345678", "name": "Mumbai DID",
     "byot_trunk_id": "4b3a2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d", "telephony_provider": "sip-trunk", "deleted": false,
     "created_at": "2026-10-13T10:40:00Z", "updated_at": "2026-10-13T10:40:00Z"}
  ],
  "is_active": true,
  "created_at": "2026-10-13T10:40:00Z",
  "updated_at": "2026-10-13T10:40:00Z"
}

The password is encrypted at rest and never returned.

Required fields

Field	Rule
`name`, `provider`	Required text
`auth_type`	`userpass` or `ip-based`
`gateways`	At least one, each with a `gateway_address`
`auth_username`, `auth_password`	Required when `auth_type` is `userpass`
`ip_identifiers`	Required when `auth_type` is `ip-based`

Optional settings and their defaults

Field	Default
`allow`	`ulaw,alaw`
`disallow`	`all`
`transport`	`transport-udp`
`direct_media`	`false`
`rtp_symmetric`	`true`
`force_rport`	`true`
`media_encryption`	`no`
`media_encryption_optimistic`	`false`
`qualify_frequency`	`60`
`inbound_enabled`	`true`
`outbound_leading_plus_enabled`	`true`

Errors

Status	Message
400	`name is required` (also `provider`, `auth_type`)
400	`auth_type must be userpass or ip-based`
400	`At least one gateway is required`
400	`gateways[].gateway_address is required`
400	`auth_username and auth_password are required for userpass trunks`
400	`ip_identifiers are required for ip-based trunks`
404	`SIP trunk not found`

List, read, update, delete

bash

curl "https://api.sevennadi.si/sip-trunks/trunks?is_active=true" \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Call	Notes
`GET /sip-trunks/trunks`	Optional `is_active` filter. Returns a list of trunks with their numbers
`GET /sip-trunks/trunks/{trunk_id}`	One trunk
`PATCH /sip-trunks/trunks/{trunk_id}`	Send only the fields to change. `is_active` switches the record on or off; a new `auth_password` replaces the stored one. The merged result is validated with the same rules as create
`DELETE /sip-trunks/trunks/{trunk_id}`	Permanent, together with every number on the trunk

Delete answers with a count:

json

{"message": "Trunk deleted successfully. 1 phone number(s) removed."}

Numbers on a trunk

Add a number:

bash

curl -X POST https://api.sevennadi.si/sip-trunks/trunks/4b3a2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d/numbers \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+912212345679", "name": "Mumbai DID 2"}'

json

{"id": "7d6e5f4a-3b2c-4d1e-8f9a-0b1c2d3e4f5a", "phone_number": "+912212345679", "name": "Mumbai DID 2",
 "byot_trunk_id": "4b3a2c1d-0e9f-4a8b-9c7d-6e5f4a3b2c1d", "telephony_provider": "sip-trunk", "deleted": false,
 "created_at": "2026-10-13T10:44:00Z", "updated_at": "2026-10-13T10:44:00Z"}

Numbers are checked as E.164 (the leading + is optional here). For an extension or a short code, send "e164_check_enabled": false. Otherwise: phone_number must be E.164 (or set e164_check_enabled to false).

GET /sip-trunks/trunks/{trunk_id}/numbers lists a trunk's numbers.
DELETE /sip-trunks/trunks/{trunk_id}/numbers/{phone_number_id} removes one and answers {"message": "Phone number removed from trunk"}.

Trunk numbers are free: nothing is charged to the wallet for them. They do not appear in GET /phone-numbers/all, which lists rented and imported numbers only.

Agents and SIP

An agent's telephony provider can be set to sip-trunk:

bash

curl -X PATCH https://api.sevennadi.si/v2/agent/3c90c3cc-0d44-4b50-8822-8dd25736052a \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"agent_config": {"telephony_provider": "sip-trunk"}}'

This stores the provider on the agent's input and output with audio format pcm. It is configuration only: see the limitations below.

A transfer_call tool may name a SIP URI (sip:agent@pbx.example.test) as its destination; the value is validated and stored. See Function tools.

Limitations

No SIP signalling or media. The platform has no SIP registrar, no outbound SIP dialler and no SIP media path to the voice engine. A trunk record changes nothing about how calls are placed.
An agent set to sip-trunk cannot place live calls through the trunk. In live telephony mode, dialling falls back to the Twilio path and needs Twilio credentials.
Trunk settings such as codecs, transport and qualify_frequency are stored as you send them and are not applied to any network component.
Gateways are not contacted or health-checked. is_active is a flag you set, not a measured state.
Transfers to a SIP URI are stored and reported, not carried out over SIP.
There is no SIP path for inbound calls. A trunk number never rings an agent.

For the full field list see SIP trunks reference.