SIP trunks

A SIP trunk is the SIP endpoint an organization points its PBX or carrier at so calls reach a Lua voice agent. These routes create trunks, manage the IP allow list (ACL) and digest-authentication users that secure them, and set the default agent for a trunk. For the setup walkthrough, see Voice calls. Verified against lua-cli 3.33.0.

Base URL and authentication

Every route sits under https://api.heylua.ai/developer/orgs/:orgId/sip-trunks and takes Authorization: Bearer <<YOUR_API_KEY>>; the REST API overview covers keys, scopes, and the error envelope. Every route checks a telephony scope on the organization in the path except agent linking, which checks telephony:write on the agent and telephony:read on the organization: telephony:read lists and inspects, telephony:write creates trunks, ACL entries, and credentials and rotates passwords, and telephony:manage deletes trunks, ACL entries, credentials, and the agent link. There is no CLI equivalent for this family. A POST answers 201.

SIP trunk object

string

Trunk ID; use it in the path of the other routes.

string

SIP domain assigned to the trunk.

string

sip:*@<domain>.sip-<region>.vonage.com, the endpoint to send calls to.

string

One of us, eu, ap.

string

One of provisioning, active, failed, suspended, deleted.

string

TLS requirement: optional, always, or never.

string

SRTP requirement: optional, always, or never.

boolean

Whether digest-authentication users can be created.

string[]

Digest usernames on the trunk. Passwords are never returned here.

object[]

Allowed source addresses.

Show properties

string

CIDR, for example 203.0.113.0/24.

string

Optional label.

number

Unix time in milliseconds.

string

The agent that answers calls on this trunk, once linked.

number

Unix time in milliseconds.

string

User ID of the creator.

string

Creator email, when known.

object

What to configure on your PBX.

Show properties

string

The same host as sipEndpoint with a literal {agent-id} placeholder as the user part; substitute your own user part.

string

Region.

string[]

["TLS"] when tls is always, otherwise ["UDP", "TCP", "TLS"].

number

5061 when tls is always, otherwise 5060.

Endpoints

POST /developer/orgs/:orgId/sip-trunks

Provisions a trunk. Scope telephony:write. A trunk must have at least one ACL entry or digest authentication enabled; otherwise the trunk is recorded as failed and the call answers 400. Answers 201 with the SIP trunk object.

string

default:"us"

One of us, eu, ap.

string[]

Source addresses in CIDR notation; not validated locally, the carrier rejects malformed entries.

boolean

default:false

Allow digest-authentication users on this trunk.

string

default:"optional"

optional, always, or never.

string

default:"optional"

optional, always, or never.

GET /developer/orgs/:orgId/sip-trunks

Lists the organization’s trunks, failed ones included and deleted ones excluded. Scope telephony:read. Response 200 with { trunks: SipTrunk[], count }, where count is the page length.

GET /developer/orgs/:orgId/sip-trunks/:trunkId

Returns one SIP trunk object. Scope telephony:read. 404 when unknown or deleted.

DELETE /developer/orgs/:orgId/sip-trunks/:trunkId

Deletes the trunk at the carrier and marks the record deleted, so it no longer appears in list or get; its credentials and ACL entries go with it. Scope telephony:manage. Response 200 with { "success": true }.

POST /developer/orgs/:orgId/sip-trunks/:trunkId/acl

Adds an address to the allow list. Scope telephony:write. A trunk holds at most 16 ACL entries. Answers 201 with the updated SIP trunk object.

string

required

CIDR, for example 203.0.113.0/24.

string

Label for the entry.

DELETE /developer/orgs/:orgId/sip-trunks/:trunkId/acl/:ip

Removes an address from the allow list. Scope telephony:manage. URL-encode the CIDR in the path (/ becomes %2F). The last entry cannot be removed, even on a trunk with digest authentication; add its replacement first. Answers 200 with the updated object.

POST /developer/orgs/:orgId/sip-trunks/:trunkId/credentials

Creates a digest-authentication user. Scope telephony:write. Requires digestAuthEnabled; a trunk holds at most 200 users. The password, 24 letters and digits, is returned once, in this response only.

string

required

5 to 32 characters, alphanumeric and dashes, starting and ending with an alphanumeric character.

Response 201 with { username, password }.

GET /developer/orgs/:orgId/sip-trunks/:trunkId/credentials

Lists digest usernames as { users: string[] }. Scope telephony:read.

DELETE /developer/orgs/:orgId/sip-trunks/:trunkId/credentials/:username

Deletes a digest user. Scope telephony:manage. Response 200 with { "success": true }.

POST /developer/orgs/:orgId/sip-trunks/:trunkId/credentials/:username/rotate

Generates a new password for a digest user, returned once. Scope telephony:write. Response 201 with { username, password }.

POST /developer/orgs/:orgId/sip-trunks/:trunkId/agents/:agentId

Sets the agent that answers calls on the trunk. Scope telephony:write on the agent, plus telephony:read on the organization. The agent must belong to the organization, and that is checked before the trunk lookup: a foreign agent answers 403 even for an unknown trunk. The route takes no body; per-URI-user and header routing are not available through this API. Answers 201 with the updated object and defaultAgentId set.

DELETE /developer/orgs/:orgId/sip-trunks/:trunkId/agent

Removes the default agent. Scope telephony:manage. 400 when no agent is linked. Answers 200 with the updated object.

Errors

Status	Message	Meaning
`400`	`At least one ACL entry or digest authentication is required for security`	Create body with no `acl` and `enableDigestAuth` false; pass an `acl` or enable digest auth, and delete the `failed` record that remains
`400`	`Maximum 16 ACL entries allowed`	ACL is full; remove an entry first
`400`	`IP already in ACL`	Duplicate CIDR; nothing to do
`400`	`Cannot remove last ACL entry. Add a replacement first.`	Removal would empty the ACL; add the new entry, then remove the old one
`400`	`Digest authentication is not enabled on this trunk`	Credential create on a trunk created without `enableDigestAuth`; create a trunk with it enabled
`400`	`Maximum 200 digest users allowed`	User list is full; delete a user first
`400`	`Username must be 5-32 characters, alphanumeric and dashes only`	Invalid username
`400`	`Username already exists`	Duplicate username; rotate the existing user’s password instead
`400`	`No agent is currently linked to this trunk`	Unlink with no link; nothing to do
`403`	`Agent does not belong to this organization`	Link across organizations; link an agent from the trunk’s organization
`403`	`Insufficient permissions for this organization`	The key lacks `telephony:read` on the organization; grant the scope
`404`	`SIP trunk not found`, `IP not found in ACL`, `User not found`	Unknown record; list and retry

Example

Create a trunk that accepts calls from one address range, then read the endpoint to configure on the PBX.

const response = await fetch('https://api.heylua.ai/developer/orgs/<<YOUR_ORG_ID>>/sip-trunks', {
  method: 'POST',
  headers: { Authorization: 'Bearer <<YOUR_API_KEY>>', 'Content-Type': 'application/json' },
  body: JSON.stringify({ region: 'eu', acl: ['203.0.113.0/24'], tls: 'always', srtp: 'always' }),
});
if (!response.ok) throw new Error(`Trunk creation failed: ${response.status} ${await response.text()}`);
const trunk: { id: string; status: string; connectionDetails: { sipUri: string; port: number; transport: string[] } } =
  await response.json();
console.log(`Point your PBX at ${trunk.connectionDetails.sipUri}:${trunk.connectionDetails.port}`);

curl -X POST "https://api.heylua.ai/developer/orgs/<<YOUR_ORG_ID>>/sip-trunks" \
  -H "Authorization: Bearer <<YOUR_API_KEY>>" \
  -H "Content-Type: application/json" \
  -d '{ "region": "eu", "acl": ["203.0.113.0/24"], "tls": "always", "srtp": "always" }'

SDK

CLI

REST API

Base URL and authentication

SIP trunk object

Endpoints

POST /developer/orgs/:orgId/sip-trunks

GET /developer/orgs/:orgId/sip-trunks

GET /developer/orgs/:orgId/sip-trunks/:trunkId

DELETE /developer/orgs/:orgId/sip-trunks/:trunkId

POST /developer/orgs/:orgId/sip-trunks/:trunkId/acl

DELETE /developer/orgs/:orgId/sip-trunks/:trunkId/acl/:ip

POST /developer/orgs/:orgId/sip-trunks/:trunkId/credentials

GET /developer/orgs/:orgId/sip-trunks/:trunkId/credentials

DELETE /developer/orgs/:orgId/sip-trunks/:trunkId/credentials/:username

POST /developer/orgs/:orgId/sip-trunks/:trunkId/credentials/:username/rotate

POST /developer/orgs/:orgId/sip-trunks/:trunkId/agents/:agentId

DELETE /developer/orgs/:orgId/sip-trunks/:trunkId/agent

Errors

Example

See also

​Base URL and authentication

​SIP trunk object

​Endpoints

​POST /developer/orgs/:orgId/sip-trunks

​GET /developer/orgs/:orgId/sip-trunks

​GET /developer/orgs/:orgId/sip-trunks/:trunkId

​DELETE /developer/orgs/:orgId/sip-trunks/:trunkId

​POST /developer/orgs/:orgId/sip-trunks/:trunkId/acl

​DELETE /developer/orgs/:orgId/sip-trunks/:trunkId/acl/:ip

​POST /developer/orgs/:orgId/sip-trunks/:trunkId/credentials

​GET /developer/orgs/:orgId/sip-trunks/:trunkId/credentials

​DELETE /developer/orgs/:orgId/sip-trunks/:trunkId/credentials/:username

​POST /developer/orgs/:orgId/sip-trunks/:trunkId/credentials/:username/rotate

​POST /developer/orgs/:orgId/sip-trunks/:trunkId/agents/:agentId

​DELETE /developer/orgs/:orgId/sip-trunks/:trunkId/agent

​Errors

​Example

​See also

Base URL and authentication

SIP trunk object

Endpoints

POST /developer/orgs/:orgId/sip-trunks

GET /developer/orgs/:orgId/sip-trunks

GET /developer/orgs/:orgId/sip-trunks/:trunkId

DELETE /developer/orgs/:orgId/sip-trunks/:trunkId

POST /developer/orgs/:orgId/sip-trunks/:trunkId/acl

DELETE /developer/orgs/:orgId/sip-trunks/:trunkId/acl/:ip

POST /developer/orgs/:orgId/sip-trunks/:trunkId/credentials

GET /developer/orgs/:orgId/sip-trunks/:trunkId/credentials

DELETE /developer/orgs/:orgId/sip-trunks/:trunkId/credentials/:username

POST /developer/orgs/:orgId/sip-trunks/:trunkId/credentials/:username/rotate

POST /developer/orgs/:orgId/sip-trunks/:trunkId/agents/:agentId

DELETE /developer/orgs/:orgId/sip-trunks/:trunkId/agent

Errors

Example

See also