# Embedded Dialer

> Add the Allo dialer inside your own app

You can embed your own Allo dialer directly inside your app. Your team makes and receives calls without leaving your product, and your app stays in sync with what happens on every call.

It works with a single iframe.

## How to connect

Add this iframe wherever you want the dialer to appear:

```html
<iframe
  src="https://web.withallo.com?variant=dialer"
  allow="microphone; autoplay"
  style="width: 376px; height: 640px; border: 0;"
></iframe>
```

Any website can embed the dialer. There is nothing to activate on Allo's side and no domain to send us. Your team signs in to Allo inside the dialer the first time.

The `allow="microphone"` attribute is required: the browser only grants microphone access to an iframe whose parent allows it. If your page is itself inside another iframe, every parent must pass the microphone permission down.

If your page sends a `Permissions-Policy` header, it must allow the microphone for your own page as well as for Allo:

```
Permissions-Policy: microphone=(self "https://web.withallo.com")
```

Listing only `https://web.withallo.com` blocks the microphone in Chrome without any prompt. The dialer then says the microphone is blocked, even though Chrome allows it for your site.

### How to sign in to the embedded dialer

Sign in with your email or phone number and the code Allo sends you. Google and Apple sign-in don't work inside the embedded dialer, because Google and Apple block their sign-in pages from loading inside another website. Use the embedded dialer in Chrome or Edge.

### What the embedded dialer includes

The embedded dialer places and receives calls. Your app can also queue contacts and start a calling session in the embedded dialer, see [Power dialing](#power-dialing).

## Events you can send

Control the dialer from your app:

| Event | Payload | What it does |
|-------|---------|--------------|
| `init` | None | Asks the dialer to send `ready` again, for example when your listener starts after the dialer loaded |
| `dial` | `{ phone_number }` | Opens the dialer with a phone number ready to call |
| `hangup` | `{ call_id }` | Ends the current call, or declines it while it rings |

`dial` fills in the number, and your teammate presses call. `hangup` ends the call right away. Pass the `call_id` you got from `outgoing_call` or `incoming_call`, so a late message never ends a different call.

## Events you receive

Stay in sync with what happens on each call:

| Event | Payload | When it happens |
|-------|---------|-----------------|
| `ready` | None | The dialer is loaded and ready |
| `login` | `{ user_id, team_id }` | A teammate signs in |
| `outgoing_call` | `{ to, call_id }` | An outbound call starts |
| `incoming_call` | `{ from, to, call_id }` | A call is ringing |
| `call_answered` | `{ call_id }` | The call is picked up |
| `call_ended` | `{ call_id, duration }` | The call ends. `duration` is the talk time in seconds, `0` if nobody answered |

The `call_id` identifies the call inside the embedded dialer only. The `call_id` is not the call `id` sent in [webhooks](/help/integrations/webhooks) or returned by the API. To match a dialer call with a webhook, compare the phone numbers and the time of the call.

## Power dialing

Power dialing lets your app send a list of contacts to the embedded dialer and start a calling session. The embedded dialer calls the contacts one after another and shows the session to your teammate. Your app receives an event at every step of every call, so it can open the right record the moment a call starts.

Power dialing uses the same queue as [Power Dialer](/help/features/power-dialer) in the Allo app. The contacts your app sends are added to your teammate's current Allo queue.

Every message uses the same envelope as the other events on this page: `{ source: "allo-host", type, payload }` from your app, `{ source: "allo-dialer", type, payload }` from the embedded dialer.

### The contact object

Your app describes each contact to call with a contact object:

| Field | Required | Description |
|-------|----------|-------------|
| `phone_number` | Yes | The number to call, in E.164 format, for example `+15551234567` |
| `name` | No | First name |
| `last_name` | No | Last name |
| `company` | No | Company name |
| `job_title` | No | Job title |
| `external_id` | No | Your own identifier for the contact, for example `person:123` |

The embedded dialer keeps the `external_id` in memory against the phone number and sends the `external_id` back in every event about that contact. Use the `external_id` to find the record in your app without matching phone numbers.

### Power dialing commands you can send

| Event | Payload | What it does |
|-------|---------|--------------|
| `power_dialer.queue` | `{ contacts, replace? }` | Adds the contacts to your teammate's current Allo queue. With `replace: true`, the queue is cleared first. The dialer answers `power_dialer.queued` |
| `power_dialer.start` | `{}` | Starts a session on the current queue. If the browser needs a click first, the dialer answers `power_dialer.start_blocked` and shows a Start button |
| `power_dialer.pause` | `{}` | Pauses the session |
| `power_dialer.resume` | `{}` | Resumes a paused session |
| `power_dialer.skip` | `{}` | Skips the current contact |
| `power_dialer.stop` | `{}` | Ends the session |
| `power_dialer.get_state` | `{}` | Asks for the current state. The dialer answers `power_dialer.state` |

### Power dialing events you receive

| Event | Payload | When it happens |
|-------|---------|-----------------|
| `power_dialer.queued` | `{ added, skipped, total }` | After `power_dialer.queue`. `skipped` lists each number that was not added, as `{ phone_number, reason }`. `total` is the size of the queue |
| `power_dialer.start_blocked` | `{ reason }` | The session could not start. See Why a session does not start, below |
| `power_dialer.session_started` | `{ session_id, total, line }` | The session starts. `line` is the Allo number the calls go out from, as `{ number, name }` |
| `power_dialer.call_started` | `{ session_id, index, total, call_id, contact }` | The dialer places the call, before it rings. `call_id` can be `null` at this point |
| `power_dialer.call_ringing` | Same as `call_started` | The call rings |
| `power_dialer.call_answered` | Same, with `call_id` | The contact picks up |
| `power_dialer.call_ended` | Same, plus `duration` and `result` | The call ends. `duration` is the talk time in seconds. `result` is `connected`, `no_answer`, `voicemail`, `skipped` or `failed` |
| `power_dialer.paused` | `{ session_id }` | The session is paused |
| `power_dialer.resumed` | `{ session_id }` | The session resumes |
| `power_dialer.session_ended` | `{ session_id, reason, stats }` | The session ends. `reason` is `completed`, `stopped` or `error` |
| `power_dialer.state` | `{ phase, session_id, index, total, current, queue }` | After `power_dialer.get_state`, and on every phase change. `phase` is `idle`, `countdown`, `dialing`, `paused` or `ended` |
| `power_dialer.error` | `{ code, message }` | Something went wrong |

In every `power_dialer.call_*` event, `contact` is the contact object your app queued, `external_id` included.

#### Payload examples

`power_dialer.queued`:

```json
{
  "source": "allo-dialer",
  "type": "power_dialer.queued",
  "payload": {
    "added": 2,
    "skipped": [],
    "total": 2
  }
}
```

`power_dialer.session_started`:

```json
{
  "source": "allo-dialer",
  "type": "power_dialer.session_started",
  "payload": {
    "session_id": "pds_8f2c1a",
    "total": 2,
    "line": { "number": "+15557654321", "name": "Sales line" }
  }
}
```

`power_dialer.call_started`:

```json
{
  "source": "allo-dialer",
  "type": "power_dialer.call_started",
  "payload": {
    "session_id": "pds_8f2c1a",
    "index": 0,
    "total": 2,
    "call_id": null,
    "contact": {
      "phone_number": "+15551234567",
      "name": "Jane",
      "last_name": "Smith",
      "company": "Smith Plumbing",
      "job_title": "Owner",
      "external_id": "person:123"
    }
  }
}
```

`power_dialer.call_ended`:

```json
{
  "source": "allo-dialer",
  "type": "power_dialer.call_ended",
  "payload": {
    "session_id": "pds_8f2c1a",
    "index": 0,
    "total": 2,
    "call_id": "c_41d9",
    "contact": { "phone_number": "+15551234567", "external_id": "person:123" },
    "duration": 94,
    "result": "connected"
  }
}
```

`power_dialer.session_ended`:

```json
{
  "source": "allo-dialer",
  "type": "power_dialer.session_ended",
  "payload": {
    "session_id": "pds_8f2c1a",
    "reason": "completed",
    "stats": { "dialed": 2, "connected": 1, "voicemail": 1, "no_answer": 0, "skipped": 0 }
  }
}
```

`power_dialer.state`:

```json
{
  "source": "allo-dialer",
  "type": "power_dialer.state",
  "payload": {
    "phase": "dialing",
    "session_id": "pds_8f2c1a",
    "index": 0,
    "total": 2,
    "current": { "phone_number": "+15551234567", "external_id": "person:123" },
    "queue": [
      { "phone_number": "+15551234567", "external_id": "person:123" },
      { "phone_number": "+15559876543", "external_id": "person:456" }
    ]
  }
}
```

The ids in these examples are illustrative. Do not rely on their format.

### How a power dialing session runs

1. Your app sends `power_dialer.queue` with the contacts. The dialer answers `power_dialer.queued`.
2. Your app sends `power_dialer.start`. The dialer answers `power_dialer.session_started`, or `power_dialer.start_blocked` if the session cannot start yet.
3. For each contact, your app receives `power_dialer.call_started`, `power_dialer.call_ringing`, `power_dialer.call_answered` if the contact picks up, then `power_dialer.call_ended`.
4. If your teammate pauses, your app receives `power_dialer.paused`, then `power_dialer.resumed`.
5. When the queue is done or the session is stopped, your app receives `power_dialer.session_ended` with the session stats.

The dialer also sends `power_dialer.state` on every phase change, so your app can mirror the session without tracking each event.

### Power dialing example

This example queues two contacts, starts a session, and opens the matching record in your app when each call starts:

```html
<iframe id="allo" src="https://web.withallo.com?variant=dialer" allow="microphone; autoplay"></iframe>

<script>
  const allo = document.getElementById("allo").contentWindow;
  const ALLO = "https://web.withallo.com";

  function send(type, payload = {}) {
    allo.postMessage({ source: "allo-host", type, payload }, ALLO);
  }

  // Queue the contacts, then start the session
  function startCalling() {
    send("power_dialer.queue", {
      replace: true,
      contacts: [
        { phone_number: "+15551234567", name: "Jane", last_name: "Smith", external_id: "person:123" },
        { phone_number: "+15559876543", name: "Sam", company: "Lee Electric", external_id: "person:456" },
      ],
    });
    send("power_dialer.start");
  }

  window.addEventListener("message", ({ origin, data }) => {
    if (origin !== ALLO || data?.source !== "allo-dialer") return;

    switch (data.type) {
      case "power_dialer.call_started":
        // Open the record in your app, for example /people/123
        openRecord(data.payload.contact.external_id);
        break;
      case "power_dialer.start_blocked":
        // "user_gesture_required": ask your teammate to click Start in the dialer
        showMessage(data.payload.reason);
        break;
      case "power_dialer.session_ended":
        console.log("Session done:", data.payload.stats);
        break;
    }
  });
</script>
```

`openRecord` and `showMessage` stand for your own code.

### Why a session does not start

Browsers only let a page use the microphone and play sound after the person has clicked inside it. The first `power_dialer.start` can therefore answer `power_dialer.start_blocked` with the reason `user_gesture_required`. The embedded dialer then shows a Start button, and the session starts when your teammate clicks it.

| `reason` | What it means |
|----------|---------------|
| `user_gesture_required` | The browser needs a click inside the dialer first. Your teammate clicks Start in the dialer |
| `no_line` | Your teammate has no Allo number to call from |
| `empty_queue` | The queue is empty. Send `power_dialer.queue` first |
| `not_entitled` | Your teammate does not have access to power dialing |

### Where to get the call summary and recording

The call summary, transcript and recording are not in the dialer events: Allo prepares them after the call ends. Your server receives them in the `call.completed` [webhook](/help/integrations/webhooks). As for the other events on this page, the `call_id` is not the call `id` of the webhook: compare the phone numbers and the time of the call.

## Example

```html
<iframe id="allo" src="https://web.withallo.com?variant=dialer" allow="microphone; autoplay"></iframe>

<script>
  const allo = document.getElementById("allo").contentWindow;
  const ALLO = "https://web.withallo.com";

  // Send a number to call
  allo.postMessage({ source: "allo-host", type: "dial", payload: { phone_number: "+15551234567" } }, ALLO);

  // End the call from your own button
  allo.postMessage({ source: "allo-host", type: "hangup", payload: { call_id: currentCallId } }, ALLO);

  // React to call events
  window.addEventListener("message", ({ origin, data }) => {
    if (origin !== ALLO || data?.source !== "allo-dialer") return;
    console.log("Allo event:", data.type, data.payload);
  });
</script>
```

## Need help?

<CardGroup cols={2}>
  <Card title="Contact support" icon="headset" href="/help/support/contact">
    Something not working in your embed? Our team can help
  </Card>
  <Card title="Webhooks" icon="bolt" href="/help/integrations/webhooks">
    Get server-side notifications for calls and messages
  </Card>
</CardGroup>
