# Calls

> Ring, answer, place and control WhatsApp calls in the browser with prebuilt call components.

The call components render WhatsApp calls in your web app: the incoming call
card, the call stage with participant video, the control dock, the participant
list and a dial pad. They all render from one `CallsController`, created by the
browser Calls client.

For how calls work, the call actions and their limits, see the
[Calls guide](https://docs.polymorfa.com/calls).

## Set up the Calls client

```tsx
import { createBrowserCalls, createClientTokenProvider } from "@polymorfa/browser";
import { CallSurface, DialPad, PolymorfaProvider } from "@polymorfa/react";

// Create once in the browser. Call dispose() when your app releases it.
const calls = createBrowserCalls({
  session: "support",
  getClientToken: createClientTokenProvider(),
});
await calls.connect();

<PolymorfaProvider>
  <CallSurface controller={calls.controller} resolveName={lookupContactName} />
  <DialPad controller={calls.controller} />
</PolymorfaProvider>;
```

`createClientTokenProvider()` posts to `/api/polymorfa/token` on your origin;
pass `{ path }` to use another route. The client token is the only credential.
Enable `voip_place`, `voip_answer` and `voip_signal` in the session's
[client rules](https://docs.polymorfa.com/development/client-tokens#session-rules) to place and answer calls.

| Option | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `session` | `string` | Yes | | Local call identity. Requests use the session bound to the client token. |
| `getClientToken` | `() => Promise<string \| ClientToken>` | Yes | | Returns a client token. Called again when the token expires or is refused. |
| `baseUrl` | `string` | No | `https://api.polymorfa.com` | API origin. |
| `diagnostics` | `boolean` | No | `true` | Sends connection quality figures every 15 seconds and when a connection closes, and an error code when media fails. No personal data is sent. |
| `onError` | `({ code, message }) => void` | No | | Failures that do not belong to one call. `unauthorized` means the token was refused; the next attempt asks for a new one. |

`calls.connect()` opens the call event connection and rejects if the first
attempt fails. `calls.dispose()` releases media and the connection: calls you
joined are left, not ended, and a call you placed that is still ringing is
ended.

Inside a provider with `tokenEndpoint`, `<CallButton/>` creates and shares a
Calls client for you. See [CallButton](#callbutton).

## CallSurface

The complete call experience in one component: a fixed overlay with the
incoming call card while a call rings, and the stage, control dock and
participant list during a call. A pop-out button moves the call into its own
resizable window; closing that window or ending the call brings it back.

All 11 `CallSurface` props, with types, defaults and a live preview, are on the [CallSurface](https://docs.polymorfa.com/ui-kit/components/call-surface) page.

## Answering and claims

`exclusive` on `CallSurface`, `IncomingCallCard` and `<pmfa-call>` decides what
Answer does:

- `false` (default): the call is answered without a claim. Other participants
  keep ringing and can join.
- `true`: Answer claims the call. Other participants stop ringing and cannot
  join.

The components never decline a call on their own. A call another participant
answered without a claim shows Join and Dismiss. A call another participant
claimed shows "Answered by another participant" and only Dismiss, because
declining would end the call for the participant who answered. Other waiting
calls are listed under the card with a Show button.

## Individual parts

Compose these when you need your own layout. Each takes `controller` or
`createController` and `className`.

### IncomingCallCard

The ringing window: name, "WhatsApp audio call" or "WhatsApp video call",
an avatar for audio or a mirrored self-preview for video, then Reject and
Answer. On a video call, camera and microphone toggles and a device menu sit on
the preview. Answering with the camera off still prepares video muted, so the
camera can be turned on during the call.

All 8 `IncomingCallCard` props, with types, defaults and a live preview, are on the [IncomingCallCard](https://docs.polymorfa.com/ui-kit/components/incoming-call-card) page.

While an answer is in progress, Answer, Join, Reject and the camera and
microphone choices are disabled. A failed answer shows a notice on the card.

### CallStage

The in-call view: one video tile per remote participant when anyone sends
video, otherwise a centered avatar. Your camera shows as a picture-in-picture
tile. The name line alternates between the number and the call duration. Call
audio plays through one hidden element and follows the selected speaker. The
stage is always dark.

All 8 `CallStage` props, with types, defaults and a live preview, are on the [CallStage](https://docs.polymorfa.com/ui-kit/components/call-stage) page.

### ParticipantVideoGrid

One tile per remote participant video, keyed by participant or connection so a
tile survives camera and source changes. Videos are separate streams. Tiles are
muted video elements with an accessible name ("Video from …") and a visible
label. Renders nothing without remote video. Takes `labelVideo`.

### ParticipantList

The call's WhatsApp participants and their state. `resolveName(participant)`
supplies display names.

### CallControls

The control dock: a camera group (toggle and camera picker), a microphone
group (toggle, microphone and speaker picker), and a red end call button. The
camera group shows when the line can carry video and is disabled until the call
connects. On an audio call, the camera button upgrades the call to video. When
the call supports them, the dock also offers screen sharing, raise hand and
reactions.

All 5 `CallControls` props, with types, defaults and a live preview, are on the [CallControls](https://docs.polymorfa.com/ui-kit/components/call-controls) page.

When Leave shows, the red button is labelled "End call for everyone". A call
this browser placed shows only Hang up until it connects, because leaving would
keep the other person ringing. If ending fails, the call stays active, the
controls remain available and a localized message explains the failure.

### DialPad

A number field in E.164 form with a keypad and call buttons.

All 6 `DialPad` props, with types, defaults and a live preview, are on the [DialPad](https://docs.polymorfa.com/ui-kit/components/dial-pad) page.

### Hooks and helpers

| Export | Description |
| --- | --- |
| `useCallDuration(snapshot)` | Seconds since the call connected, updated every second. Keeps counting through a reconnect. |
| `formatDuration(seconds)` | Formats as `m:ss`, or `h:mm:ss` past an hour. |
| `useCallPopout(title?)` | Opens and closes a separate call window and returns a container to render into. |
| `injectCallsStyles()` | Adds the call stylesheet to the document once. Safe during server rendering. |

## CallButton

Places a call from a phone number, for example in a contact panel. It uses the
provider's client token and shows `CallSurface` after placing. The button is
hidden unless the grant allows `voip_place`.

```tsx
<PolymorfaProvider tokenEndpoint="/api/polymorfa/token">
  <CallButton to="+15551234567" />
</PolymorfaProvider>
```

All 9 `CallButton` props, with types, defaults and a live preview, are on the [CallButton](https://docs.polymorfa.com/ui-kit/components/call-button) page.

## CallNumberPicker

Chooses which of your Numbers places outgoing calls. Create one Calls client per
Number, each with its own token route authorized for that Number's session, and
pass them as options. Use the selected client's controller for `DialPad`.

All 5 `CallNumberPicker` props, with types, defaults and a live preview, are on the [CallNumberPicker](https://docs.polymorfa.com/ui-kit/components/call-number-picker) page.

The picker locks while any of its clients is placing, answering or on a call.
It does not discover Numbers, mint tokens or move an existing call to another
Number.

## pmfa-call

The Web Component renders the incoming call card, the in-call controls and the
participant list from the same controller. Participant video tiles are React
only.

```ts
import { createBrowserCalls, createClientTokenProvider } from "@polymorfa/browser";
import { defineCallElements } from "@polymorfa/elements";

defineCallElements();
const calls = createBrowserCalls({
  session: "support",
  getClientToken: createClientTokenProvider(),
});
await calls.connect();
document.querySelector("pmfa-call").controller = calls.controller;
```

```html
<pmfa-call exclusive></pmfa-call>
```

| Attribute or property | Type | Description |
| --- | --- | --- |
| `exclusive` | Boolean attribute or property | Answering claims the call. |
| `controller` | `CallsController` | Calls state. |
| `configuration` | `{ appearance?, locale?, stylesheet? }` | Appearance, text and extra CSS. |

Style it with these parts: `panel`, `answer`, `join`, `reject`, `dismiss`,
`claimed`, `failure`, `invitations`, `invitation`, `show`, `mute`, `camera`,
`screen-share`, `reaction`, `clear-reaction`, `leave`, `hangup` and
`participants`. Answer and Join also carry the `primary` part. The element dispatches
`pmfa-state-change` with the calls snapshot and `pmfa-render` after each render.

## Accessibility

- Every control has an accessible name, and toggles report their state with
  `aria-pressed`. Device menus report `aria-expanded`.
- Focused controls show a visible outline.
- All motion stops under `prefers-reduced-motion: reduce`.
- Failures, such as a failed answer or hang up, are shown as text, not color
  alone.

## Related

- [Calls guide](https://docs.polymorfa.com/calls)
- [Control calls from your server](https://docs.polymorfa.com/calls/server)
- [Client tokens](https://docs.polymorfa.com/development/client-tokens)
