The WhatsApp Cloud API has introduced a powerful new feature that’s set to revolutionise how businesses handle voice communications. With Session Initiation Protocol (SIP) support, developers can now integrate real-time voice calling directly into their WhatsApp Business applications. This comprehensive guide will walk you through everything you need to know about implementing SIP calling in your WhatsApp Cloud API setup.
What is SIP and Why Does it Matter?
Session Initiation Protocol (SIP) is a signalling protocol that’s been the backbone of modern telecommunications for years. It’s responsible for initiating, maintaining, modifying, and terminating real-time communication sessions between two or more endpoints. Think of it as the digital handshake that makes voice calls possible over the internet.
For WhatsApp Business API users, this means you can now handle voice calls using industry-standard SIP infrastructure instead of relying solely on Graph API endpoints. This opens up tremendous possibilities for businesses looking to integrate their existing telephony systems with WhatsApp’s messaging platform.
Important Launch Information
Please note: The SIP calling endpoints will go live on the General Availability launch date, which is targeted for July 15, 2025. Once SIP is enabled on your business phone number, you won’t be able to use the traditional calling-related endpoints, and you’ll stop receiving calling-related webhooks.
Prerequisites: What You’ll Need
Before diving into SIP integration, ensure you have the following sorted:
- SIP Configuration: You must enable and configure SIP on your business phone number through the WhatsApp Cloud API settings
- SIP User Password: Meta generates a unique SIP user password for each business phone number and app combination. You’ll need to retrieve this using the get Call Settings endpoint
- WebRTC Media Support: Your SDP (Session Description Protocol) offer must support ICE, DTLS-SRTP, and OPUS protocols – essentially WebRTC media standards
Setting Up SIP Configuration
Configuring SIP Settings
To enable SIP calling on your business phone number, you’ll need to update the call settings configuration:
Endpoint: POST /<PHONE_NUMBER_ID>/settings
Request Body:
{
"calling": {
"sip": {
"status": "ENABLED",
"servers": [
{
"hostname": "your-sip-server.com",
"port": 5061,
"request_uri_user_params": {
"tgrp": "trunk-group-1",
"context": "business-context"
}
}
]
}
}
}
Key Parameters:
- status: Set to “ENABLED” to activate SIP calling or “DISABLED” to turn it off
- servers: Array containing your SIP server configuration (only one server per application)
- hostname: Your SIP server’s hostname (must use TLS)
- port: The port for SIP requests (default is 5061, must use TLS)
- request_uri_user_params: Optional parameters for the request URI (useful for trunk groups)
Retrieving SIP Settings
To check your current SIP configuration:
Endpoint: POST /<PHONE_NUMBER_ID>/settings
For detailed information including SIP credentials:
Endpoint: POST /<PHONE_NUMBER_ID>/settings?include_sip_credentials=true
Response Example:
{
"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}"
}
]
}
}
}
Authentication: How SIP Digest Auth Works
WhatsApp’s SIP server implementation uses digest authentication for user-initiated calls. Here’s how the authentication flow works:
- Initial INVITE: Your SIP server sends an initial INVITE request
- 407 Challenge: Meta responds with a 407 Proxy Authentication Required
- Authenticated INVITE: Your server resends the INVITE with proper authentication
- Success: Meta processes the authenticated request
The username for digest auth is your normalised business phone number, and the password is generated by Meta (retrievable via the GET /settings API).
SRTP Key Exchange: Securing Your Calls
Security is paramount in voice communications. WhatsApp Cloud API supports two SRTP (Secure Real-time Transport Protocol) key exchange options:
DTLS (Default)
Datagram Transport Layer Security is the default and recommended option for most implementations.
SDES (SIP-Specific)
Session Description Protocol Security can only be used when SIP signalling is enabled.
Configuration:
{
"calling": {
"status": "ENABLED",
"srtp_key_exchange_protocol": "DTLS"
}
}
Important Note: Regardless of the key exchange protocol, Meta expects the business side to send the first SRTP packet for both user-initiated and business-initiated calls.
Common SIP Call Flows
User-Initiated Calls
- Initial SIP INVITE from your server
- 407 authentication challenge from Meta
- Second SIP INVITE with proper authentication
- Call establishment and media exchange
- SIP BYE to terminate the call
Business-Initiated Calls
- SIP INVITE from Meta to your server
- SIP OK response from your server
- Media exchange
- SIP BYE to terminate
Best Practices and Tips
Server Configuration
- Always use TLS for SIP communication
- Configure your SIP server to handle digest authentication properly
- Ensure your server supports the required media protocols (ICE, DTLS-SRTP, OPUS)
Error Handling
- Implement proper error handling for authentication failures
- Monitor for 407 responses and handle re-authentication gracefully
- Keep track of call states and handle unexpected disconnections
Security Considerations
- Store SIP user passwords securely
- Implement proper access controls for your SIP server
- Regularly rotate credentials when possible
- Monitor for suspicious call patterns
Troubleshooting Common Issues
Authentication Problems
- Verify your SIP user password is current
- Check that your phone number is properly normalised
- Ensure your server responds correctly to 407 challenges
Connection Issues
- Confirm TLS is properly configured
- Verify your SIP server hostname and port settings
- Check firewall settings for SIP traffic
Media Problems
- Ensure WebRTC media support is properly implemented
- Verify SRTP key exchange is working correctly
- Check codec compatibility (OPUS support required)
Integration Examples
Basic SIP Server Setup
When setting up your SIP server for WhatsApp integration, ensure it can:
- Handle TLS connections on the configured port
- Process digest authentication challenges
- Support the required media protocols
- Manage call routing based on your business logic
Trunk Group Configuration
For businesses with complex telephony setups, you can use the request_uri_user_params field to include trunk group information:
{
"request_uri_user_params": {
"tgrp": "sales-team",
"context": "customer-support"
}
}
What’s Next?
SIP calling integration with WhatsApp Cloud API represents a significant step forward in business communication capabilities. As this feature moves towards general availability, consider how it might enhance your existing communication workflows.
Whether you’re building a customer support system, developing a sales platform, or creating a comprehensive business communication solution, SIP calling can provide the voice component that makes your WhatsApp integration truly comprehensive.
Remember to test your implementation thoroughly before the July 15, 2025 launch date, and keep an eye on WhatsApp’s developer documentation for any updates or changes to the SIP calling feature.
The future of business communication is here, and with SIP calling support, WhatsApp Cloud API is positioning itself as a complete communication platform for modern businesses.
This guide is based on the official WhatsApp Cloud API documentation as of July 2025. Always refer to the latest official documentation for the most current implementation details.
