SIP trunk documentation
Quick start
1. Create a workspace → https://console.whatsmcp.com/register
2. Link a WhatsApp number → Console → Pair device (scan the QR with your phone)
3. Put it on a plan with calls → Console → the number → Plan (see Voice plans)
4. Connect SIP → Console → the number → SIPWhatsMCP bridges WhatsApp voice calls to SIP. A WhatsApp call to your number rings your PBX or a softphone; a call you place from SIP goes out as your own WhatsApp number. The bridge decodes WhatsApp’s Opus and MLow audio and hands your side ordinary G.722 or G.711 — your phone system never learns that MLow exists.
Two ways to connect, same result: take a hosted SIP line (we run the phone system) or bring your own PBX. Both are configured on the number’s SIP page in the console.
This is not the WhatsApp Business Calling API. WhatsMCP links a regular WhatsApp number as a device and speaks the protocol directly — no Meta business verification. It is unofficial, not affiliated with Meta, and outside WhatsApp’s terms of service: numbers can be blocked. See About this service.
How it works
The bridge registers to a SIP server like any ordinary extension — no module, agent or fork of your PBX, and no inbound firewall rule for signalling. On one side it holds a SIP registration; on the other it holds your linked WhatsApp session. A call is live only when both are up: SIP registered and WhatsApp connected.
SIP phone / PBX / CRM ⇄ WhatsMCP bridge ⇄ WhatsApp
G.722 / G.711 transcode Opus / MLow (encrypted)One WhatsApp number carries one call at a time. A second call while one is up is refused as busy — add numbers for parallel calls.
Voice plans and call direction
Calls are part of a number’s plan: one flat monthly price per number covering its messaging and its calls, with no per-minute billing. A number needs a plan that includes calls before its SIP page unlocks — without one, the SIP page stays locked with “SIP needs a voice plan.” Prices are on the plans page.
The plan also sets the direction the bridge will carry:
| Plan includes | WhatsApp → SIP | SIP → WhatsApp | Use it for |
|---|---|---|---|
| Incoming and outgoing | ✅ rings your extension | ✅ dials out as your number | Full two-way calling |
| Outgoing only | — declined | ✅ dials out as your number | Click-to-call, outbound campaigns |
| Incoming only | ✅ rings your extension | — refused (403) | A support line that only receives |
Change a number’s plan or its direction in Console → the number → Plan; the bridge picks up the new mode on its next start.
Option A: Hosted SIP line
You don’t need your own PBX. We run the phone system; you register any SIP phone or softphone to the line we give you.
- Open Console → the number → SIP and choose Hosted line.
- The console provisions the line and shows its credentials once — host, port, username and password. Copy them now; the password is stored only as a hash and can be rotated, never shown again.
- Register a softphone (or a phone, or your CRM’s dialer) with those credentials.
Your username is your WhatsApp number in E.164 digits without the + (so +44 7700 900123
registers as 447700900123).
| SIP domain | sip.whatsmcp.com |
| Port / transport | 5061 / TLS — the recommended, encrypted setup |
| Media encryption | SRTP (SDES) — turn it on in your phone. The WhatsApp side of every call is always encrypted regardless |
| Without TLS | Plain UDP on 5060, only if your phone can’t do TLS — signalling and media are then unencrypted |
WhatsApp calls to your number ring that phone; calls you dial from it go out as your WhatsApp number. To try a line without a physical phone, the SIP page also has a browser test dialer that registers in the tab and places or answers one call — handy for confirming setup before you wire up a device.
Option B: Bring your own PBX
Point the bridge at your existing Asterisk, FreePBX, 3CX, or the phone system inside your CRM. It registers outbound to your registrar as a normal extension, so there is no inbound firewall rule to open for signalling.
Open Console → the number → SIP, choose Your own PBX, and enter:
| Field | What to put |
|---|---|
| Registrar | Your SIP server, host or host:port |
| Username | The extension the bridge logs in as |
| Password | Its secret — stored encrypted (AES-256-GCM) |
| Realm | Optional — set it only if your server uses a realm other than the host |
| Ring target | The extension a WhatsApp call should ring, e.g. 101. caller rings a hunt entry named after the WhatsApp caller; 9:caller prefixes a group |
Before it saves, the console runs a live REGISTER probe against your server, so wrong
credentials are caught at setup instead of crash-looping the number later. Test connection on
the SIP page re-runs it and shows the bridge’s live sip_registered state.
Transport is UDP by default, or TLS (encrypted signalling) where your server offers it — your PBX must present a publicly-issued certificate for the registrar host. Call media on a bring-your-own trunk is plain RTP either way.
Making and receiving calls
Receiving (WhatsApp → SIP). An incoming WhatsApp call is answered by the bridge and dialed to your ring target; your extension rings, and media is bridged once you pick up.
Dialing out (SIP → WhatsApp). From your extension, dial the WhatsApp number as E.164 digits
with no leading + — 447700900123 reaches +44 7700 900123. The call goes out as your linked
WhatsApp number. If the number is not on WhatsApp, the call is rejected (and that result is cached
for about three months, so a repeat dial fails fast). A call that WhatsApp does not answer within
the post-dial window (about 12 seconds) is cleared.
Whichever direction, only one call per number runs at a time; a second is refused as busy.
Codecs
Your phone system never sees WhatsApp’s audio formats. The bridge decodes WhatsApp Opus and MLow (the proprietary codec WhatsApp falls back to on constrained networks — no PBX decodes it) and offers your side, in order:
| Offered | Detail | |
|---|---|---|
| G.722 | wideband · 16 kHz | Offered first — the call stays wideband all the way to your phone |
| G.711 µ-law | PCMU · 8 kHz | The fallback every SIP phone, softphone and PBX speaks |
| G.711 A-law | PCMA · 8 kHz | Accepted when your side prefers it |
A phone that only speaks G.711 still works, at narrowband — a clean landline-quality call. Opus toward the PBX is not offered yet.
Egress
You can control where a number’s WhatsApp-side traffic exits to the internet, per account: nominate a WireGuard peer or a SOCKS5 proxy in the console and that number’s WhatsApp traffic leaves through your node instead of the default egress. It changes where the traffic goes, not what WhatsApp does with the account — WhatsApp’s terms still apply.
AI voice agent
Put a conversational AI on the phone: your ElevenLabs voice agent can call a WhatsApp number and hold a real spoken conversation, or answer incoming WhatsApp calls to your number. You bring your own ElevenLabs agent and API key — WhatsMCP connects it to WhatsApp over the same hosted SIP line and reports back a summary, a transcript, the data the agent collected, and a recording.
AI voice agents are rolled out per workspace. If a number has no AI agents page in the console yet, ask us to switch it on for your workspace.
Before you start
- A hosted SIP line on the number (Option A), active and set to the SIP phone client (not the browser dialer). AI agents run on hosted lines, not on a bring-your-own-PBX trunk. Outbound agent calls also need the line’s direction to allow outgoing calls (two-way or outgoing-only).
- A Conversational AI agent built in your ElevenLabs account, and an API key that can reach it.
1. Connect ElevenLabs (once per workspace)
Open Console → the number → AI agents and connect your provider: choose ElevenLabs, an optional label, and paste your API key. The key is verified against ElevenLabs on save, then stored encrypted and write-only — it is never shown again; to change it you paste a new one. The connection belongs to the workspace, so every number’s presets share it.
2. Pair an agent with a number (a preset)
A preset pairs one ElevenLabs agent with one of your numbers — the line it calls from — plus its defaults. On the number’s AI agents page, add a preset:
| Field | What it does |
|---|---|
| Name | The handle you call it by (a–z, 0–9, -, _) — you pass this to the MCP tools |
| Agent | Picked from a live dropdown of your ElevenLabs agents |
| Calls from | Fixed to this number — the line the agent speaks over |
| Default / expected variables | Values merged into every call, and the names the agent’s prompt expects |
| First message | Optional opener that overrides the agent’s own |
| Max duration | Optional hard cap on call length |
| Ring delay / start delay | Wait 0–30 s before answering, and 0–10 s before the agent starts speaking |
3. Place a call (from the MCP server)
Drive outbound agent calls with the MCP server’s AI-call tools:
1. wa_ai_list_presets → pick a preset with ready = true
2. wa_ai_call_start { preset, to, → returns a call_ref (status: dialing)
variables?, first_message? } the call then rings and runs on its own
3. wa_ai_call_get { call_ref } (~every 30s) → status: dialing → in_progress → done
then: summary, successful, collected data,
transcript, recording_url (MP3, valid 1 hour)variables is per-call context merged over the preset’s defaults (e.g.
{"customer_name":"Ann","order_id":"A-1042"}). wa_ai_list_calls pages through past calls
(inbound and outbound), and wa_ai_call_hangup ends a live one. A number runs one call at a
time — AI or human.
Answer incoming calls
Each preset has an answer incoming calls toggle. Turn it on and WhatsApp calls to that
number are answered by the agent instead of ringing your SIP phone (the phone stays silent until
you turn it back off). Answered calls show up in wa_ai_list_calls with direction: inbound.
How it works
WhatsMCP registers a SIP trunk with ElevenLabs pointed at your hosted line’s Asterisk: for an
outbound call the ElevenLabs agent dials out through that trunk, and WhatsMCP bridges it to
WhatsApp exactly like any hosted-line call; for inbound, the line forwards the incoming WhatsApp
call to the agent. Results are fetched by polling, so wa_ai_call_get fills in the summary and
transcript once the call ends. Recordings are served as a signed MP3 link valid for one hour.
Limits
One live AI call per number; by default at least 60 seconds between calls on a line and at most 30 calls per line per day; recording links expire after an hour.
Limits and troubleshooting
| Symptom | Cause / fix |
|---|---|
| SIP page is locked | The number has no plan with calls — see Voice plans |
| Outbound calls refused | Your plan is incoming-only, or the number you dialed is not on WhatsApp |
| Inbound WhatsApp calls declined | Your plan is outgoing-only |
403 on an inbound SIP INVITE | Your plan is incoming-only — outbound SIP dialing is off for that mode |
| Registration fails at setup | The REGISTER probe rejected the credentials — re-check registrar, username, password and realm, then Test connection |
| Second call comes back busy | One call per number is the limit — add numbers for parallel calls |
| No audio / one-way audio | A NAT or firewall is blocking RTP; for hosted lines prefer TLS+SRTP on 5061 |
| No AI agents page on a number | The feature is enabled per workspace — ask us to switch it on |
Preset can’t call (ready is false) | not_ready_reason says why — usually the number needs an active hosted line on the SIP client with outgoing calls allowed |
| AI call refused as throttled | One AI call per number at a time, ≥60 s between calls, ≤30 per line per day |
Every call needs the bridge SIP-registered and WhatsApp connected at the same time; Test connection on the SIP page shows both.
About this service
WhatsMCP links a regular WhatsApp number as a secondary device via a QR scan — your phone stays the primary device and you keep using WhatsApp on it. Because it speaks the WhatsApp protocol directly, there is no Meta business verification and no WhatsApp Business Calling API involved.
It is unofficial, not affiliated with or endorsed by Meta, and its use is outside WhatsApp’s terms of service — a number can be blocked. A dedicated number that lives only on the trunk is available on request. Weigh that before putting a number you depend on onto the bridge.