Calls
Ring, answer, place and control WhatsApp calls in the browser with prebuilt call components.
Customize
Explore with sample data. Messages, calls and template actions stay in this demo.
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.
Set up the Calls client #
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 to place and answer calls.
sessionstringrequiredLocal call identity. Requests use the session bound to the client token.
getClientToken() => Promise<string | ClientToken>requiredReturns a client token. Called again when the token expires or is refused.
baseUrlstringAPI origin.
Default
https://api.polymorfa.comdiagnosticsbooleanSends connection quality figures every 15 seconds and when a connection closes, and an error code when media fails. No personal data is sent.
Default
trueonError({ code, message }) => voidFailures that do not belong to one call.
unauthorizedmeans 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.
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 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 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 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 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 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.
<PolymorfaProvider tokenEndpoint="/api/polymorfa/token">
<CallButton to="+15551234567" />
</PolymorfaProvider>All 9 CallButton props, with types, defaults and a live preview, are on the CallButton 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 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.
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;<pmfa-call exclusive></pmfa-call>exclusiveBoolean attribute or propertyAnswering claims the call.
controllerCallsControllerCalls 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 reportaria-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.