# 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](https://docs.polymorfa.com/calls/sip-trunks). Call permission applies to calls from Cloud
API Numbers. Neither affects incoming calls.

## Check a call before you place it

`POST /messaging/voip/calls/check` runs every check without calling. It needs a
server credential with `sessions:read`.

```bash 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 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`:

| `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](https://docs.polymorfa.com/api/calls/check-call).

## Ask for call permission

This applies to Cloud API Numbers only.

### Read the person's permission

```bash cURL
curl "https://api.polymorfa.com/messaging/support/call-permissions/%2B14155550123" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript 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](https://docs.polymorfa.com/api/calls/get-call-permission).

### 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.

```bash 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 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_limited` | WhatsApp's request limit for this person was reached. Wait for `Retry-After` when sent |
| `409 call_permission_granted` | The person already granted permanent permission. Place the call instead |
| `409 unsupported_for_connection` | The Number is not a Cloud API Number |

### 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`:

| `source` | Meaning |
| --- | --- |
| `user_action` | The person answered a request or changed the permission in WhatsApp |
| `automatic` | WhatsApp granted it when the person called you, or withdrew it after unanswered calls |
| `sync` | Reading the permission found a different state |
| `call_refused` | WhatsApp 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:**

```bash 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 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.
`POST /platform/call-opt-outs/import` adds up to 5,000 entries in one request
and lists invalid ones in `rejected`. List entries, newest first, with
`GET /platform/call-opt-outs`, and remove one with
`DELETE /platform/call-opt-outs/{optOutId}`. 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:**

```bash 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 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
`GET /platform/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](https://docs.polymorfa.com/api/call-consent/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

- [How calls work](https://docs.polymorfa.com/calls/how-calls-work#linked-device-and-cloud-api-numbers)
- [Calling best practices](https://docs.polymorfa.com/calls/best-practices)
- [Errors](https://docs.polymorfa.com/api/errors#call-permission-required)
