Skip to main content

Check permission before dialing

Complete Calling setup and connect a working media server first. Working inbound calls don’t mean you can call out: outbound also depends on the recipient’s permission and country availability. Pass the recipient’s number with country code, digits only (no + or separators):
If you only have a business-scoped user ID from the webhook, use recipient=BSUID instead of user_wa_id here, and recipient instead of to when sending the permission request or dialing. Check the start_call action, not just permission.status:
If it’s false, don’t dial. Request permission, then check again. Meta’s limits can block a call even while permission is granted; see Meta’s permission docs for current flows and limits.
The TypeScript SDK uses camelCase fields: actionName and canPerformAction. The REST response uses snake_case. See SDK calls.

Request permission in WhatsApp

Inside an open customer service window, check that send_call_permission_request has can_perform_action: true, then send a free-form request:
Replies arrive on the messages field as interactive.call_permission_reply, so handle them on the same Meta webhook as your calls. Match them by from and/or from_user_id; the phone number can be missing. The message being delivered or read doesn’t grant permission: wait for the recipient to approve, then check start_call again. Outside the window, use a template permission request. Create the template through /meta/whatsapp/{version}/{waba_id}/message_templates with a BODY explaining why you want to call and a call_permission_request component. Once Meta approves it, send it through the number’s /messages endpoint. A regular quick-reply button doesn’t grant Calling permission.

Send a real SDP offer

Create a WebRTC peer connection that sends and receives audio, set its local SDP offer with the ICE candidates your deployment needs, and keep the connection alive while the call rings. Here offerSdp comes from your media server, and recipientPhoneNumber is the number you just checked:
To record or transcribe the call, add recording and/or transcription to this connect body. See Recordings and transcripts. Map the returned call ID to your pending media session. A successful connect response only means the request was accepted, not that the recipient answered or that audio flows. Don’t auto-retry after a timeout or unclear response: the first request may already have created a billed call.

Apply the answer webhook

Use the same signed Meta receiver as for inbound calls. Route by direction and SDP type: The SDP answer can arrive while the phone is still ringing. Apply it to the pending connection right away, but don’t greet until the matching ACCEPTED status.
  • Don’t treat an outbound answer as a new inbound offer.
  • If an answer or status arrives before the dial response returns the call ID, buffer it briefly by call ID and apply it once the session is mapped.
  • Set a timeout to clean up unanswered calls, and clear it on ACCEPTED so it can’t cut off an answered call.
  • Ignore duplicate or late events after termination.

Test outbound calls

Use a consenting test recipient and check these cases separately:
  1. Revoke permission in WhatsApp. Confirm your app refuses to dial when start_call is unavailable.
  2. Send a permission request, approve it on the handset, and check start_call again.
  3. Answer a call. Verify two-way audio, the intended tool, and caller hangup.
  4. Answer another call and let the agent end it. Verify your bridge sends terminate and releases the pipeline and media connection.
  5. Decline a call, then leave another unanswered. Neither should start an agent; both must release the pending media connection.
  6. Read each saved call through List calls and match it to the webhook sequence by call ID.
COMPLETED alone doesn’t mean the call was answered. In handset tests, Meta also sent it for declined and unanswered calls, without start/end times or duration. Track RINGING, ACCEPTED, and REJECTED to tell those outcomes apart.

Billing and troubleshooting

Meta charges business-initiated calls by destination country and monthly volume, in 6-second pulses. See Calling pricing. Permission, country availability, and Kapso billing are checked separately. Having permission doesn’t get past an insufficient-balance or billing-readiness error from the proxy. A billing error comes from the dial request, not your webhook, so don’t remove the webhook to debug one. See Call actions, Call permission state, and Meta business-initiated calls.