---
title: "WhatsMCP SIP trunk — documentation"
description: "Take WhatsApp calls on your PBX or a hosted SIP line and dial WhatsApp numbers as your own — setup, call direction, codecs, egress, and the AI voice agent roadmap."
url: "https://whatsmcp.com/docs/sip"
---

# 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 → SIP
```

WhatsMCP 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](#codecs) — your phone system never learns that MLow exists.

Two ways to connect, same result: take a [hosted SIP line](#option-a-hosted-sip-line) (we run the phone system) or [bring your own PBX](#option-b-bring-your-own-pbx). Both are configured on the number’s **SIP** page in the [console](https://console.whatsmcp.com).

> 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](#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](https://whatsmcp.com/plans).

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.

1.  Open **Console → the number → SIP** and choose **Hosted line**.
2.  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.
3.  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` |
| Signalling | **TLS on port 5061**, with **SRTP** media — the recommended setup |
| Fallback | Plain **UDP** for phones that cannot do TLS |
| Media | SRTP (TLS) — the WhatsApp side of every call is always encrypted regardless |

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** where your server offers it.

## 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](#about-this-service) still apply.

## AI voice agent

> **Coming soon — not yet available.** This section describes planned behavior. A plan may already *list* “AI agent calls” as an entitlement, but the runtime that answers a call with an AI voice is still in development; listing it reserves it, it does not switch it on today. For a live agent that talks over the phone now, connect your SIP line to a voice bot on your own PBX.

The AI voice agent will let a WhatsApp caller talk to a conversational AI **without any PBX or SIP device in between**. The planned shape:

-   **Bring your own voice provider** (ElevenLabs first). You add your provider’s agent and a write-only API key on the number’s **Voice agent** card in the console; WhatsMCP holds no vendor key of its own beyond what you supply.
-   **Answer incoming calls** with the agent — a toggle per number.
-   **Place outbound calls** to an agent endpoint, driven from the [MCP server](https://whatsmcp.com/docs/mcp) or [REST API](https://whatsmcp.com/docs/rest), gated by the plan’s outgoing-calls entitlement.

We will document the exact configuration here when it ships. Until then, treat this as a roadmap item, not a feature you can turn on.

## Limits and troubleshooting

| Symptom | Cause / fix |
| --- | --- |
| SIP page is locked | The number has no plan with calls — see [Voice plans](#voice-plans-and-call-direction) |
| 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 |

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.