> For the complete documentation index, see [llms.txt](https://docs.360dialog.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.360dialog.com/docs/messaging/calling/how-to-configure-calling-api/using-session-initiation-protocol.md).
# Using Session Initiation Protocol
In this documentation, you will learn:
* [How to **configure or update SIP settings** via the API](#configure-update-sip-settings-on-business-phone-number)
* [How to set the **SRTP key exchange protocol** (DTLS or SDES)](#how-to-configure-sdes-for-srtp-key-exchange-protocol)
* [How to **get and fetch current SIP and calling settings** programmatically](#get-phone-number-calling-settings-sip)
* [Common **troubleshooting steps** for SIP configuration errors](#troubleshooting-sip-configuration-errors)
{% hint style="warning" %}
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.
{% endhint %}
## 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.
{% hint style="info" %}
You will need this information and can retrieve it by using the [get Call Settings endpoint.](#fetch-current-call-settings)
{% endhint %}
* [x] TLS transport is mandatory for SIP: Meta will present a valid server cert with subject name that covers our SIP domain `wa.meta.vc`.
* [x] 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.
* [x] For business-initiated calls, SIP INVITE from your SIP server will be challenged using digest auth.
* [x] For user-initiated calls, it is highly recommended that you challenge SIP INVITE requests from Meta to use digest auth for more security.
{% hint style="info" %}
See [Broken mention](broken://pages/ZpD3a6qPIiP8O4FpOWFV) for more details.
{% endhint %}
## Configure/Update SIP settings
{% stepper %}
{% step %}
Update call settings configuration for the phone number, using this [endpoint](/docs/messaging-api/api-reference/calling.md#post-calling-settings):
**Request body**
```json
{
"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
}
```
{% endstep %}
{% step %}
#### You should receive the following response:
```json
{
"success": true
}
```
{% endstep %}
{% endstepper %}
{% hint style="info" %}
If your SIP Server does not support ICE, you must change the type of SRTP key exchange protocol configured for the business phone number.
{% endhint %}
## 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:
Use this [endpoint](/docs/messaging-api/api-reference/calling.md#post-calling-settings).
**Request body:**
```json
{
"calling": {
"status": "ENABLED",
"call_icon_visibility": "DEFAULT"
. . .
"srtp_key_exchange_protocol": "DTLS (default) | SDES",
. . .
}
. . .
}
```
{% hint style="info" %}
SDES can be used only when SIP signaling is enabled. For more information, you can check it [here](https://developers.facebook.com/docs/whatsapp/cloud-api/calling/sip#configure-sdes-for-srtp-key-exchange-protocol).
{% endhint %}
## Get phone number calling settings (SIP)
Use this [endpoint ](/docs/messaging-api/api-reference/calling.md#get-calling-settings)to check the configuration of your Calling API feature settings, including SIP values:
{% hint style="info" %}
It may also return information related to other Cloud API feature settings.
{% endhint %}
**Response Body**
```json
{
"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**
```json
{
"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}"
}
]
}
}
}
```
{% hint style="info" %}
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](https://developers.facebook.com/docs/whatsapp/cloud-api/calling/sip#business-initiated-calls).
{% endhint %}
## 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:
```json
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**).
{% hint style="info" %}
For other common issues during implementation, refer to Meta's [Calling API FAQ](https://developers.facebook.com/docs/whatsapp/cloud-api/calling/faq), which includes these and additional error scenarios.
{% endhint %}
If you have other issues or doubts, please contact our support team:
[Get support](/docs/support/get-support.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.360dialog.com/docs/messaging/calling/how-to-configure-calling-api/using-session-initiation-protocol.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.