Click2Call — embed Callston calling in your own platform

Click2Call lets the people who work in your CRM, helpdesk or back-office make and receive phone calls through Callston without leaving your pages. Two pieces work together:

• The Callston call window — a small, persistent window on the Callston origin that owns the microphone, the audio and the calls. Your employee opens it once ("Enable calls") and keeps it open while they browse your site. Navigating, reloading or closing your pages never interrupts a call.
• The widget SDK — one JavaScript file you include on every page. It shows call readiness, the current call (as far as your policy allows), a timer, incoming calls with Answer/Decline, mute, keypad and hang up. It never touches audio: every control is sent to the Callston server, which delivers it to the call window.

Outgoing calls are requested server-to-server by your backend. The phone number goes from your database to Callston directly; when the integration policy hides numbers, the employee's browser only ever sees an opaque call reference and the display name you chose.

Base URL of this installation: https://callston.com · SDK: https://callston.com/assets/js/click2call-sdk.js · OpenAPI: /developers/click2call/openapi.json

1. Concepts

2. Setting up an integration

1. In Callston open Click2Call (personal dashboard) or Business → Click2Call (owners/admins, or managers with the Configure Click2Call permission).
2. Create an integration. Copy the server key now — it is shown once. Store it in your backend's secret store.
3. Add the exact origins of the pages that will embed the widget, e.g. https://crm.example.com (scheme + host + port, no path). Requests from any other origin are refused. Lines that are not origins (a path, no scheme) are not saved — the page says which. While you build and test, you can tick Allow all origins (for testing): any site may then use the integration's widget (your backend still decides who gets a session, and each session works only on the origin it was made for); the integration shows a warning until you switch it off and list your exact origins. Frame-shell mode always needs the exact origin.
4. Choose the identifier mode (email or UUID). In UUID mode each member's stable Callston UUID is listed on the page; you can also map your own UUID per member.
5. Set the widget defaults, permissions (outgoing / incoming), caller ID, destination countries, concurrency and duration limits, and number visibility (show / hide / masked).

• Max concurrent calls counts all of the integration's agents together. Each agent has one call at a time, so a call center sets at least the number of agents who may be on a call at once. A request over the limit gets 429 concurrency_limit.
• New integrations start at the platform default (10). Owners can raise it up to the platform's hard cap (500 unless the admin changes it in Admin → Settings → Click2Call).
• The Twilio account adds its own limit: without an approved Business profile it carries only 2–3 calls at once. Numbers are hidden by the server: hidden numbers never reach the browser in JSON, HTML, events, tooltips or URLs.
• Caller ID — the number the customer sees. Numbers you bought and numbers you verified as your own both work.
• Automatic (businesses) works exactly like a call from the agent's dialer. The agent's department numbers take turns. Calls no department covers use the business default set under Projects & Departments → Outgoing caller ID: the first number, a rotation, or one chosen number. For a personal integration, Automatic is your first number.
• Rotate over all numbers gives every usable number a turn, one call after another.
• A specific number always uses that number. If it stops being usable (released, suspended, deactivated), Automatic is used instead.
• Number visibility hides the customer's number from agents in the widget, and from every call history. That covers the agent console, the dialer's last calls, the business call history, the wallboard and exports.
• The business owner and admins always see it. The platform admin does too.
• The owner can let a manager, department manager or agent see it with the permission See phone numbers a Click2Call integration hides (Team → ✏️).
• An agent's own visibility override on this page still applies to them in the widget.

1. Businesses: choose who is covered — everyone, selected members, or departments — and whether future members inherit automatically. Per-agent overrides and their effective policy are on the same page.

Rotating a key invalidates the old one immediately. Revoking the key stops your backend; revoking the integration also ends every widget session and call window at once (calls in progress end through the provider).

3. Your backend: sessions

Every page load re-authenticates: your page asks your backend, your backend checks who is logged in and asks Callston for a widget token for that employee.

POST https://callston.com/api/v1/click2call/sessions
Authorization: Bearer c2ck_…
Content-Type: application/json

{ "integration_id": "c2c_…", "agent": { "type": "email", "value": "[email protected]" }, "origin": "https://crm.example.com" }

Response 201:

{ "ok": true, "widget_token": "c2cw_…", "expires_at": 1727612345,
  "agent": { "name": "Dana", "identifier": "[email protected]" },
  "policy": { "outbound": true, "inbound": true, "number_visibility": "hide", "controls": ["mute","dtmf"], "widget": { … }, "max_call_seconds": 3600 },
  "engine": null }

Return the token (and, if you like, policy/engine) to the page. Errors: origin_not_allowed, agent_unknown, agent_ambiguous, agent_not_assigned, agent_disabled, identifier_mode, integration_disabled, platform_disabled.

The widget refreshes its token itself (POST /widget/refresh) before expiry and re-asks your session endpoint once if a token is rejected. Revocation, disabling or un-assigning an agent apply on the next request.

4. Your page: the SDK

<script src="https://callston.com/assets/js/click2call-sdk.js"></script>
<script>
  var widget = CallstonClick2Call.init({
    integrationId: 'c2c_…',
    sessionEndpoint: '/callston/session',        // your backend → returns {widget_token, expires_at, …}
    requestCallEndpoint: '/callston/call',       // your backend → forwards to Callston with the number
    mode: 'persistent-window',
    windowMode: 'tab',                           // optional: 'popup' (default), 'tab' or 'extension' — overrides the integration setting
    position: 'bottom-right',                    // optional visual overrides
    language: 'en'
  });
  document.getElementById('enable-calls').onclick = function () { widget.enableCalls(); }; // inside a click
  widget.on('statechange', function (s) { console.log(s.state, s.call); });
</script>

The SDK posts to sessionEndpoint and requestCallEndpoint with credentials: 'same-origin' and a JSON body; add your CSRF header with headers: { 'X-CSRF-Token': … } if your backend needs one.

Return Callston's answer unchanged from both endpoints — its HTTP status and JSON. The widget reads them: a refusal ({"ok": false, "error": "agent_offline"} with 409, for example) is shown to the agent at once; an accepted call (202) shows Requesting call… until the call window picks it up. An endpoint that always answers 200 "OK" hides Callston's refusals: the widget then waits, and after 30 s says The call did not start.

States: init, connecting, offline (no call window), enabling, ready, unavailable, no_mic, call, reconnecting, unauthorized, error. call.status follows the intent lifecycle: queued, claimed, dialing, ringing, connected, completed, rejected, busy, no_answer, canceled, failed, expired; incoming calls report incoming then connected.

Multipage sites include the snippet on every page (the widget re-attaches to the existing window through the server). SPAs call init() once and endSession() on logout. The widget is rendered in a closed Shadow DOM, is keyboard operable, announces status changes to screen readers and switches to RTL for Hebrew and Arabic.

Call window modes

The call window owns the microphone and the audio, so it must live somewhere that survives your page loads. Call window opens as (per integration) picks where:

All four use the same backend calls (sessions, calls, hangup) and the same widget. Only where the call engine runs changes.

Frame-shell mode: what you need to do

In frame-shell mode, the agent's browser tab shows a shell page from your site. The shell shows your real pages in a full-screen, same-origin frame and keeps the Callston call window in a small embedded panel. Clicking links, submitting forms and reloading pages inside the frame never touches the call. No popup, no extra tab, and no click is needed to enable calls.

1. Add a shell page to your site, on the same origin as your app, for example https://crm.example.com/callston-shell.html:

<!DOCTYPE html>
<html>
<head><meta charset="utf-8"><title>CRM</title></head>
<body>
<script src="https://callston.com/assets/js/click2call-sdk.js"></script>
<script>
  CallstonClick2Call.shell({
    integrationId: 'c2c_…',
    sessionEndpoint: '/callston/session',      // the same endpoints as init()
    requestCallEndpoint: '/callston/call',
    start: '/crm/'                             // first page to show; ?p=/some/page overrides it
    // headers: { 'X-CSRF-Token': … },  panelPosition: 'left' | 'right',  autoEnable: true
  });
</script>
</body>
</html>

2. Keep init() on your pages as it is. Inside the shell's frame, init() finds the shell and returns the shell's widget (widget.inShell === true): the same methods and events, one session, one widget UI (drawn by the shell, so it does not flicker on page loads). Listeners registered by a page are removed when that page unloads.

3. In Callston, set Call window opens as → Frame shell and enter the Shell page URL (/callston-shell.html or a full URL on the same origin). The shell page's origin must be in the integration's allowed origins; the Callston call window may then be framed by exactly those origins, and by nothing else.

4. Allow same-origin framing of your own pages. Your app pages are shown in a frame of your own shell, so they must not forbid that: use X-Frame-Options: SAMEORIGIN or Content-Security-Policy: frame-ancestors 'self' (not DENY / 'none'). If your pages have a CSP, it also needs frame-src https://callston.com on the shell page (for the call panel), plus the script-src / connect-src entries listed in Deployment notes.

What the shell does for you:

• Automatic entry: a page loaded outside the shell (a bookmark, a link from an email) whose widget sees Frame shell reloads itself inside the shell as shell?p=/that/page. Opt out with init({ shellRedirect: false }), or call CallstonClick2Call.enterShell('/callston-shell.html') yourself early in the page to skip the extra round trip. Only same-origin paths are accepted for p.
• Address bar and title follow the page in the frame (?p= is kept up to date), so reload, bookmarks and copy-link keep working. The browser's Back and Forward buttons move inside the frame.
• Links: same-origin links with target="_top" stay in the frame. Links to other sites open in a new tab (most sites refuse to be framed).
• Calls start without a click: the shell pairs its panel automatically. The panel opens by itself when the microphone needs the agent; the widget's Go to call window opens it too.
• Reloading or closing the shell tab itself ends the call's audio, so the browser asks for confirmation during a call.

Things to keep outside the shell: login pages that must be top-level (some OAuth/SSO providers refuse to be framed; send those to the top window and come back to the shell), payment pages of third parties, and pages that set top.location. A page that navigates window.top leaves the shell and ends the call's audio.

Browser extension mode

With Call window opens as → Browser extension, the call engine runs inside the Callston extension for Google Chrome and Microsoft Edge, in a hidden background document. There is no window or panel to keep open, calls survive every page load, and the agent answers from the extension's toolbar button or from a desktop notification.

• Your site: no change. enableCalls() (inside a click) opens a short-lived tab that hands its one-time launch ticket to the extension and closes itself. If the extension is not installed, that tab offers the install link and a Use this tab instead button, so calls always work.
• Agents: install the extension once from the link on https://callston.com/click2call/extension, allow the microphone on its setup page and pin its icon. The extension talks only to this Callston server.
• Platform admins publish the extension from Admin → Settings → Extensions (a package built for this server, a step-by-step store guide, and the store IDs that the server accepts).
• Security: the engine API accepts an extension origin (chrome-extension://<id>) only for the extension IDs of this installation. The extension stores its own engine credential in the browser profile, never in a URL, and receives the same projection as the window: hidden numbers stay hidden.

5. Your backend: requesting a call (hidden numbers)

POST https://callston.com/api/v1/click2call/calls
Authorization: Bearer c2ck_…
Idempotency-Key: crm-call-8842
Content-Type: application/json

{ "integration_id": "c2c_…",
  "agent": { "type": "email", "value": "[email protected]" },
  "phone_number": "+14155550101",
  "contact_reference": "crm-8842", "display_name": "Alice Johnson", "display_company": "Northwind",
  "metadata": { "ticket": 4411 } }

Response 202 Accepted — queued, not answered:

{ "ok": true, "request_id": "ci_…", "call_id": "ci_…", "status": "queued",
  "display": { "name": "Alice Johnson", "company": "Northwind", "number": null, "contact_reference": "crm-8842" },
  "expires_at": 1727612405, "server_time": 1727612345 }

What happens: Callston validates the integration, the agent (membership, assignment, enabled, outgoing allowed), the number (E.164, destination countries, do-not-call list), the account (status, funds, concurrency) and that the agent has a ready call window with a microphone; freezes the policy into an intent; the window claims it atomically and connects with nothing but the reference; the provider webhook consumes the intent once and dials the real destination. Double-clicks with the same Idempotency-Key return the same intent; the same key with a different body is rejected (409 idempotency_conflict). An intent that no window picks up within the expiry (default 60 s) becomes expired.

Errors (all { "ok": false, "error": "…", "message": "…" }): agent_offline (409, no live window), agent_not_ready (409, no microphone), agent_busy (409), outbound_not_allowed (403), invalid_phone_number (422), destination_not_allowed / destination_blocked (403), concurrency_limit (429), insufficient_balance (402), no_caller_id (422), idempotency_conflict (409).

Status and hangup:

GET  https://callston.com/api/v1/click2call/calls/{request_id}
POST https://callston.com/api/v1/click2call/calls/{request_id}/hangup

duration is computed from the authoritative answered timestamp and the server clock, never from a browser timer.

6. Incoming calls

Incoming calls follow the account's normal routing: number → IVR → department → queue for businesses; forwarding / dashboard ringing for personal accounts. An agent is routable through Click2Call when their integration and member are enabled, incoming is allowed, and their call window is live, registered, has a microphone and is set Available. The queue then rings the window (client:c2c_<engine>) with the existing ring strategy; busy, decline and no-answer follow the department's timeout, overflow, voicemail and callback rules. Membership is re-validated at accept time. One live window per member; a second window is refused while the first is on a call.

The window and the widget show the department, a safe caller label (a lead name when known) and the number according to the inbound visibility policy. Enabling incoming never enrolls the agent in campaign auto-dialing. Browsers cannot open the call window for an incoming call without a gesture: the agent enables calls once per browser session.

7. Lifecycle, reliability and billing

• One authoritative lifecycle on the server. The window reports what it sees; provider callbacks win for live calls.
• Heartbeats: the window every 4 s (2 s on a call), the widget every 5 s (1.5 s on a call, 0.7 s while a call is being set up or ended, slower when the tab is hidden), with exponential backoff and jitter on failures. Click2Call API requests never start a PHP session, and provider hangup / status requests time out after 8 s, so a slow provider cannot hold web workers.
• Latency: between heartbeats the window checks a tiny per-engine wake signal (every 1 s idle, 0.4 s on a call, 0.2 s for a few seconds after a control): a file read on the server with no database or session, authenticated by a per-engine key sent in a header. The wake answer also carries the latest controls (keypad, mute, hang up, answer, decline, availability), so the window runs them without waiting for its heartbeat; the heartbeat that follows acknowledges them and remains the authority. A waiting call is claimed inside the heartbeat. The page that opened the window (or the frame shell) also sends it an instant, data-free postMessage nudge. Keypad tones play at once in the widget, the window and the extension; the provider SDK's own delayed local tone is silenced. Widget controls (mute, availability) update the widget at once and are confirmed by the state poll. Measured in Chromium with 250 ms added to every server request (roughly shared hosting behind a CDN): widget keypad → call window ≈ 0.45 s median, mute and hang up ≈ 0.5 s. A missed heartbeat is not a hangup: a window is considered offline after 90 s and its legs are then ended deliberately.
• Closing your page never hangs up. Closing the call window with no call releases the engine at once; with a call, the browser asks for confirmation first, and the provider legs settle through the status callbacks.
• A stale "busy" never blocks an agent: before a call is refused as busy, every call the server still holds for the agent is checked against the provider's own call status and closed when it already ended there; presence left "on call" with nothing live anywhere is reset. A call the window lost but the provider still carries is shown in the widget (call.orphaned: true) with Hang up. Housekeeping runs the same checks on every cron pass.
• The call window keeps its heartbeat on schedule while hidden (background tab or covered window) with a worker clock, which browsers do not throttle.
• Hangup from either UI is authorized for the assigned agent even when the call row belongs to the business owner; it terminates the parent and child legs in the correct provider account. A provider error is never reported as a confirmed hangup (hangup_uncertain).
• Duration caps are enforced by the provider (timeLimit) from the platform cap, the integration cap and the affordable share of the wallet; concurrent calls each plan for their share.
• Billing and webhooks are idempotent; retries of the same provider request get the same answer.
• Housekeeping (cron): expired intents, lost windows, stale sessions, commands.

8. Security

• Three credentials with narrow scopes (server key / widget token / engine token). Browser-supplied identifiers are never authority.
• Exact-origin CORS with preflight for the widget API; CORS is not authorization — every request re-validates its token, and widget tokens cannot reach any other account API. Refusals (expired token, wrong origin, rate limit) carry the CORS header for known origins, so the widget can read and act on them. Allow all origins (for testing) answers the preflight for any origin, but a widget session is still created only by your backend with the server key and stays bound to one origin.
• The engine identity may only connect an authorized intent: a leg that omits or changes To, Biz, CallerId or the intent is refused before any legacy branch (fail closed). Provider signatures are verified against the account the intent belongs to.
• Hidden numbers are projected out of everything an agent or member without See phone numbers a Click2Call integration hides can reach: JSON, HTML, SDK events, notifications, call histories, exports, the wallboard and provider parameters. Searching a history for a hidden number finds nothing. Display labels are escaped.
• The platform admin's Click2Call log (Admin → Logs → Click2Call) always shows the full number of every requested call, and the caller ID it went out from.
• Launch tickets are single-use and fragment-conveyed; the window page sends no referrer and carries no analytics.
• Switching businesses in another tab never moves a call, credential or wallet: tenant, member, provider and billing owner are bound on the server at session creation.

Rate limits: 300 requests/min per IP and 600/min per integration for server-key endpoints; 600/min per IP for widget endpoints. Exceeding them returns 429 rate_limited with Retry-After.

9. Examples

cURL — request a call:

curl -X POST https://callston.com/api/v1/click2call/calls \
  -H "Authorization: Bearer $CALLSTON_SERVER_KEY" -H "Idempotency-Key: crm-8842-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{"integration_id":"c2c_…","agent":{"type":"email","value":"[email protected]"},"phone_number":"+14155550101","contact_reference":"crm-8842","display_name":"Alice Johnson"}'

PHP backend — session and call endpoints:

<?php
// /callston/session — the employee is already authenticated by your app
$employee = current_user();
$res = callston('POST', '/api/v1/click2call/sessions', [
    'integration_id' => CALLSTON_INTEGRATION_ID,
    'agent' => ['type' => 'email', 'value' => $employee->email],
    'origin' => 'https://crm.example.com',
]);
header('Content-Type: application/json');
echo json_encode(['widget_token' => $res['widget_token'] ?? null, 'expires_at' => $res['expires_at'] ?? null, 'error' => $res['error'] ?? null]);

// /callston/call — {contact_reference} from the page; the number stays on the server
$contact = contacts_find($_POST['contact_reference']);
$res = callston('POST', '/api/v1/click2call/calls', [
    'integration_id' => CALLSTON_INTEGRATION_ID,
    'agent' => ['type' => 'email', 'value' => $employee->email],
    'phone_number' => $contact->phone, 'contact_reference' => $contact->id, 'display_name' => $contact->name,
], ['Idempotency-Key' => 'crm-' . $contact->id . '-' . time()]);
echo json_encode($res);

function callston(string $method, string $path, array $body, array $headers = []): array {
    $ch = curl_init(CALLSTON_URL . $path);
    $h = ['Authorization: Bearer ' . CALLSTON_SERVER_KEY, 'Content-Type: application/json'];
    foreach ($headers as $k => $v) { $h[] = "$k: $v"; }
    curl_setopt_array($ch, [CURLOPT_CUSTOMREQUEST => $method, CURLOPT_HTTPHEADER => $h, CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POSTFIELDS => $method === 'POST' ? json_encode($body) : null, CURLOPT_TIMEOUT => 15]);
    return json_decode((string) curl_exec($ch), true) ?: ['ok' => false, 'error' => 'unreachable'];
}

Vanilla multipage install: include the two script tags in your shared layout so every page has the widget; put the "Enable calls" button anywhere (it can also be the widget's own button).

SPA (React/Vue/etc.): call init() once when the app mounts after login; keep the returned widget in app state; call endSession() on logout and detach() when unmounting a preview.

Incoming: nothing to integrate — configure inbound routing in Callston and let agents set themselves Available in the widget or the window.

10. Deployment notes

• HTTPS is required for microphone access (except localhost).
• Frame shell / extension: see Call window modes in section 4.
• Popup or tab: enableCalls() must be bound to a click. A tab (Call window opens as → New browser tab, or windowMode: 'tab') is never caught by popup blockers and is harder to close by mistake — agents can pin it. A popup stays small and on top. Users who block popups get an "Open in new tab" link either way.
• CSP on your pages must allow script-src from https://callston.com and connect-src to https://callston.com. The call window has its own CSP.
• Permissions-Policy: in popup, tab and extension modes the window is not part of your pages, so no allow="microphone" is needed there. In frame-shell mode the SDK creates the call panel with allow="microphone; autoplay" itself; your shell page must not deny microphone in its own Permissions-Policy header.
• Mobile: mobile browsers suspend background windows; Click2Call targets desktop browsers. Agents on phones should use the Callston app.
• Migrations: the Click2Call tables are created by the built-in migration on the first admin page view or with php cron/run.php. Rollback: disable Click2Call in Admin → Settings → Click2Call (every endpoint refuses immediately); tables can stay.

11. Troubleshooting

The widget shows the reason after Calls unavailable; your session endpoint receives the same code from POST /sessions.

12. Endpoint reference

Full schemas: the OpenAPI document.