Phone component

The Phone component adds a browser-based softphone to your application. Users can search contacts or enter a phone number, make and receive calls, mute their microphone, and transfer an active call. The component requires a voice-enabled account with an outbound phone number configured.

Installation

Mount the component in an iframe and grant the Surge embed origin access to the browser’s microphone:

<iframe
  id="surge-phone"
  title="Surge phone"
  src="https://embed.surge.app/phone?token={USER_JWT}"
  allow="microphone https://embed.surge.app"
></iframe>

The signed User JWT identifies the User making and receiving calls. See Embeddable UI components for how to generate one. The browser asks the User for microphone permission when the component first places or accepts a call.

Query parameters

Parameter	Required	Description
`token`	Yes	A signed JWT that identifies the current User.
`caller_id`	No	The Surge Phone Number ID (`pn_...`) or verified Caller ID (`vcid_...`) to show on outbound calls. Defaults to the account’s default phone number.
`phone_number_id`	No	A legacy parameter that selects the Surge Phone Number the call is associated with and applies that number’s outbound settings, including call recording. Defaults to the account’s default phone number.
`theme`	No	The component color theme: `light` (the default), `dark`, or `system`.
`ring`	No	Set to `false` to disable the ringtone for incoming calls. The ringtone is enabled by default.

For new integrations, use caller_id by itself. Set phone_number_id only when a verified Caller ID should use the call settings from a nondefault Surge Phone Number. When caller_id is a Surge Phone Number ID, phone_number_id must be omitted or set to the same ID.

Control the phone from your application

The component works as a standalone dialer, but the parent window can also control it with postMessage. Every command must include target: "surge-phone". For example, initiate a call with an E.164-formatted phone number:

const phone = document.getElementById("surge-phone");

phone.contentWindow.postMessage(
  {
    target: "surge-phone",
    type: "initiate-call",
    to: "+14155550123",
  },
  "https://embed.surge.app",
);

The available commands are:

Command	Additional fields	Description
`initiate-call`	`to`	Start an outbound call to an E.164-formatted phone number.
`end-call`	None	End the current call.
`mute-microphone`	None	Mute the current call.
`unmute-microphone`	None	Unmute the current call.
`transfer-call`	`to`	Transfer the active call to an E.164-formatted phone number.
`register`	None	Connect the phone so it can receive incoming calls.
`unregister`	None	Disconnect the phone from incoming calls.
`accept-call`	None	Accept the pending incoming call.
`reject-call`	None	Reject the pending incoming call.

Events

The Phone component emits postMessage events for call and registration state changes.

Event	When it fires
`registering`	The phone starts connecting for incoming calls.
`registered`	The phone is ready to receive incoming calls.
`register-error`	The phone could not connect for incoming calls.
`unregistering`	The phone starts disconnecting from incoming calls.
`unregistered`	The phone is no longer connected for incoming calls.
`incoming-call`	An incoming call arrives. The payload includes a `contact` object.
`call-started`	An outgoing or incoming call connects.
`call-ended`	The current call ends.
`call-error`	The component could not place a call.
`initiate-error`	An `initiate-call` command was missing a destination.
`transfer-succeeded`	The active call was transferred.
`transfer-error`	The component could not transfer the active call.

Listen only for messages from the Surge embed origin:

window.addEventListener("message", (event) => {
  if (event.origin !== "https://embed.surge.app") return;

  switch (event.data?.type) {
    case "incoming-call":
      console.log("Incoming call", event.data.contact);
      break;
    case "call-started":
      console.log("Call connected");
      break;
    case "call-ended":
      console.log("Call ended");
      break;
    case "call-error":
    case "transfer-error":
      console.error(event.data.error);
      break;
  }
});

Get started

Register your business

Sending messages

Receiving messages & webhooks

Phone numbers

Verifications

Channels roadmap

Embeddable UI components

Concepts

Phone component

Installation

Query parameters

Control the phone from your application

Events

​Installation

​Query parameters

​Control the phone from your application

​Events

Installation

Query parameters

Control the phone from your application

Events