Obtain User Call Permissions

1. Send a call permission request to the user — Send a free-form or templated message requesting calling permission from the user. User has the option to choose between temporary or permanent.
2. Callback permission is provided by the WhatsApp user — The WhatsApp user automatically provides temporary call permissions by placing a call to the business. The callback setting must be enabled on the business phone number.
3. WhatsApp user provides call permission via Business Profile — The WhatsApp user provides call permissions to the business through their business profile.

• Temporary permissions are granted for 7 calendar days (168 hours)
  • Calculated as the number of seconds in a day multiplied by 7, from time of user’s approval.
• Permanent permissions do not expire, but they have the same connected calls limit.
• Your business can make a maximum of 100 connected calls every 24 hours
• These limits are on the business phone number

• Free form interactive message
• Template message

• The WhatsApp user interacts with a subsequent new call permission request from the business
• 7 days after the permission was accepted or declined by the consumer
• 7 days after the permission was delivered if the consumer does not respond to the request

1. When sending a calling permission request message
   • Maximum of 1 permission request in 24h
   • Maximum 2 permission requests within 7 days.
   • These limits reset when any connected call (business-initiated/user-initiated) is made between the business and WhatsApp user.
   • These limits apply toward permissions requests sent either as free form or template messages.
2. When business-initiated calls go unanswered or are rejected
   • 2 consecutive unanswered calls result in a system message to reconsider an approved permission
   • 4 consecutive unanswered calls result in an approved permission being automatically revoked. The user may again update this if they so choose.

• When you are within a customer service window with a WhatsApp user, you can send a free form message with a call permission request.
• Although a text body will be optional, you should send one to build context with the user. In the case of free form calling permission request messages, header and footer sections are not supported.
• Since the customer service window is open, there is no need to create a conversation window.

• Sending a template message allows you to initiate a user conversation with a call permission request.
• Context (that is, a text body) is required when sending a template message with a call permission request.
• With template messages, you can further customize your permission request by adding a message header and footer.

With header, footer and body

With body only

With no text body

With no text body

With text body only

Update call permission on business profile

Consecutive unanswered calls
2 consecutive unanswered calls — System message for user to update permission
4 consecutive unanswered calls — Permissions automatically revoked

Permission request expires after 7 days — User interacts with request

Permission request expires after 7 days — User does not interact

Previous permission request expires immediately — User does not interact / New call permission request is received

Previous permission request expires immediately — User allows / Interacts with the new request

POST <PHONE_NUMBER_ID>/messages

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<PHONE_NUMBER_ID> or <WHATSAPP_ID>",
  "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."
    }
  }
}

{
  "messaging_product": "whatsapp",
  "contacts": [{
      "input": "+1-408-555-1234",
      "wa_id": "14085551234"
    }],
  "messages": [{
      "id": "wamid.gBGGFlaCmZ9plHrf2Mh-o"
    }]
}

• Invalid phone-number-id
• Permissions/Authorization errors
• Rate limit reached
• Sending this message to users on older app versions will result in error webhook with error code 131026
• Calling not enabled
• Calling restriction errors

POST/<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates

{
  "name": "sample_cpr_template",
  "language": "en",
  "category": "[MARKETING|UTILITY]",
  "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"
    }
  ]
}

{
  "id": "<ID>",
  "status": "<STATUS>",
  "category": "<CATEGORY>"
}

• Invalid WABA id
• Permissions/Authorization errors
• Template structure/component validation alerts

POST/<PHONE_NUMBER_ID>/messages

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+13287759822", // The WhatsApp user who will receive the template message
  "type": "template",
  "template": {
    "name": "sample_cpr_template", // The call permission request template name
    "language": {
      "code": "en"
    },
    "components": [ // Body text parameters such as customer name and order number
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "John Smith"
          },
          {
            "type": "text",
            "text": "order #1522"
          }
        ]
      }
    ]
  }
}

GET /<PHONE_NUMBER_ID>/call_permissions?user_wa_id=<CONSUMER_WHATSAPP_ID>

{
  "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,
        }
      ]
    }
  ]
}

• Invalid phone-number-id
• If the consumer phone number is uncallable, the api response will be no_permission.
• Permissions/Authorization errors.
• Rate limit reached. A maximum of 100 requests in a 1 second window can be made to the API.
• Calling is not enabled for the business phone number.

• the user accepts or rejects the request
• the user approves permission by responding to a request or by calling the business
• the user permission is an automatic callback permission in response to a user-initiated call
• the user permission is automatically revoked in response to 4 consecutive unanswered business-initiated calls

{
. . .

"messages": [{
    "from": "{customer_phone_number}",
    "id": "wamid.sH0kFlaCGg0xcvZbgmg90lHrg2dL",
    "timestamp": "{timestamp}",
    "context": {
          "from": "{customer_phone_number}",
          "id": "wamid.gBGGFlaCmZ9plHrf2Mh-o"
    },
    "interactive": {
       "type":  "call_permission_reply",
        "call_permission_reply": {
            "response":"accept",
            "is_permanent":false,
            "expiration_timestamp": "{timestamp}",
            "response_source": "user_action"
       }
    }
 ],
. . .
}

{
. . .

"messages": [{
    "from": "{customer_phone_number}",
    "id": "wamid.sH0kFlaCGg0xcvZbgmg90lHrg2dL",
    "timestamp": "1767168000",
    "context": {
          "from": "{customer_phone_number}",
          "id": "wamid.gBGGFlaCmZ9plHrf2Mh-o"
    },
    "interactive": {
       "type":  "call_permission_reply",
        "call_permission_reply": {
            "response":"accept",
            "is_permanent":false,
            "expiration_timestamp": "1768550400",
            "response_source": "user_action"
       }
    }
 ],
. . .
}

{
. . .

"messages": [{
    "from": "{customer_phone_number}",
    "id": "wamid.sH0kFlaCGg0xcvZbgmg90lHrg2dL",
    "timestamp": "1767168000",
    "context": {
          "from": "{customer_phone_number}",
          "id": "wamid.gBGGFlaCmZ9plHrf2Mh-o"
    },
    "interactive": {
       "type":  "call_permission_reply",
        "call_permission_reply": {
            "response":"accept",
            "is_permanent":true,
            "response_source": "user_action"
       }
    }
 ],
. . .
}

{
. . .

"messages": [{
    "from": "{customer_phone_number}",
    "id": "wamid.sH0kFlaCGg0xcvZbgmg90lHrg2dL",
    "timestamp": "1767168000",
    "interactive": {
       "type":  "call_permission_reply",
        "call_permission_reply": {
            "response":"accept",
            "is_permanent":true,
            "response_source": "user_action"
       }
    }
 ],
. . .
}

{
. . .

"messages": [{
    "from": "{customer_phone_number}",
    "id": "wamid.sH0kFlaCGg0xcvZbgmg90lHrg2dL",
    "timestamp": "1767168000",
    "context": {
          "from": "{customer_phone_number}",
          "id": "wamid.gBGGFlaCmZ9plHrf2Mh-o"
    },
    "interactive": {
       "type":  "call_permission_reply",
        "call_permission_reply": {
            "response":"reject",
            "response_source": "user_action"
       }
    }
 ],
. . .
}

{
. . .

"messages": [{
    "from": "{customer_phone_number}",
    "id": "wamid.sH0kFlaCGg0xcvZbgmg90lHrg2dL",
    "timestamp": "1767168000",
    "context": {
          "from": "{customer_phone_number}",
          "id": "wacid.gBGGF4lasdnlasdHrf2Mh-o"
    },
    "interactive": {
       "type":  "call_permission_reply",
        "call_permission_reply": {
            "response":"accept",
            "is_permanent":false,
            "expiration_timestamp": "1768550400",
            "response_source": "automatic"
       }
    }
 ],
. . .
}

{
. . .

"messages": [{
    "from": "{customer_phone_number}",
    "id": "wamid.sH0kFlaCGg0xcvZbgmg90lHrg2dL",
    "timestamp": "1767168000",
    "interactive": {
       "type":  "call_permission_reply",
        "call_permission_reply": {
            "response":"reject",
            "response_source": "automatic"
       }
    }
 ],
. . .
}