Module 21 · Integrations

Lee en español: Módulo 21 · Integraciones.

Objective: connect the platform to your own systems without writing code: API keys for your scripts, webhooks that notify your CRM, the agent widget inside your CRM, and click-to-call on your website. Time: ~10 minutes · Prerequisites: access to the Security section in the sidebar. Every screen in this module lives there.

Each part ends with a link to the developer guide for whoever has to program the other side. As the administrator you decide what gets connected and who receives the credential; your technical team handles the how.

Two of these come switched off

Agent access to the widget and click-to-call are off by default and cannot be turned on from your account: the platform founder turns them on, customer by customer (in the flag catalog they are widget_auth_enabled and click_to_call_enabled, writable only by the founder). If you need them, ask your Dialer Digital contact before promising them to your team or your visitors.

1. API keys: create and revoke

API keys are for integrations — scripts and servers — that call the API. Each one is a full credential for your agency. The console itself does not sign in with a key: it uses your email and password, or your organization's SSO.

In Security, API keys section:

1. Type a Label that says what it is for (the on-screen example is "e.g. CRM integration").
2. Press Create key.
3. The notice "Copy this key now — it will not be shown again." appears. Press Copy, store the key in the secret manager of whoever will use it, and press Done.

The Keys table shows the label, status and creation date, with a summary like "N active · N total". To remove one, press Revoke on its row:

• Revoking is immediate and permanent.
• Keys are never deleted: they stay in the list, revoked, so old audit references keep resolving.
• Only the SHA-256 of each key is stored, so nobody can show it to you again. If it is lost, revoke it and create another.

One key per integration

Create a key with its own label for each system. If one is compromised you revoke only that one and leave the others running.

Technical detail: Authentication, section "Managing keys".

2. Webhooks: notify your CRM

An outbound webhook pushes each event to your own system the moment it happens, signed so your side can prove it came from us. In Security, the Webhooks for your CRM card has the Manage webhooks link (in the menu: Webhooks).

Register an endpoint

1. In Endpoint address type the address where your CRM listens (for example https://crm.ejemplo.com/hooks/dialerdigital). It must be https on the standard port 443 and resolve to a public host: anything internal is refused, and it is checked again at the moment of sending.
2. In Events to send pick at least one. The list is fixed. As the screen says, disposition.event carries name, disposition, debt_id and campaign_id; carrier.health_changed announces a state change (up, down or unknown) of a BYOC trunk; and anomaly.detected announces the moment an insights anomaly opens (resolution is not announced).
3. Press Register endpoint.
4. The signing secret appears: "Copy this signing secret now — it will never be shown again." Hand it to whoever programs your side, who uses it to verify every delivery. Press Done.

In the Endpoints table the status is Delivering or Disabled, and the secret only appears as "ends in …". Endpoints are never deleted: Disable keeps the record of what was subscribed and when, and Re-enable brings it back. If your server answers 410 Gone, we turn it off ourselves and the screen tells you so: fix the address and re-enable it. Edit changes the address (with the same checks as registering it).

Limit: 20 enabled endpoints per account. Only enabled ones count. If you already have 20, registering a new one — or pressing Re-enable on a disabled one — is refused (422, "the tenant has too many enabled webhook endpoints"): disable one you no longer use first. An account already above 20 keeps all it has and they keep receiving; only a new or re-enabled one is refused. You can register the same address twice. Technical basis: lib/dialer/webhooks.ex in core.

Rotate the secret

If the secret is lost or leaves the hands that should hold it, press Rotate secret and confirm with Rotate now. You get a new one, shown once. The old one keeps working during an overlap window (the screen says until when: "Rotated recently: the previous secret still works until …") so your CRM can switch over without dropping anything. The developer guide sets that window at 24 h by default.

Read the delivery history

Press Deliveries on an endpoint's row. You see, newest first, each send with its Event, Happened at, Response code and Result:

Result on screen	What it means
Not tried yet	Queued, not sent yet.
Retrying	The last attempt failed and another will follow. The screen counts "N attempts so far".
Delivered	Your server answered successfully.
Gave up	Attempts ran out and it is no longer retried.
Endpoint off	The endpoint was disabled.

For a given delivery, Re-send → Send again queues another attempt; it is unavailable while the endpoint is disabled (re-enable it first). Show older pages backwards. This record is never edited: it is what you show a CRM that says it was never called.

Who can register and change endpoints

A flag, webhook_admin_role_enforced, is off by default: while it is off, any console user can register or change an endpoint; once on, only the account_admin role can (a member gets 403). Turning it on is the founder's call, who measures the effect first. Reads and the delivery history stay open to any user of your account.

Technical detail: Outbound webhooks: the JSON envelope, how to verify the signature, the retry ladder and deduplication.

3. The widget inside your CRM

The agent widget is embedded in your own CRM so your agents can call without leaving it. Two control lists are involved, and they should not be confused:

• Where the widget may be shown: the allowed sites (this section).
• Who may sign into it: agent access (below).

Allowed sites

In the menu, Widget Embed (screen title: Allowed sites):

1. In Site origin type your CRM's site exactly as it appears in the address bar: scheme, host and port only, with no path. The on-screen example is https://crm.example.com.
2. Optionally add a Label (optional), such as "Sales CRM".
3. Press Add site. The screen confirms "Added — the widget may now be embedded on this site." and shows the exact form it was saved in: that is the form that counts.

In the Sites table, Disable stops the widget from being embedded on that site; Enable puts it back. Disabling does not sign anyone out or revoke anything. Sites are never deleted and the address cannot be edited: to change it, disable the old one and add the new one.

Agent access

In Security, Agent widget access sets each agent's own email and password (the Widget login column says whether they have one; Change password sets it). That way every call action is attributed to that person rather than to a shared key. Rotating or disabling the password ends the agent's live widget session immediately. Setting or removing a seat's password takes an administrator (or the agent, on their own seat): a member login on another agent's seat gets 403 role_forbidden. Seats are created beforehand, in the seat roster.

Saving a password does not switch access on

Widget access is off by default (widget_auth_enabled, which the founder turns on) and is not enabled in every environment. Where it is, a sign-in is refused unless the request comes from the widget's published host. Neither is changed from the allowed-sites list or from that screen, and the screen cannot confirm the state of either: check with us before promising an agent they will be able to sign in.

Widget tokens

At the bottom of the Allowed sites screen, Widget tokens lists the session each agent opens on signing in (agent, label, Pinned site, status live / expired / revoked, and when it Expires). Tokens are not issued from there: they are born when the agent signs in. If someone has to be removed, Revoke → Confirm revoke signs them out of the widget. Disabling a site does not revoke any token: the two are separate.

Technical detail: Agent widget (embed): the iframe, the postMessage bridge and the widget's security.

4. Click-to-call on your website

Click-to-call lets a visitor of your site ask to be called: you publish a call-request form on an allowed site, and each request is bound to the campaign, modes and limits you configure. In Security, the Click-to-call for your website card → Manage click-to-call sites.

Off by default

While click_to_call_enabled is off for your account —and it ships off— the two public routes of the form answer 404 and nothing is written. Requests that already exist are not touched: they are evidence. The founder turns it on; ask your contact before publishing anything.

Creating a site while it is off is refused too: the console shows "Click-to-call is not turned on for your account. Ask your account administrator to enable it." (the API answers 403 click_to_call_not_enabled) and no site is created. The next step is the same: ask your contact to turn it on.

Create a site

Under Create a click-to-call site:

1. Site label: how you will recognize it in the list.
2. Destination campaign: choose a campaign (required).
3. Call now and/or Schedule a call: tick at least one mode.
4. The limits: Account requests per day, Requests per number per day and Site requests per hour.
5. Visitor declaration: the exact text the visitor must acknowledge ("I acknowledge: …") before pressing Request a call. Changing it creates the next immutable version and its SHA-256 is recorded. While no text is configured the form stays closed ("Not configured — the frame stays closed").
6. Press Create site and key.

The Embed snippet appears. Copy it now with Copy snippet: the site's publishable key is shown once and cannot be recovered from the console. Hand it to whoever maintains your website.

Manage and revoke

The Click-to-call sites table shows the site, its modes, the declaration version and the status (Active or "Revoked" with a date). Configure changes the campaign, limits or declaration. Revoke → Confirm revoke kills the publishable key; existing request records remain as evidence.

Further down, Allowed embed origins is the same list as in section 3: the tenant's list controls which websites may frame the agent widget and this form. You can add an origin from there (Add origin) or open the full list with Manage the full origin list.

What the visitor sees

The visitor types their number in international format (for example +13125550100), chooses when to be called if there is more than one mode, acknowledges the declaration and presses Request a call. They get "Request received." — and the confirmation does not reveal whether the number belongs to a customer: receiving it does not guarantee a call will be placed; the platform applies its compliance gates and calling window afterwards.

Technical detail: Agent widget (embed). That guide states, as of this page, that the frame and its loading snippet are not released yet: read it before you set a date with your web team.

What to take away

• An API key is shown once; if it is lost, revoke it and create another.
• A webhook secret is also shown once; it is rotated with an overlap window, and the Deliveries history is your proof.
• Allowed sites decide where the widget is shown; agent access decides who signs in. They are different lists.
• Agent widget and click-to-call ship off: the founder turns them on, customer by customer.