Custom SIP

Speaknode supports connecting any SIP telephony — your own PBX (Mango Office, Asterisk, FreeSWITCH, a virtual PBX from a provider) — over standard SIP. This is an alternative to the Twilio and VoxImplant integrations for setups where you already have your own SIP trunk.

Architecture

A Custom SIP connection has two sides, each with its own configuration. Both sides must be set up for calls to flow in both directions.

PSTN ──► Your PBX ──SIP INVITE──► LiveKit SIP gateway ──► AI agent (LiveKit room)
PSTN ◄── Your PBX ◄──SIP INVITE── LiveKit SIP gateway ◄── AI agent (outbound)

What to configure on the platform side

In Speaknode you create a Custom SIP account — the bundle of parameters describing your PBX. Once created, the platform returns the public LiveKit data (gateway domain and our outbound IPs) that you share with the PBX side.

What to configure on the PBX side

On your SIP PBX (Mango, Asterisk, etc.) you set up three things: where to forward inbound calls, who is allowed for outbound, and authentication (if used).

Pass call data to the agent

The agent knows who is calling and which number was dialled, and can receive any data of yours about the call (amount, contract number, customer name).

Number in To — the number bound to the agent, exactly as you imported it (e.g. 71234567890). It selects the agent; a call to another number or in another format (+7… instead of 7…, an extension like 1001) is rejected.

Number in From — the caller's number. The agent sees it as the variable {{system__from_number}}; call history shows it as the customer's number.

Your own data — as X-* headers in the INVITE:

INVITE sip:[email protected] SIP/2.0
From: <sip:[email protected]>;tag=…
To: <sip:[email protected]>
X-minimumAmount: 15000
X-loan-id: L-42

To turn headers into agent variables:

1. Declare the variables on the agent — e.g. minimumAmount and loan_id — and use them in the prompt or first message: {{minimumAmount}}.
2. In the phone number card (Phone Numbers → number), block SIP headers → agent variables, set the prefix X-.

Header X-minimumAmount fills variable minimumAmount: the prefix is stripped, case does not matter, - and _ are the same (X-loan-id → loan_id). Only variables declared on the agent are filled; system variables (system__*) are never filled from headers. A value is up to 1024 characters, at most 50 variables per call.

The prefix selects headers for variables. Every header of the INVITE is stored regardless, including the standard ones (P-Asserted-Identity, Diversion, User-Agent) — you can see them on the call card, see Debugging.

Values are substituted into the agent's system prompt and first message the same way as outbound-call variables, and are kept in the call history.

Debugging: what the PBX actually sent

A variable came out empty, and it is unclear why: the PBX did not send the header, sent it under another name, or the variable is not declared on the agent. To tell these apart, every incoming call stores all the headers of its INVITE — not only the ones that matched the prefix and the agent's schema.

Look here: Conversations → Calls → the call → SIP INVITE headers.

The table holds exactly what arrived: names in lower case, values as they came. Next to it, the Agent variables block shows what of it reached the agent. Comparing the two answers the question:

Headers are stored regardless of the prefix and the agent's schema, so the table fills in even before any mapping is configured: first see what the PBX sends, then set up the prefix and the variables.

Authentication modes

A Custom SIP account configures two directions independently — outbound and inbound. For each, you choose one of two modes:

When editing an account, the password field has three states:

• Untouched — current password is kept
• Explicitly cleared — auth is disabled (clear the username too)
• New value entered — password is replaced

Verify and Reprovision

The Custom SIP account card exposes two diagnostic operations:

Verify

The Verify button runs a health check and shows four checks:

Each check is OK / Failed / Skipped. On Failed the reason is shown.

Reprovision

The Reprovision button deletes and recreates the LiveKit trunks from the current DB config. Use it in two cases:

• After editing credentials / server / transport on the account card (changes auto-reinitialize trunks; reprovision is a fallback if auto reinit didn't catch)
• If LiveKit was unavailable when you first created the account or bound a number and the trunks didn't get created (HTTP 500 on bind / create)

Deleting the account

When you delete a Custom SIP account (the Delete button on the card), the platform:

1. Removes all bound numbers
2. Removes the LiveKit inbound / outbound trunks
3. Soft-deletes the account in the DB

Your PBX-side routing to our gateway will remain — clean it up manually in the provider's admin panel if needed.

Common issues