Zum Hauptinhalt springen

WhatsApp Business Calling Integration

Vodia PBX supports direct SIP integration with the WhatsApp Business Calling API, allowing WhatsApp users to call your business number and have those calls routed directly into the PBX — to extensions, queues, or IVRs — without any middleware or gateway.

Prerequisites​

  • Vodia PBX Version 70.1+
  • A valid SSL/TLS certificate for your Tenant (subject name must match your Tenant FQDN). If you have Let's Encrypt enabled on your PBX, this is handled automatically.
  • A Meta Business Account with:
    • Business Verification completed
    • A verified WhatsApp Business phone number
    • WhatsApp Business Calling API access enabled

Part 1 — Meta Configuration​

Step 1 — Create a Meta Developer App​

  1. Go to developers.facebook.com
  2. Click My Apps → Create App
  3. During the App creation process, make sure you select the USe case Connect with customers through WhatsApp
  4. Select Business as the app type
  5. Link the app to your Meta Business Account

wa-1 wa-2 wa-3

Step 2 — Business Verification​

Business Verification is required before calling can be enabled.

  1. Go to business.facebook.com → Settings → Security Center -> Business Verification
  2. Under Business Verification, submit your business documents
  3. Verification typically takes 1–3 business days
  4. Once verified, your account status will show Verified

wa-4

Step 3 — Add and Verify Your Phone Number​

  1. Go to the WhatsApp Manager and select Phone Numbers under Account Tools
  2. Click Add phone number
  3. Enter your business phone number — this must not be an active WhatsApp personal or business app number
  4. Request a verification code via SMS or voice call
  5. Enter the code to verify the number
  6. Note your Phone Number ID — you will need this for all API calls

wa-5

Step 4 — Get a Temporary API Token​

For initial setup and testing, a temporary token can be obtained from the dashboard:

  1. Go to Meta App Dashboard → Connect with customers through WhatsApp → Customize → API Setup
  2. Under Temporary access token, click Copy

wa-6

Step 5 — Enable Calling and SIP via API​

Run the following commands, replacing PHONE_NUMBER_ID and TOKEN with your values.

Configure SIP and enable calling:

curl -X POST \
  "https://graph.facebook.com/v25.0/PHONE_NUMBER_ID/settings" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "calling": {
      "status": "ENABLED",
      "callback_permission_status": "ENABLED",
      "sip": {
        "status": "ENABLED",
        "servers": [
          {
            "hostname": "your.vodia.hostname",
            "port": 5061
          }
        ]
      },
      "srtp_key_exchange_protocol": "SDES"
    }
  }'

Retrieve your SIP credentials:

curl -X GET \
  "https://graph.facebook.com/v25.0/PHONE_NUMBER_ID/settings?include_sip_credentials=true" \
  -H "Authorization: Bearer TOKEN"

The response will contain your SIP user password:

{
  "calling": {
    "sip": {
      "status": "ENABLED",
      "servers": [
        {
          "hostname": "your.vodia.hostname",
          "sip_user_password": "YOUR_SIP_PASSWORD"
        }
      ]
    }
  }
}

Note this password — you will enter it into the Vodia trunk configuration in Part 2.

Step 6 — Outbound Call Permissions​

For outbound calls (business calling a WhatsApp user), Meta requires that the user has previously granted call permission to your business.

Recommended: Enable Callback Permission

When callback_permission_status is set to ENABLED (as configured in Step 5), any user who calls your business inbound automatically grants 7-day temporary permission for your business to call them back. This is the recommended approach for call centre and support use cases as it requires no additional steps.

Alternative: Send a Permission Request Message

If callback permission is not enabled, you must explicitly request permission from each user before placing an outbound call. This can be done by sending an interactive permission request message during an active conversation window:

curl -X POST \
  "https://graph.facebook.com/v25.0/PHONE_NUMBER_ID/messages" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "+USER_PHONE_NUMBER",
    "type": "interactive",
    "interactive": {
      "type": "call_permission_request",
      "action": {
        "name": "call_permission_request"
      },
      "body": {
        "text": "We would like to call you on WhatsApp to provide support."
      }
    }
  }'

Permission types:

  • Temporary — valid for 7 days, automatically granted when a user calls your business inbound (requires callback permission to be enabled)
  • Permanent — granted by the user via the business profile or in response to a permission request message

Part 2 — Vodia PBX Configuration​

Step 1 — Create a WhatsApp Trunk​

  1. Log into the Vodia admin portal → Trunks → Add Trunk
  2. Select the WhatsApp trunk template
  3. Configure the following fields:
FieldValue
Trunk NameWhatsApp
UsernameYour WhatsApp business phone number in normalized format, without the + (e.g. 601163370327)
PasswordThe SIP user password retrieved from the Meta API in Step 5

All other settings are pre-configured by the WhatsApp trunk template.

Step 2 — Configure Inbound DID Routing​

  1. Go to the trunk → Number Management
  2. Add your WhatsApp business phone number
  3. Map it to the appropriate inbound destination — auto-attendant, ring group, call queue, or extension

Step 3 — Configure Outbound Dial Plan​

Outbound calls through the WhatsApp trunk should only be used for calling WhatsApp users — not for regular PSTN/Landline/Mobile/GSM calls.

Call Flows​

Inbound (WhatsApp User → PBX)​

WhatsApp user dials business number
        ↓
Meta sends SIP INVITE to Vodia over TLS (port 5061)
        ↓
Vodia identifies the WhatsApp trunk
        ↓
Call routed to configured DID destination
        ↓
Agent answers

Outbound (PBX Agent → WhatsApp User)​

Agent dials WhatsApp user's number
        ↓
Vodia sends SIP INVITE to wa.meta.vc
        ↓
Meta challenges with 407 Proxy Authentication Required
        ↓
Vodia responds with digest credentials
        ↓
Meta verifies the user has granted call permission
        ↓
WhatsApp user's phone rings

References​