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:
| 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 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:
| 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:
{
"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
- Your app sends
power_dialer.queuewith the contacts. The dialer answerspower_dialer.queued. - Your app sends
power_dialer.start. The dialer answerspower_dialer.session_started, orpower_dialer.start_blockedif the session cannot start yet. - For each contact, your app receives
power_dialer.call_started,power_dialer.call_ringing,power_dialer.call_answeredif the contact picks up, thenpower_dialer.call_ended. - If your teammate pauses, your app receives
power_dialer.paused, thenpower_dialer.resumed. - When the queue is done or the session is stopped, your app receives
power_dialer.session_endedwith 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.
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. 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?
Something not working in your embed? Our team can help
Get server-side notifications for calls and messages