Allo

Embedded Dialer

Add the Allo dialer inside your own app

Updated on

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:

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

Events you can send

Control the dialer from your app:

EventPayloadWhat it does
initNoneAsks 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:

EventPayloadWhen it happens
readyNoneThe 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 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 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:

FieldRequiredDescription
phone_numberYesThe number to call, in E.164 format, for example +15551234567
nameNoFirst name
last_nameNoLast name
companyNoCompany name
job_titleNoJob title
external_idNoYour 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

EventPayloadWhat 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

EventPayloadWhen 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_ringingSame as call_startedThe call rings
power_dialer.call_answeredSame, with call_idThe contact picks up
power_dialer.call_endedSame, plus duration and resultThe 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:

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

power_dialer.session_started:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

reasonWhat it means
user_gesture_requiredThe browser needs a click inside the dialer first. Your teammate clicks Start in the dialer
no_lineYour teammate has no Allo number to call from
empty_queueThe queue is empty. Send power_dialer.queue first
not_entitledYour 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. 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

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