Call Permissions

Obtain permission to call WhatsApp users: temporary (7-day) and permanent permissions, three ways to obtain (free-form request, template request, callback auto-prompt, business profile), get permission state endpoint, permission reply webhook.

Overview

Before your business can place a business-initiated call to a WhatsApp user, the user must normally grant call permission. The exception is quality-based calling: eligible Colombia and Mexico numbers can call without prior approval unless the user declined permanent permission or revoked one they granted. That model uses only permanent permission, not temporary or callback permission, and existing permissions stay valid. The user is in full control — they can accept (temporary or permanent), decline, or ignore. They can revoke a granted permission at any time. Your business cannot revoke or modify a granted permission.

As of November 3, 2025, permanent permissions are available — users can grant ongoing permission to call. Permanent permission data is stored until the user revokes it. All call permission features, temporary and permanent, are only available in regions where business-initiated calling is available.

Dualhook Boundary

Dualhook documents call permissions but does not offer calling. The dashboard has no permission view or request builder, and the Runtime API has no /call_permissions route and rejects the call_permission_request template component, so create permission-request templates in Meta Business Suite or WhatsApp Manager, and read permission state with your own Meta app. The Runtime API /messages route forwards free-form call_permission_request messages and template sends to Meta unchanged, but placing the call afterwards needs /calls, which it does not have.

The Calling API is not available on Coexistence numbers, which most Dualhook connections are. Permission replies arrive on the messages webhook field, which Dualhook never reads; with Webhook Override active, Meta routes them to your endpoint.

Temporary vs Permanent

TemporaryPermanent
Duration7 calendar days (168 hours) from approvalNo expiration
Connected calls cap100 / 24h per business + user pair100 / 24h per business + user pair
Auto-revocation on unansweredYes (after 4 consecutive unanswered)Yes (after 4 consecutive unanswered)
User revocable any timeYesYes

Both kinds share the same per-day connected-call limit. The difference is just the expiration window.

Three Ways to Obtain Permission

MethodWhen to use
1. Send a call permission request messageProactively, when you want to call a user out of the blue (within an open CSW: free-form, otherwise: template)
2. Enable callback_permission_statusAutomatically prompt for permission when a user calls you (whether you answer or miss)
3. User grants permanent permission via business profileUser-driven — they navigate to your business profile and toggle on calling permission

Request Limits

Per business + WhatsApp user pair (these are designed to protect users from spam):

LimitProductionSandbox / Test
Permission requests per day125
Permission requests per 7 days2100

Limits reset when any connected call (BIC or UIC) happens between you and that user. They apply to both free-form and template permission requests combined.

Sending these messages also costs you — call permission request messages are subject to standard messaging charges.

Free-Form Call Permission Request

Use during an open CSW. Header and footer are not supported on free-form variants.

POST /<PHONE_NUMBER_ID>/messages
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "12015550123",
  "type": "interactive",
  "interactive": {
    "type": "call_permission_request",
    "action": { "name": "call_permission_request" },
    "body": {
      "text": "We would like to call you to help support your query on Order No: ON-12853."
    }
  }
}

body is technically optional but strongly recommended — without context, users decline. The call_permission_request interactive object itself cannot be customized; only the body text is yours.

to is required unless you send recipient with the user's BSUID or parent BSUID; if you send both, to takes precedence. The same applies to the template send below. The success response's contacts[] includes user_id (and parent_user_id when enabled).

Sending a request triggers the standard message status webhook. Sending to users on older app versions triggers an error webhook with code 131026. Calling must be enabled on the number, and calling restrictions also block requests.

Template Call Permission Request

Use outside an open CSW (or whenever you'd prefer a templated approach). Templates support header, body, and footer. Body is required.

Create the template:

POST /<WABA_ID>/message_templates
{
  "name": "sample_cpr_template",
  "language": "en",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "text": "Support of Order No: {{1}}",
      "example": { "body_text": [["ON-12345"]] }
    },
    {
      "type": "BODY",
      "text": "We would like to call you to help support your query on Order No: {{1}} for the item {{2}}.",
      "example": { "body_text": [["ON-12345", "Avocados"]] }
    },
    { "type": "FOOTER", "text": "Talk to you soon!" },
    { "type": "call_permission_request" }
  ]
}

Category must be MARKETING or UTILITY. The call_permission_request component cannot be combined with other interactive components.

Send the template:

POST /<PHONE_NUMBER_ID>/messages
{
  "messaging_product": "whatsapp",
  "to": "12015550123",
  "type": "template",
  "template": {
    "name": "sample_cpr_template",
    "language": { "code": "en" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "John Smith" },
          { "type": "text", "text": "order #1522" }
        ]
      }
    ]
  }
}

Template-based call permission requests are also covered as a category-specialty template in Marketing Messages and Utility Messages.

Callback Permission (User Calls You)

When callback_permission_status: ENABLED on the phone number's call settings, the WhatsApp client automatically prompts the user with a call permission request after they call you (whether you picked up or missed it). The resulting permission is temporary. It flows back via the permission reply webhook with response_source: automatic.

This is the lowest-friction way to obtain permission for businesses that primarily receive calls and want to follow up.

Permanent Permission from Business Profile

Users can grant permanent calling permission to a business at any time through the business's WhatsApp profile. This is user-driven — there's no API to nudge them toward this UI.

When granted this way, you receive a permission reply webhook with no context.id (since it wasn't in response to a request) and is_permanent: true.

Get Call Permission State

GET /<PHONE_NUMBER_ID>/call_permissions?user_wa_id=<USER_WHATSAPP_ID>
GET /<PHONE_NUMBER_ID>/call_permissions?recipient=<BSUID>

Use recipient (a BSUID or parent BSUID) instead of user_wa_id to identify the user without a phone number.

Returns the current permission state plus the rate-limit budget for sending another permission request and placing a new call to that user.

{
  "messaging_product": "whatsapp",
  "permission": {
    "status": "temporary",
    "expiration_time": 1745343479
  },
  "actions": [
    {
      "action_name": "send_call_permission_request",
      "can_perform_action": true,
      "limits": [
        { "time_period": "PT24H", "max_allowed": 1, "current_usage": 0 },
        { "time_period": "P7D",   "max_allowed": 2, "current_usage": 1 }
      ]
    },
    {
      "action_name": "start_call",
      "can_perform_action": false,
      "limits": [
        {
          "time_period": "PT24H",
          "max_allowed": 5,
          "current_usage": 5,
          "limit_expiration_time": 1745622600
        }
      ]
    }
  ]
}
FieldNotes
permission.statusno_permission, temporary, or permanent
permission.expiration_timeUnix timestamp when temporary permission expires. Absent when permanent.
actions[].action_namesend_call_permission_request (sending another request) or start_call (a new call the user picks up; connected calls count, not attempts)
actions[].can_perform_actionWhether the action is currently allowed by all applicable limits
limits[].time_periodISO 8601 duration: PT24H = 24 hours, P7D = 7 days
limits[].limit_expiration_timeUnix timestamp when the limit resets. Only present if current_usage has hit max_allowed.

Rate limit on this endpoint itself: 100 requests per second. If the user phone number is uncallable for any reason (not on WhatsApp, etc.), the response returns no_permission.

User Call Permission Reply Webhook

Fires whenever the user accepts, rejects, or has their permission auto-revoked. Includes whether the response was permanent and the source.

{
  "messages": [
    {
      "from": "12015550123",
      "from_user_id": "<BSUID>",
      "from_parent_user_id": "<PARENT_BSUID>",
      "id": "wamid.sH0kFlaCGg0xcvZbgmg90lHrg2dL",
      "timestamp": "1767168000",
      "context": {
        "from": "12015550123",
        "id": "wamid.gBGGFlaCmZ9plHrf2Mh-o"
      },
      "interactive": {
        "type": "call_permission_reply",
        "call_permission_reply": {
          "response": "accept",
          "is_permanent": false,
          "expiration_timestamp": "1768550400",
          "response_source": "user_action"
        }
      }
    }
  ]
}
FieldValuesNotes
responseaccept or reject
is_permanenttrue or falseAlways false for temporary; true for permanent. Absent on rejects.
expiration_timestampUnix timestampPresent only for accepts of temporary permissions
response_sourceuser_action or automaticautomatic = callback permission auto-granted on user-initiated call, or auto-revoked after consecutive unanswered calls
context.idwamid. of permission request, or wacid. of missed call, or absentTells you what triggered the response. Absent when user grants from business profile.

from may be omitted when the user has adopted a username; from_user_id carries the BSUID, and from_parent_user_id appears only if parent BSUIDs are enabled.

No webhook fires when a temporary permission expires naturally — use the expiration_timestamp you received on the accept webhook, or query the permission state endpoint.

Common scenarios:

Scenarioresponseis_permanentresponse_sourcecontext.id
User accepts temporary from request messageacceptfalseuser_actionwamid. of request
User accepts permanent from request messageaccepttrueuser_actionwamid. of request
User accepts permanent from business profileaccepttrueuser_actionabsent
User rejects from request messagerejectabsentuser_actionwamid. of request
Auto-permission via callback (user called you)acceptfalseautomaticwacid. of missed call
Auto-revoked after 4 unanswered BICrejectabsentautomaticabsent

Automatic Revocation (Unanswered Calls)

Consecutive unanswered BIC callsEffect
2System message in WhatsApp asks the user to reconsider their permission
4Permission auto-revoked. You receive a permission reply webhook with response: reject, response_source: automatic

After auto-revoke, you can call again only once the user grants permission again, through a new request or your business profile. Sandbox accounts have relaxed thresholds (5 / 10 instead of 2 / 4).

Permission Request Expiration

A call permission request expires when any of these happen:

  • The user interacts with a subsequent new permission request from you (the prior one auto-expires).
  • 7 days after the user accepts or declines it.
  • 7 days after delivery if the user never responds.

Until the request expires, a user who declined can still change their mind and grant permission from it. Sending more than the request limits allow fails with 138009.

Related

  • Business-Initiated CallsPlace outbound voice calls to WhatsApp users. POST /calls with action: connect, SDP offer/answer flow, call status webhooks (RINGING/ACCEPTED/REJECTED), terminate webhook with duration, biz_opaque_callback_data tracking.
  • Marketing MessagesMarketing template messaging through Dualhook's standard Cloud API runtime, plus boundaries for Meta's separate MM API product.
  • Utility MessagesUtility template messaging hub: components and buttons, specialty types, the October 2026 CSW billing change, volume tiers, content rules, and recategorization.
  • Calling TroubleshootingWhatsApp Calling errors and fixes: full error code table (138000-138023), SIP-specific status codes, media-flow timeouts, audio clipping causes and mitigations (SDES, pre-accept), quick triage guide.
Browse more docsStart Free Trial