Integration Examples (Build Your Own Integration)

Scope

This page contains complete, working integration examples that you can copy and adapt. It builds on the Integrations Framework page, which describes each hook in detail; here the focus is on the handful of patterns that almost every real integration turns out to be a variation of.

All names, URLs, tokens, client IDs and field IDs on this page are fictional. Replace them with the values from the system you are integrating with.

Pattern	Example	Credentials live at	Hooks
API key, screen pop while ringing	AcmeCRM	Tenant	`onagent`
Per-user OAuth, live call state	Zenith Desk	User	`onfrontend`, `onagent`
Ticket or activity written after the call	Beacon Support	Tenant	`oncdr`
Tenant OAuth with admin consent	Northwind Cloud	Tenant	`onfrontend`
External application starts calls	Click to call	Tenant	`onhttp`
Directory sync, no calls involved	Directory sync	Tenant	`onfrontend`

No packaging required

An integration is not a file bundle you upload. You create it on the system-level Integrations page, give it a display name and an identifier, then paste each part into the matching text field (tenant HTML / CSS / JavaScript, user HTML / CSS / JavaScript, backend JavaScript). Leave the fields you do not need empty.

Before you start

Three decisions shape the code more than anything else.

1. The identifier. Lower-case alphanumeric, unique on the system, e.g. acmecrm. It appears in the REST URL the front end posts to (?identifier=acmecrm) and it namespaces every stored setting. Changing it later orphans the data, so choose it once.

2. Where the credentials live. Tenant settings are entered once by the tenant administrator and shared by the whole tenant — right for a service API key. User settings are entered by each extension in the user portal — right when every agent has their own login in the target system, which is nearly always the case with OAuth.

3. Which events you need.

Inbound call arrives
        │
        ├─ onagent  state = "ringing"      → look up the caller, show a screen pop
        ├─ onagent  state = "connected"    → the agent answered
        ├─ onagent  state = "terminated"   → duration is known
        │
        └─ oncdr                           → complete record: every leg, trunk,
                                             recording, CMC, comment, rating

Use onagent for anything the agent must see during the call, and oncdr for anything you write after it. oncdr fires once and is the only hook with the full picture, which makes it the better choice for logging; onagent fires repeatedly and is the only one early enough for a screen pop.

Three things that will bite you

Timestamp units are not consistent — and not even consistent within oncdr. oncdr timestamps (start, connect, end, and the same fields on trunk and extension legs) are in seconds; onagent timestamps are in milliseconds. But durationtalk on a state leg is in milliseconds even though the timestamps beside it are in seconds. Getting this wrong by a factor of 1000 is silent — the record still writes, the number is just absurd.

// Verified on 70.6, same call:
//   trunk leg  connect = 1789362030.818482   end = 1789362034.306992   -> 3.4885 s
//   state leg  durationtalk = 3489                                     -> 3489 ms

// Accepts either unit and returns milliseconds:
function toMillis (t) {
  if (!t) return 0;
  return t > 1e12 ? t : t * 1000;
}

// durationtalk is already milliseconds - convert unconditionally:
var talkSeconds = Math.round((sleg.durationtalk || 0) / 1000);

Do not write a heuristic such as if (durationtalk > 1000) durationtalk /= 1000. It looks defensive and is wrong: an 800 ms call passes the test untouched and gets logged as 800 seconds.

Verify call direction on your own system before you rely on it. Several integrations have been caught out by event.inbound here. Log one inbound and one outbound test call at trace level 9 and read what your version actually reports:

console.trace('CRM', 9, event.domain.address, 'inbound=' + event.inbound +
  ' caller=' + event.caller.number + ' agent=' + event.agent.number);

In oncdr the direction is explicit, but only on the trunk and extension legs — they carry 'I' for inbound and 'O' for outbound. State legs do not carry a usable direction. On 70.6, an outbound call placed by an agent who is logged into a queue produces a state leg of type acd with no direction of its own; the 'O' is on the trunk leg. Code that tests states[i].direction === 'O' silently never fires and logs every such call as inbound, with the agent's own extension as the customer.

// Check the state leg first, then fall back to the trunk leg.
function legIsOutbound (sleg, tleg) {
  if (sleg.type === 'extcall') return true;
  if (sleg.type !== 'acd' && sleg.type !== 'hunt') return false;
  if (sleg.direction === 'O') return true;              // some builds
  if (tleg && tleg.direction === 'O') return true;      // 70.6
  return false;
}

A SIP response code does not tell you whether the call was answered. This is the one that produces the most wrong data, because the resulting record looks entirely plausible. Two real 70.6 CDRs:

Call	Trunk `code`	Trunk `connect`	Talk time	Actually
Outbound 504 → 0433337285	`487`	non-zero	3489 ms	answered
Inbound 0433337285 → 316	`486`	non-zero	14085 ms	answered

487 is Request Terminated and 486 is Busy Here, yet both calls connected and carried audio. The codes belong to a forked or cancelled branch of the call, not to the branch that answered.

Decide answered from talk time, and use the SIP code only to classify why an unanswered call failed:

function legAnswered (sleg) {
  return !!(sleg && sleg.durationtalk > 0);     // or, on a trunk/extension leg: connect > 0
}

function legOutcome (sleg, tleg) {
  if (legAnswered(sleg)) return 'Connected';
  var code = (tleg && tleg.code) || (sleg && sleg.code) || 0;
  if (code === 486) return 'Busy';
  if (code === 404) return 'Wrong Number';
  return 'No Answer';                            // 487, 603, 480, or no code at all
}

The three leg arrays in a CDR

A CDR carries up to three parallel arrays. They describe the same call from different angles and they are not the same length or in the same order. Which one you want depends on the question.

Array	One entry per	Use it to answer
`trunklegs`	external leg over a trunk	Was this call external at all? Which way did it go?
`extensionlegs`	extension the call touched	Which extension actually handled it, after transfers?
`states`	PBX object the call passed through	Did it hit an auto-attendant, a queue, a mailbox?

trunklegs[] — direction ('I'/'O'), code (final SIP status, see the warning above), start / connect / end (seconds), extension, remoteparty, localparty, trunk-name.

extensionlegs[] — direction, extension, redirect (a SIP contact whose display name is the queue or ring group), start / connect / end (seconds).

states[] — type (extcall, acd, hunt, attendant, mailbox), durationtalk (milliseconds), code, start (seconds), extension, account.

Three rules follow from this.

An empty trunklegs means the call never left the PBX. This is the cheapest and most reliable internal-call test in oncdr — the equivalent of the Account.get(domain, number, '*') test you use in onagent. Guard on it first, before any lookup:

function oncdr (cdr) {
  // Extension-to-extension calls have no trunk leg. Without this guard the "customer"
  // ends up being the calling extension, and most CRMs will happily create a contact
  // named after it.
  if (!cdr.trunklegs || !cdr.trunklegs.length) return;
  ...
}

Never pair the arrays by index. An attendant-to-queue call has two state legs riding one trunk leg, so states[1] has no trunklegs[1]. Two failure modes follow, and integrations have shipped with both:

// WRONG - drops every state past the shortest array. An attendant -> queue call
// loses the queue leg entirely, which is usually the one that answered.
for (var j = 0; j < Math.min(tlegs.length, slegs.length); j++) { ... }

// WRONG in the other direction - throws when tlegs is shorter.
for (var j = 0; j < slegs.length; j++) { var tleg = tlegs[j]; ...tleg.code... }

// Correct - iterate the states, pair where possible, fall back to the last trunk leg.
function trunkLegFor (tlegs, j) {
  if (!tlegs || !tlegs.length) return null;
  return j < tlegs.length ? tlegs[j] : tlegs[tlegs.length - 1];
}

for (var j = 0; j < slegs.length; j++) {
  var tleg = trunkLegFor(tlegs, j);
  ...
}

One call is one CRM record, not one record per leg. A call that hits the auto-attendant and then a queue produces two state legs, both with talk time. Logging both gives the customer two activities for one conversation. Collect candidates, then pick one:

// Priority: last answered leg with a resolvable owner -> last leg with an owner
//        -> last answered leg -> last leg.
function selectCallLeg (calls) {
  if (calls.length <= 1) return calls;
  var answeredWithOwner = null, withOwner = null, answeredAny = null;
  for (var i = 0; i < calls.length; i++) {
    var k = calls[i];
    if (k.answered && k.ownerEmail) answeredWithOwner = k;
    if (k.ownerEmail) withOwner = k;
    if (k.answered) answeredAny = k;
  }
  return [ answeredWithOwner || withOwner || answeredAny || calls[calls.length - 1] ];
}

Pattern 1: AcmeCRM — tenant API key and screen pop

The tenant administrator enters a URL and an API key once. Every extension in the tenant then gets a contact card when a known number calls.

Fictional API:

Purpose	Request
Find a contact by phone	`GET /api/v2/contacts?phone=%2B15105550142`
Authentication	`Authorization: Bearer ak_test_00000000000000000000`

Tenant HTML

The tenant interface uses Bootstrap 3. Address fields by name rather than id — several integrations share one page and id values collide.

<!-- AcmeCRM -->
<div class="row">
  <div class="form-group has-feedback">
    <label class="col-sm-6 control-label">AcmeCRM API URL</label>
    <div class="col-sm-6">
      <input class="form-control" type="text" name="acme_url"
             placeholder="https://api.acmecrm.example">
      <span class="glyphicon form-control-feedback" aria-hidden="true"></span>
    </div>
  </div>
</div>

<div class="row">
  <div class="form-group has-feedback">
    <label class="col-sm-6 control-label">AcmeCRM API Key</label>
    <div class="col-sm-6">
      <input class="form-control" type="password" name="acme_api_key"
             placeholder="ak_test_00000000000000000000">
      <span class="glyphicon form-control-feedback" aria-hidden="true"></span>
    </div>
  </div>
</div>

Tenant JavaScript

'use strict';

// Fill the form from the stored settings:
export const load = (form, data) => {
  const d = data || {};
  form.querySelector('[name="acme_url"]').value = d.acme_url || '';
  // Secrets are never sent back to the browser - clear the field:
  form.querySelector('[name="acme_api_key"]').value = '';
}

// First element: public settings. Second element: the secret.
export const save = (form) => {
  const result = [{
    acme_url: form.querySelector('[name="acme_url"]').value.replace(/\/+$/, '')
  }];
  const key = form.querySelector('[name="acme_api_key"]').value;
  key && result.push(key);      // only when the administrator typed something
  return result;
}

How the secret is stored

The second array element is a plain string, and there is one secret slot per level — one for the tenant, one for each user. The backend reads it with an empty name:

var apiKey = loadIntr(domain, '', '', true);      // tenant secret
var userKey = loadIntr(domain, user, '', true);   // that user's secret

If you need more than one secret, pack them into a single string and split it in the backend, for example email + ':' + token. Do not put passwords in the public object to work around the limit — public settings are readable from the tenant interface.

Guarding the push with key && is what makes "leave blank to keep the current key" work. Without it, every save with an empty field wipes the stored credential.

Backend JavaScript

The backend runs on the PBX, not in a browser: ES5 only, no fetch, no async/await, no DOM. HTTP goes through system.http, which is callback-based.

//
// AcmeCRM integration - example code
//

'use strict';

var PATH_CONTACTS = '/api/v2/contacts';

// Set this to the country code of your dial plan, or leave it empty to disable
// national-to-E.164 expansion entirely. See the note below.
var DEFAULT_COUNTRY_CODE = '';

function AcmeCrm () {

  // Read what the tenant administrator entered:
  this.init = function (domain) {
    this.domain = domain;
    this.url = (loadIntr(domain, '', 'acme_url', false) || '').replace(/\/+$/, '');
    this.key = loadIntr(domain, '', '', true);
    if (!this.url || !this.key) {
      console.trace('CRM', 4, domain, 'AcmeCRM: URL or API key missing, integration is idle');
      return false;
    }
    return true;
  };

  // One place for every request, so the credential header is never forgotten:
  this.send = function (method, path, body, callback) {
    system.http({
      method: method,
      url: this.url + path,
      header: [
        { name: 'Authorization', value: 'Bearer ' + this.key, secret: true },
        { name: 'Content-Type', value: 'application/json' }
      ],
      body: body,
      callback: callback
    });
  };

  // CRMs usually store E.164 - make the PBX number match.
  this.e164 = function (number) {
    var n = String(number || '').replace(/[^0-9+]/g, '');
    if (n.substr(0, 2) === '00') return '+' + n.substr(2);
    if (n.substr(0, 1) === '+') return n;
    // Only expand when a country code has been configured. Blindly prefixing one
    // corrupts every number that is not from that country: an Australian
    // 0433337285 becomes +10433337285 and matches nothing.
    if (DEFAULT_COUNTRY_CODE && n.substr(0, 1) === '0') {
      return '+' + DEFAULT_COUNTRY_CODE + n.substr(1);
    }
    return n;
  };

  this.screenPop = function (domain, callid, number) {
    var cmd = PATH_CONTACTS + '?phone=' + encodeURIComponent(this.e164(number));
    this.send('GET', cmd, '', function (code, response, headers) {
      if (code !== 200 || !response) {
        console.trace('CRM', 7, domain, 'AcmeCRM: contact lookup failed, code ' + code);
        return;
      }
      var d = JSON.parse(response || '{}');
      if (!d.contacts || !d.contacts.length) {
        console.trace('CRM', 9, domain, 'AcmeCRM: no contact for ' + number);
        return;
      }
      var c = d.contacts[0];
      system.setCallInfo(callid, {
        action: 'crmcontact',
        type: 'AcmeCRM',
        name: c.first_name + ' ' + c.last_name,
        url: 'https://app.acmecrm.example/contacts/' + c.id
      });
      console.trace('CRM', 9, domain, 'AcmeCRM: screen pop for ' + c.first_name);
    });
  };
}

// One instance per tenant, cached in memory:
var objs = {};

function instance (domain) {
  if (!(domain in objs)) {
    var o = new AcmeCrm();
    objs[domain] = o.init(domain) ? o : null;
  }
  return objs[domain];
}

function onagent (event) {
  if (event.state !== 'ringing') return;

  var crm = instance(event.domain.address);
  if (!crm) return;

  // The external party: caller on inbound, callee on outbound.
  // Confirm which way round event.inbound reports on your version - see "Before you start".
  var number = event.inbound ? event.caller.number : event.callee.number;
  if (!number) return;

  // Internal calls and star codes are never CRM contacts:
  if (Account.get(event.domain.id, number, '*')) return;
  if (number.substr(0, 1) === '*') return;

  crm.screenPop(event.domain.address, event.callid, number);
}

// Warm the cache for tenants that are already configured:
var domains = tables['domains'].search();
for (var i = 0; i < domains.length; i++) instance(domains[i]);

Number normalization is dial-plan specific

The e164 helper above is deliberately conservative: it converts an international prefix, passes through anything already in E.164, and only expands a national number when you have set DEFAULT_COUNTRY_CODE. Earlier versions of this example hard-coded +1 for any ten-digit number, which quietly corrupts every non-NANP deployment.

If the target API allows it, searching on the last seven to nine digits is more robust than trying to reconstruct E.164 on both sides.

The screen pop message

system.setCallInfo(callid, msg) attaches information to a live call. With action: 'crmcontact' the user portal and the apps render a clickable contact card:

{
  action: 'crmcontact',                                    // required
  type: 'AcmeCRM',                                         // shown as the source
  name: 'Dana Whitfield',                                  // shown as the contact name
  url: 'https://app.acmecrm.example/contacts/c_10427'      // opened when clicked
}

Send it on ringing, not on connected, so the agent knows who is calling before answering.

Pattern 2: Zenith Desk — per-user OAuth

When each agent has their own account in the target system, credentials belong at the user level and the agent authorizes the connection themselves. The PBX stores and refreshes the tokens through system.getOAuthToken.

Fictional service:

Setting	Value
Authorization URL	`https://auth.zenithdesk.example/oauth2/authorize`
Token URL	`https://auth.zenithdesk.example/oauth2/token`
API base	`https://api.zenithdesk.example`
Client ID	`zd-client-000000`
Client secret	`zd-secret-0000000000000000`

Agent clicks "Connect" in the user portal
User JS   → POST /rest/user/<ext>@<tenant>/integrations?identifier=zenith  { "info": true }
Backend   → onfrontend() replies with auth_url + client_id
User JS   opens the vendor's consent screen in a pop-up
Vendor    redirects back with ?code=...
Relay     → POST ...?identifier=zenith  { "code": "...", "url": "<redirect_uri>" }
Backend   → system.getOAuthToken({ obtainToken: true, ... }) exchanges the code
Backend   → system.updateOAuthSetting() marks the user as connected
User JS   polls the settings and turns the status icon green

User HTML

The user portal does not include Bootstrap or jQuery. It uses the pbx- web components.

<!-- Zenith Desk -->
<div class="grid">
  <pbx-label>Status</pbx-label>
  <pbx-icon name="crm-status" icon="fa-xmark"></pbx-icon>

  <pbx-label>Connection</pbx-label>
  <div>
    <pbx-button name="crm-auth-code" appearance="contained"
                icon="fa-regular fa-link">Connect</pbx-button>
    <pbx-button name="crm-disable" appearance="outlined"
                icon="fa-regular fa-link-slash">Disconnect</pbx-button>
  </div>
</div>

User CSS

div.grid {
  display: grid;
  grid-template-columns: 1fr 1fr;
  column-gap: 0.5em;
  row-gap: 0.5em;
  justify-items: stretch;
  align-items: center;
}

User JavaScript

This runs in a modern browser, so modules, fetch and async/await are all available. There is nothing for save to do — the backend owns the tokens — but the export must still exist.

import { api } from '/modules/api.js?v=[[version]]'
import { domcontrol } from '/tools/domcontrol.js?v=[[version]]'
import { localSettings } from '/tools/localsettings.js?v=[[version]]'

const IDENTIFIER = 'zenith';

export const load = (form, data) => {
  domcontrol.click(form.querySelector('[name="crm-auth-code"]'), () => crmAuth(form));
  domcontrol.click(form.querySelector('[name="crm-disable"]'), () => crmDisable(form));
  crmStatus(form);
}

// Nothing to save: the backend stores the tokens.
export const save = (form) => {
  return {};
}

// Post to our own backend - onfrontend() receives this:
const post = (payload) => {
  const url = '/rest/user/' + encodeURIComponent(localSettings.getUnDn()) +
              '/integrations?identifier=' + IDENTIFIER;
  return fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json; charset=utf-8' },
    body: JSON.stringify(payload)
  });
}

// Green check when the PBX holds a token for this user:
const crmStatus = async (form) => {
  const s = await api.getAllSettings(true);
  const status = form.querySelector('[name="crm-status"]');
  const connected = s.oauthlist && s.oauthlist[IDENTIFIER];
  status.setAttribute('icon', connected ? 'fa-check' : 'fa-xmark');
  status.style.color = connected ? 'green' : 'red';
}

const crmAuth = async (form) => {
  const response = await post({ info: 'true' });
  const info = await response.json();
  if (!info || !info.auth_url || !info.client_id) {
    console.log('Zenith Desk: no auth_url or client_id configured');
    return;
  }

  // The redirect URI registered with the vendor is fixed, so the pop-up lands on a relay page
  // that forwards the code to this PBX. The PBX address travels in the state parameter.
  const relay = 'https://portal.vodia.com/en/oauthredir';
  const back = `${window.location.protocol}//${window.location.host}/crm_token.htm`;
  const state = [ localSettings.getDn(), localSettings.getUsername(), IDENTIFIER, back ].join(':');

  const requrl = `${info.auth_url}/oauth2/authorize` +
    `?response_type=code` +
    `&access_type=offline` +
    `&client_id=${encodeURIComponent(info.client_id)}` +
    `&scope=${encodeURIComponent('contacts.read activities.write')}` +
    `&redirect_uri=${encodeURIComponent(relay)}` +
    `&state=${encodeURIComponent(state)}`;

  const win = window.open(requrl, 'zenithauth', 'width=800, height=600');

  const refresh = () => {
    if (win && win.closed) setTimeout(() => crmStatus(form), 3000);
    else setTimeout(refresh, 3000);
  };
  refresh();
}

const crmDisable = async (form) => {
  await post({ disable: 'true' });
  setTimeout(() => crmStatus(form), 3000);
}

Two easy mistakes in this file

Close the fetch( call around the whole URL. A stray parenthesis such as fetch("/rest/user/" + localSettings.getUnDn()) + "/integrations..." closes the call early and posts to the wrong path — and it is valid JavaScript, so nothing complains. Also run the extension identity through encodeURIComponent, because 41@tenant.example contains characters that must be escaped.

Ask for offline access (access_type=offline, or the vendor's equivalent scope) during authorization. Without a refresh token the integration works for an hour and then quietly stops.

Backend JavaScript

//
// Zenith Desk integration - example code
//

'use strict';

var VENDOR = 'ZenithDesk';
var AUTH_URL = 'https://auth.zenithdesk.example';
var TOKEN_URL = 'https://auth.zenithdesk.example/oauth2/token';

// System-level settings are a good place for credentials shared by every tenant:
var CLIENT_ID = system.setting('zenith_client_id') || 'zd-client-000000';
var CLIENT_SECRET = system.setting('zenith_client_secret') || 'zd-secret-0000000000000000';

function ZenithDesk () {

  // Every request carries the individual user's token. The tenant is passed in rather than
  // looked up from the user ID - see the note on table access in the reference section.
  this.sendCmd = function (method, command, domain, user, body, callback) {
    system.getOAuthToken({ vendor: VENDOR, user: user }).then(function (result) {
      if (!result || !('access_token' in result)) {
        console.trace('CRM', 4, domain, 'Zenith Desk: no token for ' +
          Account.get(domain, user, 'alias-name') + ', the user must connect first');
        return;
      }
      // Some vendors return extra fields alongside the token - for example a per-account API
      // host. Read them from the result rather than hard-coding one base URL.
      var base = result.api_domain || 'https://api.zenithdesk.example';
      system.http({
        method: method,
        url: base + command,
        header: [
          { name: 'Authorization', value: 'Bearer ' + result.access_token, secret: true },
          { name: 'Content-Type', value: 'application/json' }
        ],
        body: body,
        callback: callback
      });
    });
  };

  this.screenPop = function (domain, user, callid, number) {
    var cmd = '/v1/contacts?filter[phone]=' + encodeURIComponent(number);
    this.sendCmd('GET', cmd, domain, user, '', function (code, response) {
      if (code !== 200 || !response) return;
      var d = JSON.parse(response || '{}');
      if (!d.data || !d.data.length) {
        console.trace('CRM', 9, domain, 'Zenith Desk: no contact for ' + number);
        return;
      }
      var c = d.data[0];
      system.setCallInfo(callid, {
        action: 'crmcontact',
        type: 'Zenith Desk',
        name: c.name,
        url: 'https://app.zenithdesk.example/contacts/' + c.id
      });
    });
  };

  // Some systems want to follow the call live, not just receive a summary afterwards.
  // 'state' is one of ringing / answered / ended.
  this.callState = function (domain, user, callid, from, to, state, startMs, duration) {
    var body = JSON.stringify({
      id: callid,
      state: state,
      from: from,
      to: to,
      started_at: new Date(startMs).toISOString(),
      duration_seconds: duration || 0
    });
    this.sendCmd('POST', '/v1/calls/notify', domain, user, body, function (code, response) {
      if (code !== 200 && code !== 201) {
        console.trace('CRM', 7, domain, 'Zenith Desk: call notify failed, code ' + code);
      }
    });
  };

  this.disable = function (user, domain) {
    console.trace('CRM', 9, domain, 'Zenith Desk: removing token for ' +
      Account.get(domain, user, 'alias-name'));
    system.updateOAuthSetting(VENDOR, user, false, true);
  };
}

var objs = {};

//
// Called for POST requests the user portal sends to
//   /rest/user/<ext>@<tenant>/integrations?identifier=zenith
//
function onfrontend (data, callback) {
  var domain = data.domain;
  var user = data.user;
  var zd = objs[domain] || new ZenithDesk();
  var body = JSON.parse(data.body || '{}');

  // Step 3: tell the front end where to send the browser.
  if (body.info === 'true') {
    callback(200, 'Ok', 'application/json',
      JSON.stringify({ auth_url: AUTH_URL, client_id: CLIENT_ID }));
    return;
  }

  // The agent disconnected the integration.
  if (body.disable === 'true') {
    zd.disable(user, domain);
    saveIntr(domain, '', 'zenith_enabled', '', false);
    callback(200, 'Ok', 'application/json', '{"result":true}');
    return;
  }

  // Step 7: exchange the code for tokens. The PBX stores and refreshes them from here on.
  var arg = {
    vendor: VENDOR,
    user: user,
    domain: domain,
    clientId: CLIENT_ID,
    clientSecret: CLIENT_SECRET,
    redirectUri: body.url,
    server: TOKEN_URL,
    code: body.code,
    obtainToken: true,
    inBody: true,     // false sends the credentials as an Authorization header instead
    authorization: 'Basic ' + toBase64String(CLIENT_ID + ':' + CLIENT_SECRET)
  };

  system.getOAuthToken(arg).then(function (result) {
    if (result) {
      system.updateOAuthSetting(VENDOR, user, true);
      objs[domain] = zd;
      saveIntr(domain, '', 'zenith_enabled', 'true', false);
      console.trace('CRM', 9, domain, 'Zenith Desk: token obtained');
    } else {
      console.trace('CRM', 4, domain, 'Zenith Desk: token exchange failed');
    }
  });

  callback(200, 'Ok', 'application/json', '{"result":true}');
}

var STATES = { ringing: 'ringing', connected: 'answered', terminated: 'ended' };

function onagent (event) {
  var state = STATES[event.state];
  if (!state) return;

  var domain = event.domain.address;
  var zd = objs[domain];
  if (!zd) return;

  var number = event.inbound ? event.caller.number : event.callee.number;
  if (!number) return;
  if (Account.get(event.domain.id, number, '*')) return;    // internal
  if (number.substr(0, 1) === '*') return;                  // star code

  if (state === 'ringing') {
    zd.screenPop(domain, event.agent.id, event.callid, number);
  }

  var from = event.inbound ? number : event.agent.number;
  var to = event.inbound ? event.agent.number : number;
  var startMs = toMillis(event.timestamps[event.state]);
  var duration = 0;

  if (state === 'ended') {
    var c = toMillis(event.timestamps['connected']);
    var e = toMillis(event.timestamps['terminated']);
    duration = (c && e && e > c) ? Math.floor((e - c) / 1000) : 0;
  }

  zd.callState(domain, event.agent.id, event.callid, from, to, state, startMs, duration);
}

function toMillis (t) {
  if (!t) return 0;
  return t > 1e12 ? t : t * 1000;
}

var domains = tables['domains'].search();
for (var i = 0; i < domains.length; i++) {
  if (loadIntr(domains[i], '', 'zenith_enabled', false) === 'true') {
    objs[domains[i]] = new ZenithDesk();
  }
}

Pattern 3: Beacon Support — tickets from the CDR

A helpdesk integration. When an inbound call to a queue ends, find the customer, attach the call to their most recent ticket, and open a new one if there is none. This is the pattern to copy whenever you write after the call rather than during it.

The interesting work is not the HTTP — it is extracting sensible values out of the CDR.

Fictional API, using basic authentication with an agent e-mail and an API token:

Purpose	Request
Find a user by phone	`GET /api/v2/search?query=type:user phone:15105550142`
Find their tickets	`GET /api/v2/search?query=type:ticket requester:42 order_by:created_at sort:desc`
Append to a ticket	`PUT /api/v2/tickets/1001.json`
Create a ticket	`POST /api/v2/tickets.json`

Tenant JavaScript

Two secrets are needed here, and there is only one secret slot — so pack them into one string:

'use strict';

export const load = (form, data) => {
  const d = data || {};
  form.querySelector('[name="beacon_url"]').value = d.beacon_url || '';
  form.querySelector('[name="beacon_email"]').value = d.beacon_email || '';
  form.querySelector('[name="beacon_token"]').value = '';
}

export const save = (form) => {
  const email = form.querySelector('[name="beacon_email"]').value;
  const result = [{
    beacon_url: form.querySelector('[name="beacon_url"]').value.replace(/\/+$/, ''),
    beacon_email: email
  }];
  const token = form.querySelector('[name="beacon_token"]').value;
  // The API expects "<email>/token:<token>" as basic credentials - store it ready to use:
  token && result.push(email + '/token:' + token);
  return result;
}

Backend JavaScript

//
// Beacon Support integration - example code
//

'use strict';

var BASE = '/api/v2/';

// Fictional custom field IDs from the helpdesk - yours will differ:
var FIELD_DURATION = 100000000001;
var FIELD_CALLID = 100000000002;

function Beacon () {}

Beacon.prototype.sendCmd = function (method, settings, command, body, callback) {
  var args = {
    method: method,
    url: settings.url + BASE + command,
    header: [
      { name: 'Authorization', value: 'Basic ' + toBase64String(settings.cred), secret: true },
      { name: 'Content-Type', value: 'application/json' }
    ],
    callback: callback
  };
  if (body) args.body = JSON.stringify(body);
  system.http(args);
};

Beacon.prototype.hhmmss = function (seconds) {
  var d = new Date(null);
  d.setSeconds(seconds);
  return d.toISOString().substr(11, 8);
};

Beacon.prototype.logCall = function (domain, settings, call) {
  var self = this;

  var body = { ticket: { comment: { public: false } } };
  body.ticket.comment.body = 'Call from ' + call.from + ' to ' + call.to +
    ' at ' + new Date(call.startMs).toISOString() +
    ' for ' + this.hhmmss(call.duration);

  if (call.recordingLink) {
    body.ticket.comment.body += '\nRecording: ' + call.recordingLink;
  }

  body.ticket.custom_fields = [
    { id: FIELD_DURATION, value: call.duration },
    { id: FIELD_CALLID, value: call.callid }
  ];

  // Strip a leading + - many helpdesks store numbers without it:
  var caller = call.from.substr(0, 1) === '+' ? call.from.substr(1) : call.from;

  self.sendCmd('GET', settings, 'search?query=type:user%20phone:' + encodeURIComponent(caller),
    '', function (code, response) {
      var res = JSON.parse(response || '{}');

      if (!res.results || !res.results.length || !res.results[0].id) {
        // No such customer: create the ticket and the contact together.
        body.ticket.subject = 'Call from ' + caller;
        body.ticket.requester = { name: caller, phone: caller };
        if (call.groupId) body.ticket.group_id = call.groupId;
        self.sendCmd('POST', settings, 'tickets.json', body, function (c2, r2) {
          console.trace('CRM', 9, domain, 'Beacon: new ticket and contact, code ' + c2);
        });
        return;
      }

      var customerId = res.results[0].id;
      var customerEmail = res.results[0].email;
      var q = 'search?query=type:ticket%20requester:' + customerId +
              '%20order_by:created_at%20sort:desc';

      self.sendCmd('GET', settings, q, '', function (c3, r3) {
        var res3 = JSON.parse(r3 || '{}');

        if (res3.results && res3.results.length && res3.results[0].id) {
          // Append to the most recent ticket:
          self.sendCmd('PUT', settings, 'tickets/' + res3.results[0].id + '.json', body,
            function (c4) {
              console.trace('CRM', 9, domain, 'Beacon: appended to ticket, code ' + c4);
            });
        }
        else if (customerEmail) {
          body.ticket.subject = 'Call from ' + caller;
          body.ticket.requester = { email: customerEmail };
          if (call.groupId) body.ticket.group_id = call.groupId;
          self.sendCmd('POST', settings, 'tickets.json', body, function (c5) {
            console.trace('CRM', 9, domain, 'Beacon: new ticket, code ' + c5);
          });
        }
      });
    });
};

var beacon = new Beacon();

function oncdr (cdr) {
  // In oncdr, cdr.domain is the tenant address. Resolve it the way the settings were stored:
  var domain = Domain.get(cdr.domain, '*');

  var settings = {
    url: loadIntr(domain, '', 'beacon_url', false),
    email: loadIntr(domain, '', 'beacon_email', false),
    cred: loadIntr(domain, '', '', true)
  };
  if (!settings.url || !settings.cred) return;

  // No trunk leg at all means an internal extension-to-extension call. Filter it out
  // before anything else - see "The three leg arrays in a CDR".
  if (!cdr.trunklegs || !cdr.trunklegs.length) {
    console.trace('CRM', 9, domain, 'Beacon: internal call, not logging');
    return;
  }

  // This integration only wants inbound calls. Leg direction is 'I' for inbound.
  if (cdr.trunklegs[0].direction !== 'I') return;

  // The From header is a full SIP contact - parse it down to the number:
  var contact = system.parseSipContact(cdr.from);
  var from = system.parseSipUri(contact.uri).user;

  // Walk the extension legs and keep the LAST one that actually connected. After a transfer
  // there are several, and the last one is the extension that really handled the call.
  // Note this tests connect/end timestamps, NOT a SIP response code - a cancelled fork
  // reports 486 or 487 on calls that were in fact answered.
  var answered = null;
  var group = '';
  if (cdr.extensionlegs) {
    for (var i = 0; i < cdr.extensionlegs.length; i++) {
      var e = cdr.extensionlegs[i];
      if (e.direction === 'O' && e.connect > 0 && e.end > e.connect) {
        answered = e;
        if (e.redirect) group = system.parseSipContact(e.redirect).name || '';
      }
    }
  }
  if (!answered) {
    console.trace('CRM', 9, domain, 'Beacon: call from ' + from + ' was never answered');
    return;
  }

  // CDR leg timestamps are in seconds:
  var call = {
    callid: cdr.callid,
    from: from,
    to: answered.extension,
    startMs: answered.start * 1000,
    duration: Math.floor(answered.end - answered.connect),
    groupId: 0,
    recordingLink: ''
  };

  // Build a playback link for the first recording, if there is one:
  if (cdr.recordings && cdr.recordings.length) {
    var rec = cdr.recordings[0];
    if (rec.url) {
      call.recordingLink = rec.url;
    } else if (rec.id) {
      var rep = system.httpRepresentation(domain);
      var host = (rep && rep.address) ? rep.address : Domain.get(domain, 'name');
      call.recordingLink = 'https://' + host + '/rest/user/' + call.to + '@' +
        Domain.get(domain, 'name') + '/recs?id=' + rec.id;
    }
  }

  // Route the ticket to the helpdesk group matching the PBX queue name, when there is one:
  if (group) {
    var cmd = 'search?query=type:group%20name:' + encodeURIComponent(group);
    beacon.sendCmd('GET', settings, cmd, '', function (code, response) {
      var res = JSON.parse(response || '{}');
      if (res.results && res.results.length && res.results[0].id) {
        call.groupId = res.results[0].id;
      }
      beacon.logCall(domain, settings, call);
    });
  } else {
    beacon.logCall(domain, settings, call);
  }
}

Reading a CDR

cdr.from and cdr.to are full SIP headers. Use system.parseSipContact then system.parseSipUri to get a bare number.
An empty cdr.trunklegs means an internal call — return early.
trunklegs[0].direction tells you inbound ('I') or outbound ('O'). State legs do not.
Decide answered from talk time or connect > 0, never from a SIP response code.
Iterate extensionlegs and keep the last leg with connect > 0 && end > connect — that is the extension that handled the call after any transfers. No such leg means the call was never answered.
extensionlegs[i].redirect is a SIP contact whose display name is the queue or ring group the call came through.
Leg timestamps (start, connect, end) are seconds; states[i].durationtalk is milliseconds. Multiply the former by 1000 before new Date(); divide the latter.
states[] and trunklegs[] are not the same length. Do not pair them by index.

Some platforms authorize once per organization rather than per user, often with a separate administrator consent step. The tenant administrator does this from the tenant interface, and because the whole page navigates away and back, the tokens arrive as query parameters and are saved with the ordinary save call.

Fictional values:

Setting	Value
Client ID	`00000000-0000-0000-0000-000000000000`
Redirect URI (registered with the vendor)	`https://portal.example.com/en/northwindredir`
Consent endpoint	`https://login.northwind.example/common/adminconsent`
Authorize endpoint	`https://login.northwind.example/common/oauth2/v2.0/authorize`

Tenant HTML

<!-- Northwind Cloud -->
<input type="password" style="display:none;" readonly>

<div class="row">
  <div class="col-sm-12"><div id="northwind-status"></div></div>
</div>

<div class="row">
  <div class="form-group">
    <label for="northwind_org_url" class="col-sm-6 control-label">Organization URL</label>
    <div class="col-sm-6">
      <input type="url" class="form-control" id="northwind_org_url"
             placeholder="https://yourorg.northwind.example">
      <small class="form-text text-muted">Required before requesting a token</small>
    </div>
  </div>
</div>

<div class="row">
  <div class="form-group">
    <div class="col-sm-4">
      <button id="northwind-consent" class="btn btn-warning fancy">
        <i class="fa fa-shield"></i> 1. Grant Admin Consent
      </button>
    </div>
    <div class="col-sm-4">
      <button id="northwind-token" class="btn btn-primary fancy">
        <i class="fa fa-key"></i> 2. Get OAuth Token
      </button>
    </div>
    <div class="col-sm-4">
      <button id="northwind-remove" class="btn btn-danger fancy">
        <i class="fa fa-trash"></i> Remove Tokens
      </button>
    </div>
  </div>
</div>

The hidden password input at the top is a small trick that stops browsers from autofilling credentials into the real fields below.

Tenant JavaScript

Bootstrap and jQuery are available in the tenant interface, so $(...) works here — unlike in the user portal.

'use strict';

const CLIENT_ID = '00000000-0000-0000-0000-000000000000';
const REDIRECT_URI = 'https://portal.example.com/en/northwindredir';
const LOGIN_BASE = 'https://login.northwind.example/common';

// Tokens handed back as query parameters after the redirect:
window.northwindTokens = null;

function collectTokens () {
  const p = new URLSearchParams(window.location.search);
  if (p.get('northwind_success') !== '1' || !p.get('northwind_access_token')) return;

  const expires = parseInt(p.get('northwind_expires_in')) || 3600;
  window.northwindTokens = {
    access_token: p.get('northwind_access_token'),
    refresh_token: p.get('northwind_refresh_token') || '',
    org_url: p.get('northwind_org_url') || '',
    token_expires: Date.now() + expires * 1000
  };

  // Clean the tokens out of the address bar so they are not bookmarked or shared:
  window.history.replaceState({}, document.title, window.location.href.split('?')[0]);
  alert('Authorization successful. Please save your settings.');
}

collectTokens();

export const load = (form, data) => {
  form.querySelector('#northwind_org_url').value = (data || {}).northwind_org_url || '';
  if (!window.northwindTokens) collectTokens();
  updateStatus();
}

export const save = (form) => {
  const orgUrl = form.querySelector('#northwind_org_url').value.trim();
  const pub = { northwind_org_url: orgUrl };
  const t = window.northwindTokens;
  if (!t) return [pub];

  // Public settings plus the refresh token in the secret slot:
  pub.northwind_org_url = t.org_url || orgUrl;
  pub.northwind_token_expires = t.token_expires;
  return [pub, t.refresh_token || t.access_token];
}

function validOrgUrl (url) {
  try {
    const u = new URL(url);
    return u.protocol === 'https:' && u.hostname.endsWith('.northwind.example');
  } catch (e) {
    return false;
  }
}

function updateStatus () {
  const div = document.getElementById('northwind-status');
  const t = window.northwindTokens;
  div.innerHTML = t && t.access_token
    ? `<div class="alert alert-success"><i class="fa fa-check-circle"></i>
         <strong>Connected</strong><br>Organization: ${t.org_url || 'configured'}</div>`
    : '';
}

function authUrl (kind, orgUrl) {
  const dn = sessionStorage.getItem('domain');
  if (!dn) {
    alert('Domain not found. Please reload the page.');
    return null;
  }
  const back = window.location.href.split('?')[0];
  const state = [ encodeURIComponent(dn), back, kind, encodeURIComponent(orgUrl) ].join('::');

  if (kind === 'admin_consent') {
    return `${LOGIN_BASE}/adminconsent` +
      `?client_id=${encodeURIComponent(CLIENT_ID)}` +
      `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}` +
      `&state=${encodeURIComponent(state)}`;
  }

  const scope = orgUrl.replace(/\/+$/, '') + '/user_impersonation offline_access';
  return `${LOGIN_BASE}/oauth2/v2.0/authorize` +
    `?client_id=${encodeURIComponent(CLIENT_ID)}` +
    `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}` +
    `&response_type=code` +
    `&scope=${encodeURIComponent(scope)}` +
    `&state=${encodeURIComponent(state)}`;
}

$(function () {
  $('#northwind-consent').on('click', function () {
    const url = authUrl('admin_consent', $('#northwind_org_url').val().trim());
    if (url) window.location.href = url;
  });

  $('#northwind-token').on('click', function () {
    const orgUrl = $('#northwind_org_url').val().trim();
    if (!validOrgUrl(orgUrl)) {
      alert('Please enter a valid organization URL first.');
      $('#northwind_org_url').focus();
      return;
    }
    const url = authUrl('oauth', orgUrl);
    if (url) window.location.href = url;
  });

  $('#northwind-remove').on('click', function () {
    const domain = encodeURIComponent(sessionStorage.getItem('domain'));
    fetch('/rest/domain/' + domain + '/integrations?identifier=northwind', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json; charset=utf-8' },
      body: JSON.stringify({ disable: 'true' })
    }).then(() => {
      window.northwindTokens = null;
      updateStatus();
    });
  });

  updateStatus();
});

Note the two REST paths. The tenant interface posts to /rest/domain/<tenant>/integrations, the user portal to /rest/user/<ext>@<tenant>/integrations. Both arrive at onfrontend; the difference is whether data.user is set.

Tokens in query parameters

This pattern is convenient but it puts an access token in a URL, where it can end up in browser history, proxy logs and referrer headers. Mitigate it: use a short-lived code or refresh token rather than a long-lived access token, call history.replaceState immediately as above, and put the token in the secret slot when saving rather than in the public settings object.

Host matching for regional tenants

Whatever you use to validate or recognize the organization host, write the test against the shape the vendor actually uses, not one example of it. A check for a literal .crm.example.com will never match a regional host such as yourorg.crm6.example.com, and the failure is silent — the value is stored, the integration simply reports itself as unconfigured. Prefer a pattern (/\.crm\d*\.example\.com$/) over a substring.

Backend JavaScript

'use strict';

var VENDOR = 'Northwind';

function onfrontend (data, callback) {
  var domain = data.domain;
  var body = JSON.parse(data.body || '{}');

  if (body.disable === 'true') {
    system.updateOAuthSetting(VENDOR, data.user || 0, false, true);
    saveIntr(domain, '', 'northwind_enabled', '', false);
    callback(200, 'Ok', 'application/json', '{"result":true}');
    return;
  }

  callback(200, 'Ok', 'application/json', '{"result":true}');
}

// Read the tenant token whenever a request needs to be made:
function northwindRequest (domain, method, path, body, callback) {
  var org = loadIntr(domain, '', 'northwind_org_url', false);
  var token = loadIntr(domain, '', '', true);
  if (!org || !token) {
    console.trace('CRM', 4, domain, 'Northwind: not configured');
    return;
  }
  system.http({
    method: method,
    url: org.replace(/\/+$/, '') + path,
    header: [
      { name: 'Authorization', value: 'Bearer ' + token, secret: true },
      { name: 'Content-Type', value: 'application/json' }
    ],
    body: body,
    callback: callback
  });
}

Pattern 5: Click to call from an external application

onhttp lets an outside application reach into the PBX. Requests arrive on a URL prefixed with your identifier, and you answer through the callback. This example rings the agent's own extension first, then dials the customer once the agent picks up.

POST https://pbx.example.com/northwind/dial
Content-Type: application/json
X-Integration-Secret: shared-secret-000000

{ "domain": "tenant.example.com", "extension": "41", "to": "+15105550142" }

'use strict';

function onhttp (data, callback) {
  if (data.method !== 'POST' || data.url !== 'dial') {
    callback(404, 'Not Found', 'application/json', '{"error":"unknown endpoint"}');
    return;
  }

  // Authenticate. Never leave this endpoint open - it can place calls.
  var secret = '';
  for (var i = 0; i < data.headers.length; i++) {
    if (data.headers[i].name.toLowerCase() === 'x-integration-secret') {
      secret = data.headers[i].value;
    }
  }
  var expected = loadIntr(data.domain || '', '', '', true);
  if (!expected || secret !== expected) {
    callback(403, 'Forbidden', 'application/json', '{"error":"bad secret"}');
    return;
  }

  var req = {};
  try {
    req = JSON.parse(data.body || '{}');
  } catch (e) {
    callback(400, 'Bad Request', 'application/json', '{"error":"invalid json"}');
    return;
  }
  if (!req.extension || !req.to) {
    callback(400, 'Bad Request', 'application/json', '{"error":"extension and to are required"}');
    return;
  }

  var id = startCall({
    domain: req.domain || data.domain,
    user: req.extension,
    to: req.to,
    timeout: 30,
    connect: true          // connect the two parties automatically
  });

  console.trace('SCRIPT', 9, data.domain,
    'Click to call: ' + req.extension + ' -> ' + req.to + ' (call ' + id + ')');

  callback(200, 'Ok', 'application/json', JSON.stringify({ callid: id }));
}

startCall returns an identifier you can pass to endCall(id) to cancel the attempt.

Reporting failures back

If the external system wants to know why a click-to-dial attempt failed, subscribe to the system's call error events:

system.on('call-error-rejected', function (data) {
  report(data, 'rejected', 'The agent did not accept the call');
});

system.on('call-error-notavailable', function (data) {
  report(data, 'notavailable', 'The agent is not available');
});

system.on('call-error-invalid', function (data) {
  report(data, 'invalid', 'The dialed number is invalid');
});

function report (data, code, message) {
  // data.call has domain, from and to; data.user is the extension that dialed.
  var from = system.parseSipUri(system.parseSipContact(data.call.from).uri).user;
  var to = system.parseSipUri(system.parseSipContact(data.call.to).uri).user;
  console.trace('SCRIPT', 7, data.call.domain,
    'Click to call failed: ' + code + ' ' + from + ' -> ' + to + ' (' + message + ')');
  // ...forward to the external system here
}

These fire for every call on the system, so check that the call belongs to your integration before acting — for example by comparing the tenant against your own settings.

Pattern 6: Directory sync and other non-call integrations

Nothing in the framework restricts integrations to calls. A useful category has no call hooks at all: it adds buttons to the tenant interface, and the backend does work when they are pressed. Directory sync is the usual example — read users from an identity provider, then create matching extensions.

The mechanics: the tenant page posts an action, onfrontend dispatches on it, and the backend uses the PBX's own REST API to make changes.

'use strict';

function onfrontend (data, callback) {
  var domain = data.domain;
  var body = JSON.parse(data.body || '{}');

  switch (body.action) {

    case 'preview':
      // Fetch the directory and return it, so the administrator can review and choose
      // before anything is created. Do not create accounts on the first click.
      fetchDirectory(domain, function (users) {
        callback(200, 'Ok', 'application/json', JSON.stringify({ users: users }));
      });
      return;

    case 'create':
      // body.users is what the administrator confirmed in the dialog.
      createExtensions(domain, body.users || [], function (results) {
        callback(200, 'Ok', 'application/json', JSON.stringify({ results: results }));
      });
      return;

    case 'settings':
      saveIntr(domain, '', 'sync_enabled', body.enabled ? 'true' : '', false);
      callback(200, 'Ok', 'application/json', '{"result":true}');
      return;
  }

  callback(400, 'Bad Request', 'application/json', '{"error":"unknown action"}');
}

function createExtensions (domain, users, done) {
  var results = [];
  for (var i = 0; i < users.length; i++) {
    var u = users[i];

    // Do not overwrite an account that already exists:
    if (Account.get(domain, u.extension, '*')) {
      results.push({ email: u.email, ok: false, error: 'extension ' + u.extension + ' in use' });
      continue;
    }

    // The exact payload depends on your PBX version - see the REST API documentation.
    var r = system.restApi({
      method: 'POST',
      path: '/rest/domain/' + domain + '/accounts',
      body: JSON.stringify({
        name: u.extension,
        'display-name': u.display_name,
        email_address: u.email
      })
    });
    results.push({ email: u.email, ok: !!r, extension: u.extension });
  }
  done(results);
}

Three points that matter more here than in a CRM integration:

Preview before writing. Creating extensions is destructive if the mapping is wrong. Return the proposed list, let the administrator adjust extension numbers and deselect rows, then create only what came back confirmed.

Detect conflicts explicitly. Check for an existing extension number, for an e-mail already attached to a different account, and for duplicates within the batch itself. Report each conflict next to the row that caused it rather than failing the whole run.

Make automatic sync opt-in. Store a flag and check it before doing anything unattended, and report what a scheduled run did in the trace log — nobody will be watching when it happens.

Reference: what the backend gives you

Settings

Function	Purpose
`loadIntr(domain, user, name, secret)`	Read a setting. `""` as `user` for tenant settings. `secret: true` with an empty name reads the one secret slot.
`saveIntr(domain, user, name, value, secret)`	Write a setting from the backend.
`system.setting(name)`	Read a system-level setting, e.g. a client ID shared by all tenants.

HTTP and OAuth

Function	Purpose
`system.http({ method, url, header, body, callback })`	Outbound HTTP. `callback(code, response, headers)`. Mark credential headers `secret: true`.
`system.getOAuthToken(arg)`	Promise resolving to a valid access token; also performs the initial code exchange with `obtainToken: true`. Vendor extras such as `api_domain` come back in the result.
`system.updateOAuthSetting(vendor, user, enabled, remove)`	Mark a user as connected, or drop the stored token.
`system.oauthList`	The current OAuth registrations.
`system.restApi({ method, path, body })`	Call the PBX's own REST API.
`toBase64String(text)`	Base64, e.g. for HTTP basic authentication.

Prefer system.getOAuthToken over hand-rolling token storage and refresh in your own settings. Integrations that keep their own tokens have to reimplement expiry, refresh, concurrency and failure handling, and every one of those is a place to get it wrong.

Calls

Function	Purpose
`system.setCallInfo(callid, msg)`	Attach information to a live call — this is the screen pop.
`startCall(args)`	Place a call; returns an ID.
`endCall(id, code, expl, forced)`	Tear a call down.
`system.on(event, fn)`	Subscribe to system events such as `call-error-rejected`, `call-error-notavailable`, `call-error-invalid`.

Looking things up

Function	Purpose
`tables['domains'].search()`	List tenants, e.g. at start-up.
`Account.get(domain, account, field)`	Account lookup. Useful fields: `alias-name`, `display-name`, `email_address`, `crm_account`. Returns nothing when the account does not exist, which is the cheapest internal-number test: `Account.get(domain, number, '*')`.
`Domain.get(domain, field)`	Tenant lookup, e.g. `name`, or `'*'` to resolve a reference.
`system.httpRepresentation(domain)`	The externally reachable address for the tenant — use it to build links.

Do not look tenants up by user index

Avoid table access that goes through the user index — for example resolving a tenant from a numeric user ID with the users table. That access path changes in version 71, and code written against it will need reworking.

You never need it. Every hook hands you the tenant: event.domain.address in onagent and ongroup, cdr.domain in oncdr, data.domain in onfrontend and onhttp. Pass it down through your own functions, as sendCmd does in Pattern 2, and use Account.get and Domain.get for the lookups themselves — those stay as they are.

Resolving the agent behind a leg

A state leg does not always carry extension. Queue and mailbox legs often carry only account, which maps to the agent extension through the crm_account property. Resolve in that order:

function legExtension (domain, sleg) {
  if (!sleg) return '';
  if (sleg.extension) return sleg.extension;
  if (!sleg.account) return '';
  return Account.get(domain, sleg.account, 'crm_account') || sleg.account;
}

The e-mail address you then read with Account.get(domain, ext, 'email_address') may be stored as a full contact — Ash Prasad <ash.prasad@example.com> — rather than a bare address. Strip it before putting it in a query, and escape it if it goes into a filter expression:

function normalizeEmail (email) {
  if (!email) return '';
  var m = ('' + email).match(/<([^>]+)>/);
  return (m ? m[1] : ('' + email)).replace(/^\s+|\s+$/g, '');
}

Parsing and formatting

Function	Purpose
`system.parseSipContact(header)`	Split a SIP contact into `name` and `uri`.
`system.parseSipUri(uri)`	Split a URI; `.user` is the number.
`system.domainGlobalNumber(domain, number)`	Expand an extension to its global number.
`system.format(fmt, ...)`	`printf`-style formatting.
`console.trace(area, level, domain, text)`	Log. Higher level means more verbose.

Practical advice

Log at deliberate levels. Level 9 for the detail you want while building, level 7 for failures worth noticing, level 4 for misconfiguration the administrator must fix. Raise the log level on the system's Logging page while testing, then leave the verbose lines in — they cost nothing at a low level and save hours later.

Log the decision, not just the outcome. One line per leg showing type, trunk code, state code and talk time turns a wrong record into a five-second diagnosis:

console.trace('CRM', 9, domain, 'leg ' + j + ' (' + sleg.type + '), trunk code: ' +
  (tleg ? tleg.code : 'none') + ', state code: ' + sleg.code +
  ', talk: ' + (sleg.durationtalk || 0));

Filter internal traffic first. Extension-to-extension calls, star codes and pickup codes all fire onagent, and they all produce a CDR. The test differs by hook:

In onagent, check Account.get(domain, number, '*') before anything else — it returns nothing for an external number, so a truthy result means internal.
In oncdr, check cdr.trunklegs.length. Zero means the call never touched a trunk.

Add a second guard before creating contacts, whatever the hook: a "customer number" shorter than about six digits is an extension, not a contact. It costs one line and it is the difference between a clean contact list and one full of entries named 504.

Note that resolving the agent by e-mail is not an internal-call filter. It decides who owns the activity; the contact is still matched on the phone number, which on an internal call is an extension. The two guards are independent and you need both.

Return quickly. These hooks run inside call processing. Do the work in the system.http callback and return; never wait for a response inline.

Expect duplicate events. A single call produces several onagent events per state as legs change. If a write is not idempotent, key it on event.callid.

Prefer oncdr for logging. It fires once, the direction is explicit in the legs, and transfers, recordings and queue names are all resolvable. Reconstructing the same picture from onagent events is considerably more work and easier to get wrong.

Numbers rarely match on the first attempt. The PBX passes on whatever the trunk sent — ten digits, sometimes a leading 1, sometimes full E.164. The target system holds whatever somebody typed. Normalize both sides, and if the API allows it, search on the last seven to nine digits instead of the whole string.

Write timestamps in the timezone the target system expects. The PBX script engine reports local time as UTC, so getHours() and friends return UTC regardless of the server's configured timezone. Some targets convert UTC to the viewer's timezone on display and want an ISO string; others store whatever you send verbatim and need the offset applied before you send it. Check which, and if you have to apply an offset yourself, make it a named constant rather than burying it in a date helper — somebody will have to change it twice a year.

Scope​

Before you start​

Three things that will bite you​

The three leg arrays in a CDR​

Pattern 1: AcmeCRM — tenant API key and screen pop​

Tenant HTML​

Tenant JavaScript​

Backend JavaScript​

The screen pop message​

Pattern 2: Zenith Desk — per-user OAuth​

User HTML​

User CSS​

User JavaScript​

Backend JavaScript​

Pattern 3: Beacon Support — tickets from the CDR​

Tenant JavaScript​

Backend JavaScript​

Pattern 4: Northwind Cloud — tenant OAuth with admin consent​

Tenant HTML​

Tenant JavaScript​

Backend JavaScript​

Pattern 5: Click to call from an external application​

Reporting failures back​

Pattern 6: Directory sync and other non-call integrations​

Reference: what the backend gives you​

Settings​

HTTP and OAuth​

Calls​

Looking things up​

Resolving the agent behind a leg​

Parsing and formatting​

Practical advice​

Scope

Before you start

Three things that will bite you

The three leg arrays in a CDR

Pattern 1: AcmeCRM — tenant API key and screen pop

Tenant HTML

Tenant JavaScript

Backend JavaScript

The screen pop message

Pattern 2: Zenith Desk — per-user OAuth

User HTML

User CSS

User JavaScript

Backend JavaScript

Pattern 3: Beacon Support — tickets from the CDR

Tenant JavaScript

Backend JavaScript

Pattern 4: Northwind Cloud — tenant OAuth with admin consent

Tenant HTML

Tenant JavaScript

Backend JavaScript

Pattern 5: Click to call from an external application

Reporting failures back

Pattern 6: Directory sync and other non-call integrations

Reference: what the backend gives you

Settings

HTTP and OAuth

Calls

Looking things up

Resolving the agent behind a leg

Parsing and formatting

Practical advice