API : PBX : Events

A PBX event is a rule of the form when this happens on the PBX, do that. When the trigger happens - a call starts, rings, is answered or ends, a switch is turned on or off, something happens in a queue or a conference room, a user logs in to or out of a hotdesk phone, or a point in time is reached - the event runs its actions:

• Webhook - call a URL of your own, with details of what happened.
• SMS - send an SMS to up to 10 recipients.
• Call - place a call, e.g. ring a group and connect whoever answers to an announcement or another number.
• Set variable - set a PBX variable.
• Set switch - turn a PBX switch on or off.
• Queue - put an extension in a queue or take it out, take it out of every queue, or empty a queue.

An event can have any combination of the six actions. Texts in the webhook, the SMS and the variable value can hold variables such as %A_NUMBER%, which are filled in when the event runs.

A customer can have at most 100 events. Each run of an event is logged with the result of each action, and every event can be tested with values of your own choosing.

The type of an event decides what triggers it, and its target can limit it to a number, a switch, a queue, a conference room or a phone.

Good to know:

• A call can have several legs - e.g. when a group rings five phones. An event runs once per call for each phase (start, ring, answer, end), on the first leg that matches its target.
• Secret numbers are never shown. For a caller with a secret number calling in from outside, a queue caller with a secret number and a conference participant with a secret number, the number and name are empty in the variables, and a target number is not matched against the number. A conference participant who is not one of the customer's employees counts as secret, unless the PBX knows that the number is not secret.
• Setting a switch to the value it already has does not trigger an event, and neither does deleting a switch.
• A switch or variable set by the set switch or set variable action of an event, a member put in or taken out of a queue by the queue action, and a call placed by the call action, never trigger events themselves, so events cannot trigger each other in a loop. So an extension that an event puts in a queue does not trigger QUEUE or QUEUE_MEMBER_JOIN events - see Queue.
• QUEUE runs once per caller for each of entered, answered, cancelled and timed out, and every time a member joins or leaves. QUEUE_MEMBER_JOIN and QUEUE_MEMBER_LEFT run every time a member joins or leaves, and never for the callers.
• TIMER follows Danish summer and winter time: when summer time ends, the repeated hour runs once; a time that does not exist when summer time starts (02:00-02:59 on the last Sunday of March) does not run that day.
• An event with enabled false is kept but never triggered. It can still be tested.

The actions of an event run in this order: set switch, set variable, queue, webhook, SMS, call. Each action runs on its own - one that fails does not stop the others - and the result of each is written to the run log.

Because the set actions run first, a webhook or SMS of the same event that uses %SWITCH:name% or %VARIABLE:name% sees the value that was just set.

The webhook calls the URL of the event. The URL must be http or https, and may not point at a private, loopback or otherwise non-public address, or at Telecom X's own network. Variables may be used in the path and the query string of the URL, but not in the host name.

Every request carries these headers:

Every webhook has a secret. One is generated when the webhook is created, and you can set your own or generate a new one. The secret is shown only to users who may change the event: by Get, in the answers to Create, Update and Secret - never by List. Check the signature to be sure a request comes from your PBX event and was not changed on the way.

• The request times out after 5 seconds.
• A response with status 200-299 is a success. The response body is not used.
• Redirects are not followed - a 3xx response counts as a failure.
• The host name is looked up when the request is sent, and the request is refused if the name points at a private, loopback or otherwise non-public address, or at Telecom X's own network - also an IPv6 address that carries such an IPv4 address (NAT64, 6to4).
• A user name and password in the URL (https://user:password@hooks.example.com/) is sent as basic authentication.
• A failed request is not retried.

For GET, the signature is made over the URL exactly as it is called: the URL of the event with the variables filled in, e.g. https://hooks.example.com/pbx?caller=%2B4512345678. If your server sits behind a proxy, rebuild the URL as it is written in the event before you check it. Do not put a #fragment in a GET webhook URL - it is signed, but not sent.

const http = require('node:http')
const crypto = require('node:crypto')
 
const SECRET = process.env.PBX_EVENT_SECRET     // the webhook secret of the event
const BASE = 'https://hooks.example.com'        // scheme and host of the webhook URL, as written in the event
 
function signatureOk(signed, header) {
  const expected = Buffer.from('sha256=' + crypto.createHmac('sha256', SECRET).update(signed).digest('hex'))
  const received = Buffer.from(String(header || ''))
  return expected.length === received.length && crypto.timingSafeEqual(expected, received)
}
 
http.createServer((req, res) => {
  const chunks = []
  req.on('data', chunk => chunks.push(chunk))
  req.on('end', () => {
    const body = Buffer.concat(chunks).toString('utf8')
    // GET is signed over the complete URL, POST and POSTJSON over the raw body
    const signed = req.method === 'GET' ? BASE + req.url : body
 
    if (!signatureOk(signed, req.headers['x-tcx-signature'])) {
      res.writeHead(401).end()
      return
    }
    console.log('PBX event', req.headers['x-tcx-event-id'], req.method === 'GET' ? req.url : body)
    res.writeHead(204).end()
  })
}).listen(8080)

Check the signature against the raw body, before it is parsed - a body that is parsed and serialised again can differ by a single character, and then the signature does not match.

The SMS action sends message to each of the recipients (at most 10, in E.164 format, e.g. +4520123456). The message can hold variables.

The sender is from - a phone number in E.164 format, or 1-11 letters, digits, spaces, dots, underscores or dashes. A phone number is sent without its +, and a sender can be at most 11 characters, so a number with more than 11 digits is cut to its first 11. Without from, the sender is the customer's name, cut to 11 characters.

Each SMS is billed to the customer like any other SMS sent from the platform.

The call action rings destination the way the customer's PBX rings that number on an internal call: an extension rings its phones, a group rings its members, and an external number is called like any other outbound call of the PBX. The destination must be an extension, a group or an external number - any other destination is refused, and the run log shows the call as failed. Emergency numbers are never called by the event, not even through a redirect - but once a person has answered, that person can always transfer the call to an emergency number.

The destination rings as long as it normally does - e.g. a large group that rings its members one after the other is not cut short. When a person answers, he or she is connected to source, which is called as an internal call of the customer - e.g. a playback with an announcement, or another extension. Start audio and the recording consent prompt are skipped for these calls.

With autoAnswer, SIP phones that support it answer the call by themselves (as when paging a group), which is useful for announcements over the phones' speakers. Only the phones of the destination itself answer by themselves - not phones the call is redirected to. The caller name shown is PBX event.

A call placed by the call action never triggers events itself - also not after the person who answered transfers it. On Realtime, its events carry source PBX_EVENTS.

Set variable sets a PBX variable to value (variables are filled in, at most 1024 characters). Set switch turns a PBX switch on or off. The names follow the same rules as everywhere else: no prefix for a system variable or switch, SHARED: for a shared one, and <employee-id>: for a personal one.

The change is announced on Realtime like any other change, with source PBX_EVENTS, and it never triggers other events.

The queue action changes the members of a queue of the customer. Its action says how:

queue and extension are the id of a queue and of an extension of the customer - or TRIGGER, to take them from what triggered the event:

If what triggered the event has no queue or no extension - e.g. a call that did not come through a queue, or a member who is an external number - the action fails with no_trigger_queue or no_trigger_extension in the run log. A test takes them from the variables you send.

Good to know:

• The queue does not have to let its members join and leave by themselves (member.dynamic) - an event is made by a manager, who may change the members of any queue. But if only the members of a group may join the queue (member.group), JOIN of an extension that is not in the group fails with not_permitted.
• Permanent members are never taken out. LEAVE of a permanent member fails with permanent_member, and LEAVE_ALL, EMPTY and exclusive leave them in the queue.
• A queue that locks its last member (member.lockLastMember) never loses it: LEAVE of the last member fails with last_member_locked, LEAVE_ALL skips that queue, and EMPTY fails with last_member_locked, and changes nothing, when nobody would be left.
• EMPTY with extension TRIGGER keeps the member who triggered the event. If that member has already left the queue again when the event runs, nothing is taken out.
• The change is announced on Realtime as QUEUE_MEMBER_JOIN and QUEUE_MEMBER_LEFT, with source PBX_EVENTS, and it shows up in the queue statistics like any other join or leave. It never triggers other events: when an event puts an extension in a queue, an event of type QUEUE_MEMBER_JOIN on that queue does not run. Use exclusive on the JOIN to take the others out at the same time.

An event of type QUEUE_MEMBER_JOIN with the queue action EMPTY, and TRIGGER as both queue and extension: whenever someone joins the queue, everyone else is taken out of it - except permanent members. Without a target it works on every queue of the customer; give the id of a queue as target to limit it to that queue. See the request in Create.

A variable is written as its name between percent signs, e.g. %A_NUMBER%. In addition to the variables of the trigger below, two kinds of lookups can be used:

A variable that is not known, or has no value for this run, becomes empty. Variable names are upper case letters and underscores.

Variables are filled in in the webhook URL, the webhook JSON, the SMS message and the value of set variable. They are not filled in in the call numbers, the SMS recipients and sender, or the names of the variable and switch to set. A value is escaped for the place it is put:

QUEUE_MEMBER_JOIN and QUEUE_MEMBER_LEFT are member events only.

Only the variables of every run.

The per minute limits count the last 60 seconds, and test runs count too. One event can only be tested once at a time - see Test. An action that would go over its limit is skipped, and the run log shows it as failed with the error rate_limited. An SMS action with more recipients than are left of the limit is skipped as a whole.

Events run when the PBX reports what happened, and each event runs at most once for each thing that happened. Delivery is best effort: if the service that runs the events is unavailable - e.g. during maintenance - what happens on the PBX in that time does not trigger events, and is not caught up afterwards. A TIMER that is a few minutes late runs when it can. A failed webhook, SMS or call is not retried.

Do not use PBX events for anything that must never be missed, such as billing or statistics - use the CDR for that.

Every run of an event - triggered or a test - is logged with what triggered it, the variables it ran with, and for each action whether it succeeded, the HTTP status, the error and how long it took. Runs are kept for 30 days. See Log.

When an event is deleted, its runs can no longer be read, and they are removed when their 30 days are up.