Skip to content
Shortcut: /, ⌘K or Ctrl+K

Add calling to a web app

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

View as Markdown

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.

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:

ActionAllows
voip_placePlacing calls, inviting participants and connecting to calls you place
voip_answerAnswering, joining and declining calls, and connecting to calls you answer or join
voip_signalReceiving 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 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#

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>;

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.

Place a call#

TypeScript
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, 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.

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.

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#