Call permissions and opt-outs
Ask people for permission to call them, keep a do-not-call list and block country codes for your team's calls.
Two sets of rules decide whether a call you place goes through:
- WhatsApp's call permission. Before a Cloud API Number calls someone, that person must allow your business to call them. Linked-device Numbers do not use call permission.
- Your team's call policy. A do-not-call list and blocked country codes that Polymorfa applies to every call your team places, from every Number and project.
The call policy applies to calls placed from the API, the SDKs and browsers, to invites, and to calls your phone system places through a SIP trunk. Call permission applies to calls from Cloud API Numbers. Neither affects incoming calls.
Check a call before you place it#
API Check call runs every check without calling. It needs a server credential with sessions:read.
curl -X POST "https://api.polymorfa.com/messaging/voip/calls/check" \
-H "Authorization: Bearer $POLYMORFA_KEY" \
-H "Content-Type: application/json" \
-d '{ "session": "support", "to": "+14155550123" }'const check = await messaging.voip.check({ session: "support", to: "+14155550123" });
if (!check.data.data.allowed) {
console.log("Call would fail:", check.data.data.refusal);
}The response reports allowed, the first refusal and, on a Cloud API Number, the person's permission:
refusal | Cause |
|---|---|
calls_disabled | Calling is turned off for the Number |
call_recipient_opted_out | The person is on your do-not-call list |
call_destination_blocked | Your call policy blocks the person's country code |
call_permission_required | The person has not allowed this Cloud API Number to call them |
call_limit_reached | WhatsApp's call limits for this person do not allow a call now |
Placing the call runs the checks again. See Check call.
Ask for call permission#
This applies to Cloud API Numbers only.
Read the person's permission
cURL curl "https://api.polymorfa.com/messaging/support/call-permissions/%2B14155550123" \ -H "Authorization: Bearer $POLYMORFA_KEY"TypeScript const permission = await messaging.voip.retrieveCallPermission("support", "+14155550123"); console.log(permission.data.data.status);statusisnone,temporary(granted untilexpiresAt),permanentorrevoked(declined or withdrawn, including by WhatsApp after unanswered calls). Polymorfa asks WhatsApp on every request. Whenfreshistrue,actions.requestPermissionandactions.startCallreport whether WhatsApp allows a request or a call now, with its limits. When WhatsApp cannot be reached,freshisfalseand the stored state is returned. A linked-device Number returns409 unsupported_for_connection. See Get call permission.Send a call permission request
Send a message with
callPermissionRequest. Itsbody, 1 to 1,024 characters, tells the person why you want to call; WhatsApp shows it above its allow and decline buttons.cURL curl -X POST "https://api.polymorfa.com/messaging/support/messages/send" \ -H "Authorization: Bearer $POLYMORFA_KEY" \ -H "Content-Type: application/json" \ -d '{ "conversation": { "phoneNumber": "+14155550123" }, "content": { "callPermissionRequest": { "body": "Can we call you about order 1522?" } } }'TypeScript await messaging.messages.send("support", { conversation: { phoneNumber: "+14155550123" }, content: { callPermissionRequest: { body: "Can we call you about order 1522?" } }, });WhatsApp allows one request to a person every 24 hours and two every 7 days; a connected call resets the limits.
Status and code Cause 429 call_permission_request_limitedWhatsApp's request limit for this person was reached. Wait for Retry-Afterwhen sent409 call_permission_grantedThe person already granted permanent permission. Place the call instead 409 unsupported_for_connectionThe Number is not a Cloud API Number Receive the answer
Subscribe a webhook to
call.permission_changed. It carries the person'sstatusandpreviousStatus,expiresAtfor a temporary permission, andsource:sourceMeaning user_actionThe person answered a request or changed the permission in WhatsApp automaticWhatsApp granted it when the person called you, or withdrew it after unanswered calls syncReading the permission found a different state call_refusedWhatsApp refused a call for lack of permission No event is sent when a temporary permission expires.
Keep a do-not-call list#
Calls to anyone on the list are refused from every Number in the team with 403 call_recipient_opted_out. Add people who asked not to be called. The list holds up to 100,000 entries, each a phone number in E.164 format or a WhatsApp user ID (BSUID), with an optional note of up to 500 characters.
Console
Open Calls in a project and choose the Call policy tab. The Do-not-call list tab opens first. Every team member can see the list; team owners and admins change it.
- Select Add entry, enter a Phone number or WhatsApp user ID and an optional note, then select Add.
- Select Import to paste entries, one per line with an optional note in the next column, or choose a CSV file. Entries already on the list stay unchanged.
- Use Find to look up a phone number or user ID, and the row's remove action to take someone off the list.
API
curl -X POST "https://api.polymorfa.com/platform/call-opt-outs" \
-H "Authorization: Bearer $POLYMORFA_TEAM_KEY" \
-H "Content-Type: application/json" \
-d '{ "phoneNumber": "+14155550123", "note": "Asked not to be called" }'const added = await platform.callOptOuts.create({
phoneNumber: "+14155550123",
note: "Asked not to be called",
});
for await (const entry of await platform.callOptOuts.list({ limit: 100 })) {
console.log(entry.id, entry.phoneNumber ?? entry.bsuid);
}
await platform.callOptOuts.delete(added.data.id);Send exactly one of phoneNumber or bsuid. A new entry returns 201; an entry already on the list returns 200 with the existing entry. API Import call opt outs adds up to 5,000 entries in one request and lists invalid ones in rejected. List entries, newest first, with API List call opt outs, and remove one with API Delete call opt out. The list is a team resource: use a team key, with sessions:read to read and sessions:manage to change it. Project tokens and client tokens are refused with 403. A list that would pass 100,000 entries returns 409 call_opt_out_limit. Matching uses the identifier you stored: a phone number entry does not block a call addressed by user ID.
TypeScript:
Use the team client. platform.callOptOuts.import({ entries }) adds up to 5,000 entries at once.
Block country codes#
Calls to phone numbers that start with a blocked code are refused with 403 call_destination_blocked. Codes are country calling codes or longer dialing prefixes of 1 to 4 digits without +: 44 blocks the United Kingdom, and 1876 blocks Jamaica without blocking the rest of +1. A team can block up to 300 codes. While any code is blocked, calls to people whose phone number is unknown, for example when only their WhatsApp user ID is known, are refused too.
Console
Open Calls, choose the Call policy tab, then Blocked country codes, and enter the codes under Blocked codes, separated by commas or new lines. Select Save blocked codes. Leave the field empty to allow every country. If someone else changed the codes while you were editing, the Console shows the latest list; review it and save again.
API
curl -X PUT "https://api.polymorfa.com/platform/call-policy" \
-H "Authorization: Bearer $POLYMORFA_TEAM_KEY" \
-H "Content-Type: application/json" \
-d '{ "blockedCountryCodes": ["44", "1876"], "expectedRevision": 0 }'const policy = await platform.callPolicy.retrieve();
await platform.callPolicy.update({
blockedCountryCodes: ["44", "1876"],
expectedRevision: policy.data.revision,
});The list replaces the stored one; send an empty list to allow every country. Read the policy, with its revision and the size of the do-not-call list, with API Get call policy. A stale expectedRevision returns 409 state_conflict. Use a team key, with sessions:read to read and sessions:manage to change. See Update call policy.
TypeScript:
Use the team client. update replaces the whole list.
New calls are checked against a change at once; calls in progress continue. If the policy cannot be read, the call is refused with 503 rather than placed without it.