Troubleshoot WhatsApp Calling Errors - Reference Guide

{
  "error": {
    "message": "<Error Message>",
    "type": "<Exception Type>",
    "code": <Exception Code>,
    "fbtrace_id": "<Trace ID>"
  }
}

1. Navigate to WhatsApp Manager > Account tools > Phone numbers⁠
2. Select the desired phone number to view the call logs

(Right click image and choose “Open in new tab” for enlarged image)

• WAConsumer is a WhatsApp user calling the business phone number using WhatsApp mobile app
• Meta is the Cloud API product
• MetaWebrtcEndpoint is the WebRTC agent on the Meta infrastructure
• BizIntegration is the webhook server receiving calls related webhooks and the app server with business logic to invoke Cloud API Graph APIs
• BizWebrtcEndpoint is the WebRTC termination point as well as the SIP UAC typically in a media server on your side.
• BizSipEndpoint is the SIP User Agent (UA) often representing IVR or Business Agent.

1. Upon receiving the connect webhook (step 5 above), initialize your WebRTC agent, prepare the SDP answer, and make the Pre-accept Graph API call with the SDP answer. This pre-establishes the WebRTC connection in anticipation of an ‘accept/ok’ response from the SIP User Agent (UA). In most cases, the consumer’s call is answered, such as by an automated recording or IVR system.
2. At step 11 above, wait for the ICE process to complete the creation of valid lists, indicating the near completion of ICE connection establishment (RFC reference).
3. If the SIP UA rejects the call instead of returning a 200 OK, use the terminate Graph API to end the call.
4. If the consumer connection is ready before the SIP connection, the consumer may experience a few milliseconds of silence, which is preferable to losing some initial audio from the business.

• Use SDES: Configure SDES on your business number instead of DTLS. A common reason for delayed setup of the media leg between your infrastructure and Meta is DTLS handshake completion. Meta cannot complete DTLS handshake until it receives your SDP. You may not be able share your SDP with Meta until your internal endpoint responds to your with their SDP. Common DTLS implementations have a retry interval of 1s, 2s, 4s, and so on. After you send Meta the SDP, there is often a ~3 second delay before we receive your DTLS client hello packet and this is when your internal endpoint is sending media but it is dropped. When you switch to SDES you can directly send SRTP after you send us your SDP.
• Delayed Audio Playback: Instruct the SIP User Agent (UA) to wait for an ACK from BizWebrtcEndpoint before playing audio. The ACK would be sent only after receiving a successful response from the Accept API, followed by an artificial delay. This approach ensures that the WebRTC connection is established before audio playback begins.
• Connection State-Based Delay: Direct the SIP UA to wait until the WebRTC connection state is ‘connected’ before playing audio. This method relies on the WebRTC connection being fully established before audio playback starts.
• Buffered Media Packets: Buffer SIP media packets and send them only after the WebRTC connection is established. This approach ensures that no audio packets are lost due to premature playback.
• Silence Insertion: Insert a brief period of silence into the IVR audio before the actual audio content. This method allows the WebRTC connection to establish itself while the IVR is playing silence, reducing the likelihood of audio clipping.
• Pre-accept: According to the RFC recommendation⁠, a WebRTC agent, such as BizWebrtcEndpoint, should not transmit media until the ICE process is nearly complete. In our context, this means adopting an ‘optimistic accept’ strategy by invoking the pre-accept API call even before sending the SIP INVITE. According to SIP RFCs, a User Agent Client (UAC) should be prepared to receive media immediately after sending the INVITE. Therefore, it’s advisable to initiate the WebRTC connection setup process prior to sending the SIP INVITE.