Using Session Initiation Protocol

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

In this documentation, you will learn:

• How to configure or update SIP settings via the API

• How to set the SRTP key exchange protocol (DTLS or SDES)

• How to get and fetch current SIP and calling settings programmatically

• Common troubleshooting steps for SIP configuration errors

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.

Before starting

Make sure you have enabled and configured SIP on the business phone number. Please note that 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.

• 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: 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 for more details.

Configure/Update SIP settings

1

Update call settings configuration for the phone number, using the endpoint:

POST https://waba-v2.360dialog.io/calling/settings

--header 'D360-API-KEY: ••••••'

Request body

{
  "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
}

2

You should receive the following response:

{
  "success": true
}

If your SIP Server does not support ICE, you must change the type of SRTP key exchange protocol configured for the business phone number.

How to configure SDES for SRTP key exchange protocol

You can configure SRTP key exchange to one of two options:

• DTLS (default) — Industry-standard encrypted key exchange. Recommended.

• SDES — Plain text key is defined in the SDP which is sent over secure signaling protocol (SIP).

To proceed, use the following request syntax:

POST https://waba-v2.360dialog.io/calling/settings

Request body:

{
  "calling": {
    "status": "ENABLED",
    "call_icon_visibility": "DEFAULT"
  . . .
    "srtp_key_exchange_protocol": "DTLS (default) | SDES",
  . . .
  }
. . .
}

SDES can be used only when SIP signaling is enabled. For more information, you can check it here.

Get phone number calling settings (SIP)

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

GET https://waba-v2.360dialog.io/calling/settings

--header 'D360-API-KEY: ••••••'

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 (Optional)

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

GET https://waba-v2.360dialog.io/calling/settings?include_sip_credentials=true

--header 'D360-API-KEY: ••••••'

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}"
        }
      ]
    }
  }
}

You must include the SIP User Password generated by Meta in your SIP Trunking configuration. 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.

If you have other issues or doubts, please contact our support team:

How to get support