> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surge.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone component

> Embed a browser-based phone for making, receiving, and transferring calls as the current User.

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:

```html theme={null}
<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](https://docs.surge.app/embeddable/index.md#authentication) 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:

```javascript theme={null}
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:

```javascript theme={null}
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;
  }
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.