# Add calling to a web app

> Place and answer WhatsApp calls in the browser with a client token and the prebuilt call components.

Your users place and answer WhatsApp calls from a page in your web app. The
browser connects their microphone, camera and speakers to the call, and the
call components render the ringing card, the call stage and the controls.

> **Note**
>
> **Before you begin**
>
> - A connected Number in your project. See
>   [How calls work](https://docs.polymorfa.com/calls/how-calls-work#linked-device-and-cloud-api-numbers)
>   for what each connection type supports.
> - A server route that can mint client tokens with a team key or project token.
>   Team keys and project tokens never reach the browser.
> - The calling packages, `@polymorfa/browser` and `@polymorfa/react`, or
>   `@polymorfa/elements` for plain HTML. See
>   [Install the TypeScript SDK](https://docs.polymorfa.com/get-started/development-environment#install-the-typescript-sdk)
>   for installation.

## Allow call actions for the Number

A browser acts on calls with a client token bound to one Number. Enable the
call actions the browser needs in that Number's
[client rules](https://docs.polymorfa.com/development/client-tokens#session-rules):

| Action | Allows |
| --- | --- |
| `voip_place` | Placing calls, inviting participants and connecting to calls you place |
| `voip_answer` | Answering, joining and declining calls, and connecting to calls you answer or join |
| `voip_signal` | Receiving call events, keeping connections alive, leaving and ending calls |

The browser client needs all three to place and answer calls. A client token
acts only on calls of the Number it is bound to, and that Number must still
belong to the token's project.

## Mint client tokens on your server

Add a route on your own origin that returns a client token for the signed-in
user. The browser client calls `/api/polymorfa/token` by default.

Your route calls [`POST /platform/client-tokens`](https://docs.polymorfa.com/development/client-tokens#mint)
with the Number in `session` and a stable ID for the user in `ephemeralId`. The
user acts in calls as `client:<ephemeralId>`, so the ID must use only `A-Z`,
`a-z`, `0-9`, `.`, `_`, `:`, `@` and `-`, up to 128 characters. Otherwise call
requests return `403`.

Client tokens expire. The browser client asks your route for a fresh token and
renews it on open connections before it expires. When a token is revoked or
stops authorizing the Number, the client reports an `unauthorized` error and
asks your route again. It does the same when Polymorfa cannot confirm the token
for 3 minutes because checks are rate limited or temporarily unavailable.

## Connect and render the call interface

**React**

```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} exclusive={false} />
  <DialPad controller={calls.controller} />
</PolymorfaProvider>;
```

**HTML**

Assign the same controller to the `<pmfa-call>` element from
`@polymorfa/elements`. See [pmfa-call](https://docs.polymorfa.com/ui-kit/calls#pmfa-call).

`calls.connect()` opens the call event connection and rejects if the first
attempt fails. `CallSurface` shows ringing calls, the call stage, participant
video, the participant list, and controls for the microphone, camera, devices,
leaving and ending the call. Each part is also available on its own; see
[Call components](https://docs.polymorfa.com/ui-kit/calls).

## Place a call

```ts
await calls.controller.place("+15550100", { video: true });
```

The call rings on the callee's device. `DialPad` places calls the same way.
On a Cloud API Number, the recipient must first
[grant call permission](https://docs.polymorfa.com/calls/permissions), and calls are audio only.

## Answer incoming calls

Every inbound call on the Number rings in each connected browser. Several calls
can ring at once; the controller lists them in `snapshot.invitations` and never
declines a call for you.

`exclusive` on `CallSurface` decides what an answer does. With `true`, the
first person to answer claims the call and it stops ringing for everyone else.
With `false`, others keep ringing and can join. When another participant claims
a call, the interface marks it as claimed elsewhere; do not decline it, because
declining ends the call for the person who answered. See
[Answer, join, decline and claim](https://docs.polymorfa.com/calls/how-calls-work#answer-join-decline-and-claim).

## Build your own interface

Read `calls.controller.getSnapshot()` and call `place`, `answer`, `join`,
`reject`, `leave`, `end`, `setMuted` and `switchDevice` on the controller. Each
remote participant's video is a separate stream in `controller.remoteVideos`,
labeled with the participant.

## Diagnostics

The browser client sends call diagnostics by default: connection quality
figures every 15 seconds and when a connection closes, and an error code when
media fails. Reports carry no personal data. Pass `diagnostics: false` to
`createBrowserCalls` to send none. The Console shows the reports on the call's
details; see [App-reported diagnostics](https://docs.polymorfa.com/calls/records#report-call-diagnostics-from-your-app).

## Release the client

Call `await calls.dispose()` when your app releases the calling interface.
Calls you joined are left, not ended, and a call you placed that is still
ringing is ended.

## Test the integration

1. Open your page in two browser tabs signed in as different users.
2. Call the Number from a phone. Both tabs ring.
3. Answer in one tab. With `exclusive` set to `true`, the other tab stops
   ringing.
4. End the call, then open **Calls** in the Console to see its participants,
   connections and quality figures.

## See also

- [Call components](https://docs.polymorfa.com/ui-kit/calls)
- [Client tokens](https://docs.polymorfa.com/development/client-tokens)
- [How calls work](https://docs.polymorfa.com/calls/how-calls-work)
- [Control calls from your server](https://docs.polymorfa.com/calls/server)
