Skip to content
Shortcut: /, ⌘K or Ctrl+K

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.

View as Markdown

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
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" }'
TypeScript
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:

refusalCause
calls_disabledCalling is turned off for the Number
call_recipient_opted_outThe person is on your do-not-call list
call_destination_blockedYour call policy blocks the person's country code
call_permission_requiredThe person has not allowed this Cloud API Number to call them
call_limit_reachedWhatsApp'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.

  1. 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);

    status is none, temporary (granted until expiresAt), permanent or revoked (declined or withdrawn, including by WhatsApp after unanswered calls). Polymorfa asks WhatsApp on every request. When fresh is true, actions.requestPermission and actions.startCall report whether WhatsApp allows a request or a call now, with its limits. When WhatsApp cannot be reached, fresh is false and the stored state is returned. A linked-device Number returns 409 unsupported_for_connection. See Get call permission.

  2. Send a call permission request

    Send a message with callPermissionRequest. Its body, 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 codeCause
    429 call_permission_request_limitedWhatsApp's request limit for this person was reached. Wait for Retry-After when sent
    409 call_permission_grantedThe person already granted permanent permission. Place the call instead
    409 unsupported_for_connectionThe Number is not a Cloud API Number
  3. Receive the answer

    Subscribe a webhook to call.permission_changed. It carries the person's status and previousStatus, expiresAt for a temporary permission, and source:

    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
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" }'
TypeScript
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
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 }'
TypeScript
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.

See also#