Configure and Use Session Initiation Protocol (SIP)

This section provides guidance on how to configure and use Session Initiation Protocol (SIP) for VoIP communication. It is only relevant if you plan to use a custom SIP infrastructure.

When SIP is enabled, you cannot use calling-related Graph API endpoints, and calling-related webhooks will not be sent.

Additionally, for debugging purposes, please note that as soon as the user presses the voice call button, Meta immediately attempts to connect with the SIP server defined—leaving no opportunity to intercept or inspect the request beforehand.

Overview

Session Initiation Protocol (SIP) is a signaling protocol used for initiating, maintaining, modifying, and terminating real-time communication sessions between two or more endpoints.

Calling flows using SIP

Before you start, make sure you have enabled and configured SIP on the business phone number.

Meta generates a unique SIP user password for each business phone number + app combination. You will need this information and can retrieve it by using the get Call Settings endpoint.

Security

• TLS transport is mandatory for SIP. Meta will present a valid server cert with subject name that covers our SIP domain wa.meta.vc. Your SIP server should do the same, as Meta ensures your cert is valid and the subject name covers the SIP domain you configured on the business phone number.

• For business-initiated calls, SIP INVITE from your SIP server will be challenged using digest auth.

• For user-initiated calls, it is highly recommended that you challenge SIP INVITE requests from Meta to use digest auth for more security.

See Business-Initiated WhatsApp Calls for more details.

Configure/Update SIP settings

To configure or update the SIP settings on the business's phone number, you can use this endpoint to update call settings configuration for an individual business phone number.

POST https://alpha-beta-onboarding.hub-production.360dialog.io/calling/settings/{phone_number_id}}

{
  "calling": {
    ... // other calling api settings
    "sip": {
      "status": "ENABLED",
      "servers": [
        {
         "hostname": SIP_SERVER_HOSTNAME
          "port": SIP_SERVER_PORT,
          "request_uri_user_params": {
            "KEY1": "VALUE1", // for cases like trunk groups (tgrp)
            "KEY2": "VALUE2",
          }
        }
      ]
    }
  },
  // Other non calling api feature configurations
}

Success Response

{
  "success": true
}

Get phone number calling settings (SIP)

Use this endpoint to check the configuration of your Calling API feature settings, including SIP values:

GET https://alpha-beta-onboarding.hub-production.360dialog.io/calling/settings/{phone_number_id}}

It may also return information related to other Cloud API feature settings.

Response Body

{
  "calling": {
    "status": "ENABLED",
    "call_icon_visibility": "DEFAULT",
    "callback_permission_status": "ENABLED",
    "sip": {
      "status": "ENABLED",
      "servers": [
        {
          "hostname": "sip.example.com",
          "sip_user_password": "{SIP_USER_PASSWORD}"
        }
      ]
    }
  }
}

Include SIP User Password

Optionally, you can include SIP user credentials in your response body by adding the SIP credentials query parameter in the POST request:

GET https://alpha-beta-onboarding.hub-production.360dialog.io/calling/settings/{phone_number_id}?include_sip_credentials=true

Response Body

{
  "calling": {
    "status": "ENABLED",
    "call_icon_visibility": "DEFAULT",
    "callback_permission_status": "ENABLED",
    "sip": {
      "status": "ENABLED",
      "servers": [
        {
          "hostname": "sip.example.com",
          "sip_user_password": "{SIP_USER_PASSWORD}"
        }
      ]
    }
  }
}

For more detailed info, feel free to check Meta Official Documentation.

Troubleshooting SIP Configuration Errors

If your SIP server is not receiving SIP INVITE requests from Meta, a common issue is a mismatch between the hostname you configured and the domain name in your TLS certificate. Meta performs strict validation of the server’s certificate.

To test your certificate setup, run:

openssl s_client -quiet -verify_hostname {hostname} -connect {hostname}:{port}

Replace {hostname} and {port} with the values used in your SIP configuration (typically port 5061).

For other common issues during implementation, refer to Meta's Calling API FAQ, which includes these and additional error scenarios.