# polymorfa calls

> Place and manage calls, check consent, carry audio, and report on past calls.

## Commands

- [polymorfa calls accept](https://docs.polymorfa.com/cli/calls/accept): Answer or join a call.
- [polymorfa calls check](https://docs.polymorfa.com/cli/calls/check): Check whether a call can be placed.
- [polymorfa calls end](https://docs.polymorfa.com/cli/calls/end): End a call for everyone.
- [polymorfa calls export](https://docs.polymorfa.com/cli/calls/export): Export call detail records.
- [polymorfa calls hand](https://docs.polymorfa.com/cli/calls/hand): Raise or lower a call hand.
- [polymorfa calls invite](https://docs.polymorfa.com/cli/calls/invite): Invite a participant into a call.
- [polymorfa calls leave](https://docs.polymorfa.com/cli/calls/leave): Close one call connection.
- [polymorfa calls link create](https://docs.polymorfa.com/cli/calls/link-create): Create a WhatsApp call link.
- [polymorfa calls link preview](https://docs.polymorfa.com/cli/calls/link-preview): Preview a WhatsApp call link.
- [polymorfa calls list](https://docs.polymorfa.com/cli/calls/list): List one page of stored call records, newest first. Requires sessions:read and a server credential. Project tokens read only their original owning project. Reuse the same filters with --cursor.
- [polymorfa calls media](https://docs.polymorfa.com/cli/calls/media): Send and receive call audio as raw PCM.
- [polymorfa calls opt-outs add](https://docs.polymorfa.com/cli/calls/opt-outs-add): Add a person to the do-not-call list.
- [polymorfa calls opt-outs import](https://docs.polymorfa.com/cli/calls/opt-outs-import): Import entries into the do-not-call list.
- [polymorfa calls opt-outs list](https://docs.polymorfa.com/cli/calls/opt-outs-list): List the do-not-call list.
- [polymorfa calls opt-outs remove](https://docs.polymorfa.com/cli/calls/opt-outs-remove): Remove a person from the do-not-call list.
- [polymorfa calls permission get](https://docs.polymorfa.com/cli/calls/permission-get): Show a person’s call permission.
- [polymorfa calls permission request](https://docs.polymorfa.com/cli/calls/permission-request): Ask a person for permission to call them.
- [polymorfa calls place](https://docs.polymorfa.com/cli/calls/place): Place a call.
- [polymorfa calls place-group](https://docs.polymorfa.com/cli/calls/place-group): Place a WhatsApp group call.
- [polymorfa calls policy get](https://docs.polymorfa.com/cli/calls/policy-get): Read the team call policy.
- [polymorfa calls policy set](https://docs.polymorfa.com/cli/calls/policy-set): Replace the blocked country codes.
- [polymorfa calls react](https://docs.polymorfa.com/cli/calls/react): Send or clear a call reaction.
- [polymorfa calls reject](https://docs.polymorfa.com/cli/calls/reject): Decline a ringing call.
- [polymorfa calls retention get](https://docs.polymorfa.com/cli/calls/retention-get): Read team call data retention.
- [polymorfa calls retention set](https://docs.polymorfa.com/cli/calls/retention-set): Change team call data retention.
- [polymorfa calls ring](https://docs.polymorfa.com/cli/calls/ring): Ring an existing call participant again.
- [polymorfa calls settings get](https://docs.polymorfa.com/cli/calls/settings-get): Read session call settings.
- [polymorfa calls settings set](https://docs.polymorfa.com/cli/calls/settings-set): Change session call settings.
- [polymorfa calls stats](https://docs.polymorfa.com/cli/calls/stats): Summarize call volume, outcomes, and duration.
- [polymorfa calls view](https://docs.polymorfa.com/cli/calls/view): Read one stored call and its bounded metadata history. Requires sessions:read and a server credential. Use --json for participants, connections and reported diagnostics. No audio, video, event payload or webhook delivery data is returned.
- [polymorfa calls watch](https://docs.polymorfa.com/cli/calls/watch): Stream call updates for a session.

## polymorfa calls accept

Answer or join a call.

Answer a ringing call, or join a call another participant answered without a claim. --exclusive claims the call: other participants then get call_claimed and their connections close. Exits with code 4 when another participant claimed the call (call_claimed). Accepting does not attach media; use calls media or a browser client for that.

### Usage

```bash
polymorfa calls accept CALLID [flags]
```

### Arguments

- `CALLID` (required). Call ID.

### Flags

- `--exclusive` (boolean). Claim the call so no other participant can answer or join.
- `--participant <value>` (value). Server API keys only: participant that answers (default "default").
- `--video` (boolean). Answer with video, or --no-video for audio only.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls accept call_123
```

```bash
polymorfa calls accept call_123 --exclusive --participant agent-7 --json
```

## polymorfa calls check

Check whether a call can be placed.

Run the checks a call placement runs, without calling: the session’s calling switch, the team’s do-not-call list and blocked country codes, and on Cloud API numbers the person’s call permission and WhatsApp’s call limits. Prints allowed and the first refusal: calls_disabled, call_recipient_opted_out, call_destination_blocked, call_permission_required or call_limit_reached. The command exits with code 0 either way; read allowed from the output. Requires a server API key.

### Usage

```bash
polymorfa calls check TO [flags]
```

### Arguments

- `TO` (required). Phone number in E.164 form or a numeric WhatsApp user ID.

### Flags

- `--session <value>` (value, required). Session (number) that would place the call.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls check +14155550123 --session support
```

```bash
polymorfa calls check +14155550123 --session support --json
```

## polymorfa calls end

End a call for everyone.

End a call for every participant and close every connection. Repeating the command succeeds.

### Usage

```bash
polymorfa calls end CALLID [flags]
```

### Arguments

- `CALLID` (required). Call ID.

### Flags

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls end call_123
```

## polymorfa calls export

Export call detail records.

Export call detail records as CSV or newline-delimited JSON, newest first.

Each record has callId, projectId, sessionId, direction, upstream, outcome, state, hasVideo, peerRef, startedAt, connectedAt, endedAt, durationSeconds, and endReason. peerRef is a team-specific pseudonym of the other party, never a phone number.

The command requests every page until no records remain and writes one CSV header. Records go to standard output, or to --output. Progress and the next cursor go to standard error, as JSON lines with --json. --max-pages stops early; resume with --cursor and the same filters. When a page fails, the command reports the cursor that resumes from that page and exits non-zero.

Pass --project to read one project. Without it, a team API key reads every project in the team. A project token reads only its own project and requires --project. Credentials need the sessions:read scope.

### Usage

```bash
polymorfa calls export [flags]
```

### Flags

- `--cursor <value>` (value). Continue from this cursor, reported by an earlier export. Pass the same filters.
- `--direction <value>` (value). Include only inbound or outbound calls. Values: `inbound`, `outbound`.
- `--force` (boolean). Overwrite an existing --output file.
- `--format <value>` (value). Write CSV (one header row) or newline-delimited JSON. Values: `csv`, `ndjson`. Default: `csv`.
- `--limit <value>` (value). Request this many records per page. Default: `1000`.
- `--max-pages <value>` (value). Stop after this many pages and report the cursor for the rest.
- `--outcome <value>` (value). Include only calls with this outcome. answered includes answered calls still in progress; in_progress means still ringing. Values: `answered`, `missed`, `declined`, `failed`, `in_progress`.
- `-o, --output <value>` (value). Write records to this file instead of standard output. Use - for standard output.
- `--session <value>` (value). Include only calls on this session (number).
- `--since <value>` (value). Include calls that started at or after this RFC 3339 time.
- `--until <value>` (value). Include calls that started before this RFC 3339 time.
- `--upstream <value>` (value). Include only numbers that connect this way. Values: `linked_device`, `cloud_api`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls export --since 2026-09-01T00:00:00Z --output calls.csv
```

```bash
polymorfa calls export --project 018f0000-0000-7000-8000-000000000002 --format ndjson > calls.ndjson
```

```bash
polymorfa calls export --outcome missed --max-pages 1 --limit 100
```

```bash
polymorfa calls export --since 2026-09-01T00:00:00Z --cursor <cursor> --output rest.csv
```

## polymorfa calls hand

Raise or lower a call hand.

Raise or lower the Number’s hand. The Number has one hand state shared across its application connections.

### Usage

```bash
polymorfa calls hand CALLID [flags]
```

### Arguments

- `CALLID` (required). Call ID.

### Flags

- `--connection-id <value>` (value, required). Connection to close: 8 to 64 letters, digits, underscores, or hyphens.
- `--participant <value>` (value). Server API keys only: participant that owns the connection (default "default").
- `--raised` (boolean). Raise the hand; omit to lower it.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls hand call_123 --connection-id conn_0123456789 --raised
```

## polymorfa calls invite

Invite a participant into a call.

Ring another WhatsApp user into a call, turning a 1:1 call into a group call. The call must have a live leg. While WhatsApp restricts the number to people it has already chatted with, inviting anyone else exits with code 3 and number_restricted.

### Usage

```bash
polymorfa calls invite CALLID TARGET [flags]
```

### Arguments

- `CALLID` (required). Call ID.
- `TARGET` (required). Phone number in E.164 form or a numeric WhatsApp user ID.

### Flags

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls invite call_123 +15550101
```

## polymorfa calls leave

Close one call connection.

Close one media connection. The call and the participant’s other connections continue. Use calls end to end the call for everyone.

### Usage

```bash
polymorfa calls leave CALLID [flags]
```

### Arguments

- `CALLID` (required). Call ID.

### Flags

- `--connection-id <value>` (value, required). Connection to close: 8 to 64 letters, digits, underscores, or hyphens.
- `--participant <value>` (value). Server API keys only: participant that owns the connection (default "default").

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls leave call_123 --connection-id conn_0123456789
```

## polymorfa calls link create

Create a WhatsApp call link.

Create a WhatsApp call link from a Linked Device Number. It does not place or join a call. Requires a server API key or project token and calling enabled for the Number; client tokens and Cloud API-only Numbers are refused. The request is never retried: if the outcome is unknown, check before creating another link. Keep the link private.

### Usage

```bash
polymorfa calls link create [flags]
```

### Flags

- `--session <value>` (value, required). Linked Device session that owns the link.
- `--video` (boolean). Create a video link.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls link create --session support
```

```bash
polymorfa calls link create --session support --video --json
```

## polymorfa calls link preview

Preview a WhatsApp call link.

Read a WhatsApp call link through a Linked Device Number without joining the call. Pipe the link, or its token, on standard input so it stays out of shell history and process listings. A full link sets voice or video; pass --video with a bare video-link token. Requires a server API key or project token.

### Usage

```bash
polymorfa calls link preview [flags]
```

### Flags

- `--session <value>` (value, required). Linked Device session that reads the link.
- `--video` (boolean). The token belongs to a video link. Not needed with a full link.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
printf '%s' "$CALL_LINK" | polymorfa calls link preview --session support
```

```bash
printf '%s' "$TOKEN" | polymorfa calls link preview --session support --video --json
```

## polymorfa calls list

List one page of stored call records, newest first. Requires sessions:read and a server credential. Project tokens read only their original owning project. Reuse the same filters with --cursor.

### Usage

```bash
polymorfa calls list [flags]
```

### Flags

- `--cursor <value>` (value). Cursor from the previous page; reuse the same filters.
- `--direction <value>` (value). Include only inbound or outbound calls. Values: `inbound`, `outbound`.
- `--limit <value>` (value). Records per page. Default: `25`.
- `--outcome <value>` (value). Include only calls with this outcome. answered includes answered calls still in progress; in_progress means still ringing. Values: `answered`, `missed`, `declined`, `failed`, `in_progress`.
- `--session <value>` (value). Include only calls on this session (number).
- `--since <value>` (value). Include calls that started at or after this RFC 3339 time.
- `--until <value>` (value). Include calls that started before this RFC 3339 time.
- `--upstream <value>` (value). Include only numbers that connect this way. Values: `linked_device`, `cloud_api`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls list --outcome missed --limit 25
```

```bash
polymorfa calls list --project PROJECT_ID --json
```

## polymorfa calls media

Send and receive call audio as raw PCM.

Carry one call’s audio as raw PCM (signed 16-bit little-endian, mono, at the sample rate the call reports; 16 kHz by default). Without --place, the command waits for an inbound call that rings after it starts, then answers it, or joins it when another participant answered without a claim. Audio from --input is sent in real time; received audio is written to --output. Status goes to standard error, as JSON lines with --json. Ctrl-C leaves the call, or ends a call you placed that is still ringing. Exits with code 4 when another participant claimed the call.

### Usage

```bash
polymorfa calls media [CALLID] [flags]
```

### Arguments

- `CALLID` (optional). Inbound call to answer when it rings. Omit it to answer the next inbound call.

### Flags

- `--exclusive` (boolean). Claim the call so no other participant can answer or join it.
- `--input <value>` (value). Raw PCM file to send, or - for standard input.
- `--leave-on-eof` (boolean). Leave the call after all input audio is sent.
- `--muted` (boolean). Mute this connection while receiving call audio. Requires media-control support.
- `--output <value>` (value). File for received PCM, or - for standard output. Default: `-`.
- `--participant <value>` (value). Server API keys only: participant that carries the audio (default "default").
- `--place <value>` (value). Place a call to this E.164 number or user ID instead of answering one.
- `--session <value>` (value). Session of the call. Required with a server API key; client tokens use their bound session.
- `--video` (boolean). Request video for the call. This command carries audio only.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls media --session support --output call.pcm
```

```bash
polymorfa calls media --session support --place +15550100 --input prompt.pcm --leave-on-eof --output reply.pcm
```

```bash
sox in.wav -t raw -r 16000 -e signed -b 16 -c 1 - | polymorfa calls media call_123 --session support --input - --exclusive > out.pcm
```

## polymorfa calls opt-outs add

Add a person to the do-not-call list.

Add a person to the team’s do-not-call list by phone number or BSUID. From then on, calls to them are refused with call_recipient_opted_out, including calls your PBX places through a SIP trunk. Adding a person already on the list changes nothing and returns their entry (metadata.status 200 instead of 201). The list holds up to 100,000 entries; a full list fails with call_opt_out_limit (exit code 4). Requires a team API key.

### Usage

```bash
polymorfa calls opt-outs add [flags]
```

### Flags

- `--bsuid <value>` (value). WhatsApp business-scoped user ID.
- `--note <value>` (value). Why the person asked not to be called, 1 to 500 characters.
- `--phone-number <value>` (value). Phone number in E.164 format.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls opt-outs add --phone-number +14155550123 --note "Asked by phone on 2026-09-19"
```

```bash
polymorfa calls opt-outs add --bsuid US.13491208655302741918
```

## polymorfa calls opt-outs import

Import entries into the do-not-call list.

Add many people to the team’s do-not-call list from a file of up to 10 MiB. CSV needs a header row naming phoneNumber, bsuid and optionally note; each row names a phone number (E.164) or a BSUID. JSON is an array of {"phoneNumber" | "bsuid", "note"} objects, or an object with that array as "entries". The CLI sends 5,000 entries per request and reports the entries added, already listed and rejected, with each rejected entry's zero-based position (and CSV line). Running an import again is safe: entries already on the list are counted as already listed. Exit codes: 0 when every entry is listed; 12 when some entries were rejected, or when a later request failed after earlier batches were stored (run the import again); the request's own exit code when nothing was stored. Requires a team API key.

### Usage

```bash
polymorfa calls opt-outs import FILE [flags]
```

### Arguments

- `FILE` (required). CSV or JSON file, or - for standard input with --format.

### Flags

- `--format <value>` (value). File format; required for standard input. Defaults to the file extension. Values: `csv`, `json`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls opt-outs import do-not-call.csv
```

```bash
polymorfa calls opt-outs import entries.json --json
```

```bash
cat do-not-call.csv | polymorfa calls opt-outs import - --format csv
```

## polymorfa calls opt-outs list

List the do-not-call list.

List the team’s do-not-call list, newest first. One page is returned unless --paginate follows page.nextCursor up to --max-items entries; human output ends with the --cursor for the next page. --phone-number or --bsuid returns only that person’s entry, if any. Requires a team API key.

### Usage

```bash
polymorfa calls opt-outs list [flags]
```

### Flags

- `--bsuid <value>` (value). Return only the entry for this BSUID.
- `--cursor <value>` (value). Continue from page.nextCursor of an earlier page.
- `--limit <value>` (value). Entries per page, 1 to 500 (default 100).
- `--max-items <value>` (value). Stop --paginate after this many entries.
- `--paginate` (boolean). Request consecutive pages until --max-items entries are collected or no pages remain. Requires --max-items.
- `--phone-number <value>` (value). Return only the entry for this E.164 phone number.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls opt-outs list
```

```bash
polymorfa calls opt-outs list --phone-number +14155550123
```

```bash
polymorfa calls opt-outs list --paginate --max-items 100000 --json
```

## polymorfa calls opt-outs remove

Remove a person from the do-not-call list.

Remove one entry from the team’s do-not-call list. The person can be called again at once. Requires --yes and a team API key; an unknown ID fails with exit code 4.

### Usage

```bash
polymorfa calls opt-outs remove OPTOUTID [flags]
```

### Arguments

- `OPTOUTID` (required). Entry ID from `calls opt-outs list`.

### Flags

- `--yes` (boolean, required). Confirm that the person can be called again.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls opt-outs remove 0b9f6a52-8f0e-4a44-9d51-3c1f9d6f2a10 --yes
```

## polymorfa calls permission get

Show a person’s call permission.

Show whether a person allows a Cloud API number to call them: none, temporary (until expiresAt), permanent, or revoked. WhatsApp is asked on every request, and the answer includes its limits on permission requests and calls. When WhatsApp cannot be reached, the stored state is shown with fresh false. Linked-device numbers fail with unsupported_for_connection (exit code 4). Requires a server API key.

### Usage

```bash
polymorfa calls permission get TO [flags]
```

### Arguments

- `TO` (required). Phone number in E.164 form or a numeric WhatsApp user ID.

### Flags

- `--session <value>` (value, required). Cloud API session (number) that would call.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls permission get +14155550123 --session support
```

```bash
polymorfa calls permission get +14155550123 --session support --json
```

## polymorfa calls permission request

Ask a person for permission to call them.

Send a message that asks a person for permission to call them from a Cloud API number. WhatsApp shows --body above its allow and decline buttons, and the reply arrives as a call.permission_changed event. WhatsApp limits how often a number can ask the same person; when the limit is reached the command fails with call_permission_request_limited (exit code 5) and prints the Retry-After wait when WhatsApp gives one. A person who already granted permanent permission fails with call_permission_granted, and linked-device numbers with unsupported_for_connection (exit code 4).

### Usage

```bash
polymorfa calls permission request TO [flags]
```

### Arguments

- `TO` (required). Conversation ID, E.164 phone number, or BSUID.

### Flags

- `--body <value>` (value, required). Why you want to call, 1 to 1,024 characters.
- `--idempotency-key <value>` (value). Safely identify retries of this send operation.
- `--session <value>` (value, required). Cloud API session (number) that asks.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls permission request +14155550123 --session support --body "We would like to call you about your order."
```

## polymorfa calls place

Place a call.

Place a WhatsApp call from a session. The placing participant owns the call. Server API keys name the session with --session; client tokens place from the session they are bound to. While WhatsApp restricts the number to people it has already chatted with, a call to anyone else exits with code 3 and number_restricted.

### Usage

```bash
polymorfa calls place TO [flags]
```

### Arguments

- `TO` (required). Phone number in E.164 form or a numeric WhatsApp user ID.

### Flags

- `--exclusive` (boolean). Claim the call for the placing participant; other participants cannot join it.
- `--participant <value>` (value). Server API keys only: participant that places the call (default "default").
- `--session <value>` (value). Session that places the call. Required with a server API key.
- `--video` (boolean). Place a video call.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls place +15550100 --session support
```

```bash
polymorfa calls place +15550100 --session support --video --exclusive --participant agent-7 --json
```

## polymorfa calls place-group

Place a WhatsApp group call.

Place one WhatsApp group call by public group ID or to 2 to 31 distinct recipients from a Linked Device number. Each recipient must pass the number’s calling restrictions and your team’s destination policy. Cloud API numbers refuse this operation.

### Usage

```bash
polymorfa calls place-group [flags]
```

### Flags

- `--exclusive` (boolean). Claim the call for the placing participant; other participants cannot join it.
- `--group-id <value>` (value). Public group ID. Calls its 2 to 31 remote members after live consent checks.
- `--participant <value>` (value). Server API keys only: participant that places the call (default "default").
- `--session <value>` (value). Session that places the call. Required with a server API key.
- `--to <value>` (value, repeatable). E.164 phone number or public user ID. Repeat for each recipient.
- `--video` (boolean). Place a video call.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls place-group --to +15550100 --to +15550101 --session support
```

```bash
polymorfa calls place-group --group-id 9007199254740996 --session support
```

## polymorfa calls policy get

Read the team call policy.

Read the team call policy: the blocked country codes, the number of entries on the do-not-call list, and the revision to pass to `calls policy set --expected-revision`. The revision is 0 before the codes are first saved. Requires a team API key: a project token used as the API key is refused by the API (exit code 3), and a client token is not accepted for this command (exit code 2).

### Usage

```bash
polymorfa calls policy get [flags]
```

### Flags

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls policy get
```

## polymorfa calls policy set

Replace the blocked country codes.

Replace the team’s blocked country codes. Calls to phone numbers that start with a blocked code are refused with call_destination_blocked, and while any code is blocked, calls to a person whose phone number is not known are refused too. The list you pass replaces the stored list; --clear allows every country. Codes are country calling codes or longer dialing prefixes of 1 to 4 digits (44, 1876), at most 300. New calls use the new list at once; calls in progress continue. --expected-revision applies the change only if the policy still has that revision (see `calls policy get`); otherwise the command fails with state_conflict (exit code 4) and changes nothing. Requires a team API key.

### Usage

```bash
polymorfa calls policy set [flags]
```

### Flags

- `--blocked-country-codes <value>` (value, repeatable). Comma-separated country codes to block, replacing the stored list.
- `--clear` (boolean). Remove every blocked country code.
- `--expected-revision <value>` (value). Apply the change only if the policy still has this revision.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls policy set --blocked-country-codes 44,1876
```

```bash
polymorfa calls policy set --blocked-country-codes 44,1876 --expected-revision 3
```

```bash
polymorfa calls policy set --clear --expected-revision 4
```

## polymorfa calls react

Send or clear a call reaction.

Send a transient call reaction, or clear it. The connection must belong to the acting participant.

### Usage

```bash
polymorfa calls react CALLID [flags]
```

### Arguments

- `CALLID` (required). Call ID.

### Flags

- `--clear` (boolean). Clear the previous reaction.
- `--connection-id <value>` (value, required). Connection to close: 8 to 64 letters, digits, underscores, or hyphens.
- `--emoji <value>` (value). Reaction emoji; omit with --clear.
- `--participant <value>` (value). Server API keys only: participant that owns the connection (default "default").

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls react call_123 --connection-id conn_0123456789 --emoji 👍
```

## polymorfa calls reject

Decline a ringing call.

Decline a ringing call through the unified Calls API. Declining ends the call for every participant. Exits with code 4 when the call is no longer ringing (call_not_ringing). To reject a call through the Linked Device session route with the caller ID, use call reject.

### Usage

```bash
polymorfa calls reject CALLID [flags]
```

### Arguments

- `CALLID` (required). Call ID.

### Flags

- `--participant <value>` (value). Server API keys only: participant that declines (default "default").

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls reject call_123
```

```bash
polymorfa calls reject call_123 --participant agent-7 --json
```

## polymorfa calls retention get

Read team call data retention.

Read how long Polymorfa keeps your team’s call data from the Platform API. Deletion of call data older than the period starts on a date Polymorfa announces in its changelog; until then the setting records a choice and nothing is deleted. Teams without a saved setting return the default (extended, 90 days) at revision 0. Pass the revision to `calls retention set --expected-revision` so a change cannot overwrite another one. Requires a team API key or a project token with the sessions:read scope; client tokens are refused.

### Usage

```bash
polymorfa calls retention get [flags]
```

### Flags

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls retention get
```

## polymorfa calls retention set

Change team call data retention.

Change how long Polymorfa keeps your team’s call data through the Platform API. --policy short, standard, extended, or compliance keeps call data for 7, 30, 90, or 365 days; --policy custom keeps it for --days (1 to 2555). Deletion of call data older than the period starts on a date Polymorfa announces in its changelog; until then saving a period deletes nothing. Once deletion runs, a shorter period also applies to call data already stored, and deleted call data cannot be recovered, so the command asks you to confirm a shorter period; pass --yes to confirm without a prompt (required when standard input or error is not a terminal). --expected-revision is required: the command reads the setting first and changes it only if it still has that revision (see `calls retention get`); otherwise it fails with state_conflict (exit code 4) and changes nothing. Requires a team API key with the sessions:read and sessions:manage scopes, because the command reads the setting before it changes it; the API refuses project tokens (exit code 3).

### Usage

```bash
polymorfa calls retention set [flags]
```

### Flags

- `--days <value>` (value). Days to keep call data (1 to 2555). Required with --policy custom; with a named policy, omit it or pass that policy’s period.
- `--expected-revision <value>` (value, required). Apply the change only if the setting still has this revision (0 while your team uses the default).
- `--policy <value>` (value, required). Retention policy: short (7 days), standard (30), extended (90), compliance (365), or custom (--days). Values: `short`, `standard`, `extended`, `compliance`, `custom`.
- `--yes` (boolean). Confirm a shorter period, which permanently deletes stored call data older than it, without prompting.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls retention set --policy compliance --expected-revision 0
```

```bash
polymorfa calls retention set --policy custom --days 180 --expected-revision 2
```

```bash
polymorfa calls retention set --policy short --expected-revision 3 --yes
```

## polymorfa calls ring

Ring an existing call participant again.

Ring a non-connected WhatsApp participant already in the call roster. Re-ring applies the same destination permissions and restrictions as an invitation. It does not add a participant or mark them connected.

### Usage

```bash
polymorfa calls ring CALLID TARGET [flags]
```

### Arguments

- `CALLID` (required). Call ID.
- `TARGET` (required). E.164 phone number or public user ID already in the call roster.

### Flags

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls ring call_123 +15550100
```

## polymorfa calls settings get

Read session call settings.

Read a session’s call settings from the Platform API. Sessions without saved settings return the defaults at revision 0. Pass the revision to `calls settings set --expected-revision` so a change cannot overwrite another one. After simultaneous calls are turned off, it also prints when the Ban Insurance exclusion ends (simultaneousCallsCoverageExcludedUntil), until that time passes. Ban Insurance excludes a ban when simultaneous calls were on during the 30 days before it; this timestamp is the cutoff for a new ban from that period. No end is printed while simultaneous calls are on, and a missing end does not mean the number is covered. Requires a server API key.

### Usage

```bash
polymorfa calls settings get [flags]
```

### Flags

- `--session <value>` (value, required). Session ID.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls settings get --session support
```

## polymorfa calls settings set

Change session call settings.

Change a session’s call settings through the Platform API. Settings you do not pass keep their current values; --inbound-route sip_trunk without --sip-trunk keeps the stored trunk. --calls-enabled=false turns calling off for the session: placing, answering and joining calls fail, incoming calls are declined and SIP trunks cannot call through it, while calls in progress continue. --expected-revision applies the change only if the settings still have that revision (see `calls settings get`); otherwise the command fails with state_conflict (exit code 4) and changes nothing. --conference-mode (on by default) lets every participant you connect to a call (apps, bots and SIP trunk callers) hear the WhatsApp party and each other; --no-conference-mode lets each hear only the WhatsApp party. The WhatsApp party always hears all of your participants, and nobody hears their own audio. --inbound-route sip_trunk also sends incoming calls to --sip-trunk, and --sip-claim controls whether the trunk’s answer claims the call. --host-cloud-api-calls=true has Polymorfa Calls answer a Cloud API session’s incoming calls instead of your Graph API integration. --simultaneous-calls=true lets a linked-device number hold any number of calls at once (incoming, placed and campaign calls); Cloud API numbers ignore it. WhatsApp’s own apps never hold two calls at once, and while it is on, and for 30 days after you turn it off, Ban Insurance does not cover a ban of the number. Turning it on therefore requires --acknowledge-risk, and the command exits with code 2 without changing anything when that flag is missing. After --simultaneous-calls=false, the output shows when the Ban Insurance exclusion ends, from the server’s response. Only a team API key can turn it on; --simultaneous-calls=false needs no acknowledgment. Requires a server API key.

### Usage

```bash
polymorfa calls settings set [flags]
```

### Flags

- `--acknowledge-risk` (boolean). Confirm that turning simultaneous calls on removes Ban Insurance cover for the number. Required with --simultaneous-calls=true.
- `--calls-enabled <value>` (value). Allow calls on the session (false turns calling off). Values: `true`, `false`.
- `--conference-mode` (boolean). Let your participants hear each other as well as the WhatsApp party (--no-conference-mode: only the WhatsApp party).
- `--expected-revision <value>` (value). Apply the change only if the settings still have this revision.
- `--host-cloud-api-calls <value>` (value). On a Cloud API session, answer incoming calls with Polymorfa Calls (false leaves them to your Graph API integration). Values: `true`, `false`.
- `--inbound-route <value>` (value). Where incoming calls ring: clients, or sip_trunk to also send them to a SIP trunk. Values: `clients`, `sip_trunk`.
- `--session <value>` (value, required). Session ID.
- `--simultaneous-calls <value>` (value). Let a linked-device number hold any number of calls at once (true requires --acknowledge-risk; false turns it off). Values: `true`, `false`.
- `--sip-claim <value>` (value). Whether an answer from the SIP trunk claims the call and stops other clients ringing. Values: `true`, `false`.
- `--sip-trunk <value>` (value). SIP trunk ID that receives incoming calls.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls settings set --session support --calls-enabled=false
```

```bash
polymorfa calls settings set --session support --no-conference-mode
```

```bash
polymorfa calls settings set --session support --calls-enabled=false --expected-revision 3
```

```bash
polymorfa calls settings set --session support --inbound-route sip_trunk --sip-trunk 6f1c2f0e-1d5b-4d8e-9a55-0d4b8a6c1f10
```

```bash
polymorfa calls settings set --session support --inbound-route clients
```

```bash
polymorfa calls settings set --session support --simultaneous-calls=true --acknowledge-risk
```

```bash
polymorfa calls settings set --session support --simultaneous-calls=false
```

## polymorfa calls stats

Summarize call volume, outcomes, and duration.

Summarize calls: counts by outcome, answer rate, and connected time, grouped by day, hour, session, or outcome.

The range defaults to the last 7 days. --group-by day covers at most 366 days and --group-by hour at most 31. Day and hour buckets, and the heatmap, use --timezone (UTC by default).

Pass --project to read one project. Without it, a team API key reads every project in the team. A project token reads only its own project and requires --project. Credentials need the sessions:read scope.

### Usage

```bash
polymorfa calls stats [flags]
```

### Flags

- `--direction <value>` (value). Include only inbound or outbound calls. Values: `inbound`, `outbound`.
- `--group-by <value>` (value). Group the results by day, hour, session, or outcome. Values: `day`, `hour`, `session`, `outcome`. Default: `day`.
- `--heatmap` (boolean). Also print calls by day of week and hour. --json always includes the heatmap.
- `--outcome <value>` (value). Include only calls with this outcome. answered includes answered calls still in progress; in_progress means still ringing. Values: `answered`, `missed`, `declined`, `failed`, `in_progress`.
- `--session <value>` (value). Include only calls on this session (number).
- `--since <value>` (value). Include calls that started at or after this RFC 3339 time.
- `--timezone <value>` (value). IANA time zone for day and hour groups and the heatmap, such as Europe/Lisbon. UTC offsets are not accepted.
- `--until <value>` (value). Include calls that started before this RFC 3339 time.
- `--upstream <value>` (value). Include only numbers that connect this way. Values: `linked_device`, `cloud_api`.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls stats
```

```bash
polymorfa calls stats --project 018f0000-0000-7000-8000-000000000002 --group-by session
```

```bash
polymorfa calls stats --since 2026-09-01T00:00:00Z --until 2026-09-02T00:00:00Z --group-by hour --timezone Europe/Lisbon
```

```bash
polymorfa calls stats --direction inbound --outcome missed --heatmap
```

```bash
polymorfa calls stats --json
```

## polymorfa calls view

Read one stored call and its bounded metadata history. Requires sessions:read and a server credential. Use --json for participants, connections and reported diagnostics. No audio, video, event payload or webhook delivery data is returned.

### Usage

```bash
polymorfa calls view ID [flags]
```

### Arguments

- `ID` (required). Call ID from calls list.

### Flags

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls view CALL_ID --json
```

## polymorfa calls watch

Stream call updates for a session.

Stream a session’s inbound calls and their progress: ringing, claims, state and participant changes, and endings. Watching never answers or declines a call. With --json, each line is one JSON object. Press Ctrl-C to stop. Exits with code 3 when the API stops authorizing the credential.

### Usage

```bash
polymorfa calls watch [flags]
```

### Flags

- `--count <value>` (value). Exit after this many call updates.
- `--participant <value>` (value). Server API keys only: participant that watches (default "default").
- `--session <value>` (value). Session to watch. Required with a server API key; client tokens watch their bound session.

Also accepts the [global flags](https://docs.polymorfa.com/cli#global-flags).

### Examples

```bash
polymorfa calls watch --session support
```

```bash
polymorfa calls watch --session support --participant agent-7 --json
```

```bash
POLYMORFA_CLIENT_TOKEN=... polymorfa calls watch --count 1 --json
```
