WhatsApp SIP to VICIdial: an Implementation Pattern and Verification Plan

A WhatsApp SIP connection looks like another carrier until the first real call exposes the differences. The business server's public certificate decides whether Meta delivers an inbound INVITE. Digest authentication and a maintained source ACL decide whether Asterisk should trust it. Number normalization decides whether VICIdial finds the DID. ACK routing and SRTP decide whether a connected call stays connected.

This guide works through those boundaries in order. It is written for VICIdial administrators and telephony engineers with shell access to Asterisk and administrator access to VICIdial. It is not a beginner SIP tutorial.

Choose the call direction before configuring anything

Architecture and trust boundaries

There are two boundaries. Meta knows SIP and WhatsApp identity; it does not know the generated contexts, DIDs, campaigns, queues, or reports inside VICIdial. Asterisk must bridge those worlds without turning a public TLS listener into an open trust boundary.

Prerequisites and compatibility checks

• A WhatsApp Business phone number on Cloud API, with Calling and SIP enabled through an app in Live mode, the required messaging permission, and a healthy can_receive_call_sip status.
• An explicit signaling choice: while SIP is enabled, calling-related Graph API endpoints do not work and calling webhooks are off unless SIP webhook delivery is enabled.[1]
• The Meta-generated SIP password stored outside Git, tickets, screenshots, browser code, and public logs.
• A public DNS name and trusted certificate whose subject covers that exact SIP hostname. Meta does not support mTLS for this boundary.[1]
• Asterisk PJSIP with TLS, Opus, and the chosen SRTP mode available. This guide uses SDES; Meta defaults to DTLS, so both sides must agree.[1]
• A maintained Meta SIP network ACL, firewall access to TLS 5061, and the local RTP range.
• An existing working VICIdial inbound route to inspect rather than a guessed context name.
• A maintenance window, rollback copy, and a test path isolated from live campaigns.

Verify the certificate before debugging dialplan logic:

openssl s_client -quiet \
  -verify_hostname voice.example.com \
  -connect voice.example.com:5061

Build the Meta-facing PJSIP endpoint

The following is an illustrative, self-contained adaptation of Meta's Asterisk example. It makes inherited endpoint behavior visible and separates inbound authentication from outbound authentication. Confirm every option against the Asterisk version actually installed.[2]

[transport-whatsapp-tls]
type=transport
protocol=tls
bind=0.0.0.0:5061
cert_file=<PUBLIC_CERTIFICATE_CHAIN>
priv_key_file=<PRIVATE_KEY>
ca_list_file=<TRUSTED_CA_BUNDLE>
verify_server=yes
allow_wildcard_certs=yes
external_media_address=<PUBLIC_IP>
external_signaling_address=<PUBLIC_IP>
local_net=<PRIVATE_CIDR>

[sdes_endpointtemplate](!)
type=endpoint
transport=transport-whatsapp-tls
context=from-whatsapp
acl=meta_whatsapp_sip
disallow=all
allow=opus,ulaw,alaw
direct_media=no
rtp_symmetric=yes
force_rport=yes
rewrite_contact=no
media_use_received_transport=yes
media_encryption=sdes

[whatsapp](sdes_endpointtemplate)
auth=whatsapp-inbound-auth
aors=whatsapp
from_user=<BUSINESS_NUMBER_WITHOUT_PLUS>
from_domain=voice.example.com
outbound_auth=whatsapp-outbound-auth

[whatsapp]
type=aor
contact=sip:wa.meta.vc;transport=tls

[whatsapp-identify]
type=identify
endpoint=whatsapp
match_header=X-FB-External-Domain: wa.meta.vc

[whatsapp-inbound-auth]
type=auth
; userpass is broadly compatible with older deployments; current Asterisk may
; internally convert it to digest. Verify the supported auth_type locally.
auth_type=userpass
username=<BUSINESS_NUMBER_WITHOUT_PLUS>
password=<META_SIP_PASSWORD>

[whatsapp-outbound-auth]
type=auth
auth_type=digest
username=<BUSINESS_NUMBER_WITHOUT_PLUS>
password=<META_SIP_PASSWORD>
realm=*

rewrite_contact=no matters because Meta documents a failure where modified Record-Route headers prevent ACK or BYE from following the dialog. The call can answer and carry audio, then fail around 32 seconds.[2]

Route calls through VICIdial

Inbound: Meta to an existing VICIdial DID

First inspect a working inbound carrier and the generated dialplan. Do not paste a plausible context name from an article.

asterisk -rx 'dialplan show' | less
asterisk -rx 'dialplan show <EXISTING_VICIDIAL_INBOUND_CONTEXT>'

Then keep the custom boundary narrow:

[from-whatsapp]
exten => _+<BUSINESS_NUMBER_WITHOUT_PLUS>,1,NoOp(Inbound WhatsApp call)
 same => n,Goto(<EXISTING_VICIDIAL_INBOUND_CONTEXT>,<VICIDIAL_DID>,1)
 same => n,Hangup()

The DID format must exactly match the value configured in VICIdial. Normalize once at this boundary. Confirm the route preserves VICIdial call logging, queue delivery, disposition, and recording behavior.

Outbound: a dedicated, permission-gated carrier path

Meta's route does not use conventional SIP REGISTER. Asterisk sends the destination to wa.meta.vc and answers Meta's digest challenge.[1] Therefore, pjsip show registrations is not a health test for this route.

[from-vicidial-whatsapp]
exten => _+X.,1,NoOp(Permission-gated outbound WhatsApp call)
 same => n,Dial(PJSIP/whatsapp/sip:${EXTEN}@wa.meta.vc;transport=tls)
 same => n,Hangup()

Use a dedicated local carrier prefix only after checking the existing dialplan for collisions. The actual VICIdial carrier string and campaign assignment are local design decisions. Do not connect this route to a campaign unless the application queries Meta's current permission immediately before dialing, requires start_call.can_perform_action, and matches the returned WhatsApp identity to the normalized destination.

Change a running server safely

A reload is a mutation, not a validation command. Before touching a running dialer:

1. Back up the active PJSIP, dialplan, ACL, certificate references, and VICIdial carrier definition.
2. Check whether port 5061 is already bound and whether the target include is generated.
3. Confirm the required modules and codecs with module show like pjsip, module show like srtp, and core show codecs.
4. Inspect active calls and drain or isolate the change during a maintenance window.
5. Load the smallest possible include change. A transport may require a controlled restart because transport reload support varies.[4]
6. Verify the endpoint, ACL, context, TLS listener, and existing non-WhatsApp routes immediately.
7. Rollback if existing carriers fail, the endpoint cannot load, authentication loops, media is absent, or the test call cannot clear cleanly.

asterisk -rx 'pjsip show transports'
asterisk -rx 'pjsip show endpoint whatsapp'
asterisk -rx 'dialplan show from-whatsapp'
asterisk -rx 'core show channels concise'

Failure signatures that reveal the broken boundary

How to verify the integration

A loaded endpoint is not proof. Treat each row below as an acceptance gate.

What remains environment-specific

• Asterisk and VICIdial versions, loaded modules, and generated include ownership
• certificate, CA bundle, network ACL, NAT, and RTP range
• actual VICIdial inbound context, DID, inbound group, carrier prefix, and campaign mapping
• permission storage, normalized WhatsApp identity matching, operating hours, and call caps
• recording notice, retention, access, opt-out, and local legal requirements
• maintenance, monitoring, rollback, and incident ownership

Those values are the implementation. Replacing them with plausible examples would make this article easier to copy and less safe to use.

FAQ

Sources

1. Meta, SIP Configuration Guide for WhatsApp Business Calling Updated 26 Jun 2026.
2. Meta, Asterisk using SIP integration example Updated 21 May 2026.
3. Meta, Cloud API Calling Updated 26 Jun 2026.
4. Asterisk, PJSIP configuration sections and relationships
5. Meta, obtain and check user call permissions