Table of Contents

API : PBX : Events Create

Introduction

A PBX event is a rule that runs actions - a webhook, an SMS, a call, setting a variable or a switch, or changing the members of a queue - when something happens on the PBX. See PBX events for the triggers, the variables and the limits.

Request

This request will create an event. All properties are optional. An event without a type is a CALL event, and an event can have any combination of the six actions - also none.

A customer can have at most 100 events.

URL https://api.telecomx.dk/pbx/events
Method POST
Access level MANAGER or OWNER if user belongs to the customer.
RESELLER if customer belongs to the reseller.
ADMIN.
Body customer Id Id of the customer the event belongs to. Defaults to the users own customer. Only RESELLER and ADMIN can create an event for another customer.
type String What triggers the event, default CALL: CALL, CALL_START, CALL_RING, CALL_ANSWER, CALL_END, SWITCH, SWITCH_ON, SWITCH_OFF, QUEUE, QUEUE_MEMBER_JOIN, QUEUE_MEMBER_LEFT, CONFERENCE, HOTDESK or TIMER - see Triggers. The old names CALL_RINGING and CALL_ANSWERED are accepted and saved as CALL_RING and CALL_ANSWER.
enabled Boolean False to keep the event without it being triggered, default true.
target String What the trigger is limited to, at most 64 characters. Empty or null for no limit. Depending on type:
CALL
CALL_START
CALL_RING
CALL_ANSWER
CALL_END 		A phone number or the start of one: digits with an optional leading +. Matched against the calling and the called number.
SWITCH
SWITCH_ON
SWITCH_OFF 		Required. The exact name of the switch: letters, digits, _ and -, prefixed with SHARED: for a shared switch or <employee-id>: for a personal switch.
QUEUE
QUEUE_MEMBER_JOIN
QUEUE_MEMBER_LEFT 		Id of a queue of the customer.
CONFERENCE Id of a conference of the customer.
HOTDESK Id of an extension of the customer, or the MAC address of a SIP phone written as 00:15:65:AA:BB:CC (upper or lower case).
TIMER Not used.
timers Array When a TIMER event runs, at most 100 timers. Ignored for the other types.
timers[].day Number Weekly timer: day of the week, 0-6, 0 is Sunday. Requires time.
timers[].time Number Weekly timer: minutes since midnight, Danish time, 0-1439 - e.g. 480 is 08:00. Requires day.
timers[].date Date One-off timer: the date and time to run, as an ISO 8601 string. Runs in the minute it falls in.
A timer with neither date nor both day and time is dropped. To run every weekday at 08:00, add five timers with day 1-5 and time 480.
webhook Object Call a URL - see Webhook. Null or an empty url for no webhook.
webhook.method String GET (default), POST or POSTJSON.
webhook.url String URL to call, at most 1024 characters. Must be http or https, and may not point at a private, loopback or otherwise non-public address or a Telecom X address - also not an IPv6 address that carries such an IPv4 address. May hold variables in the path and the query string, not in the host name.
webhook.json String The JSON to post, at most 8192 characters. Required when method is POSTJSON. May hold variables - put each one inside a JSON string. It is not checked to be valid JSON.
webhook.secret String [optional] Secret to sign the requests with, 16-128 printable characters without spaces. Leave it out to have one generated (64 hex characters).
sms Object Send an SMS - see SMS. Null or empty recipients for no SMS.
sms.message String The message, at most 1024 characters. Required. May hold variables.
sms.recipients String Comma separated list of phone numbers in E.164 format (e.g. +4520123456), at most 10.
sms.from String [optional] Sender: an E.164 number, or 1-11 letters, digits, spaces, dots, underscores or dashes. A number is sent without its + and cut to 11 digits. Null or empty for the customer's name, cut to 11 characters.
call Object Place a call - see Call. Null or an empty destination for no call.
call.destination String Number to ring, as dialled on the customer's PBX. It must be an extension, a group or an external number - another destination, or an emergency number, is refused when the event runs. Digits with an optional leading +, at most 20 characters.
call.source String Number the destination is connected to when a person answers, called as an internal call - e.g. a playback with an announcement. Digits with an optional leading +, at most 20 characters.
call.autoAnswer Boolean True to make the SIP phones of the destination answer by themselves, for announcements. Default false.
setVariable Object Set a PBX variable. Null or an empty target for none.
setVariable.target String Name of the variable: letters, digits, _ and -, prefixed with SHARED: if shared or <employee-id>: if personal. At most 64 characters.
setVariable.value String Value to set, at most 1024 characters. May hold variables. Default empty.
setSwitch Object Turn a PBX switch on or off. Null or an empty target for none.
setSwitch.target String Name of the switch: letters, digits, _ and -, prefixed with SHARED: if shared or <employee-id>: if personal. At most 64 characters.
setSwitch.value Boolean True to turn the switch on, false to turn it off. Required.
queue Object Change the members of a queue - see Queue. Null or an empty action for none.
queue.action String JOIN, LEAVE, LEAVE_ALL or EMPTY.
queue.queue String Id of a queue of the customer, or TRIGGER for the queue of what triggered the event (types CALL, CALL_START, CALL_RING, CALL_ANSWER, CALL_END, QUEUE, QUEUE_MEMBER_JOIN and QUEUE_MEMBER_LEFT). Required for JOIN, LEAVE and EMPTY. Not used for LEAVE_ALL.
queue.extension String Id of an extension of the customer, or TRIGGER for the extension of what triggered the event (the types above and HOTDESK). Required for JOIN, LEAVE and LEAVE_ALL. For EMPTY, the member to keep - null or empty to keep no one.
queue.priority Number JOIN only: priority of the new member, 1-20. Null or left out for 1.
queue.exclusive Boolean JOIN only: true to also take every other member who is not permanent out of the queue. Default false.
notes String Notes about the event, at most 4096 characters.

The variables that can be used in the webhook, the SMS and the variable value are listed in Variables.

Request body example - webhook and SMS when a call to a 70 number ends

{
  customer: '1234567890123456789ABCDE',
  type: 'CALL_END',
  target: '+4570',
  webhook: {
    method: 'POSTJSON',
    url: 'https://hooks.example.com/pbx',
    json: '{ "event": "%EVENT_TYPE%", "caller": "%A_NUMBER%", "called": "%B_NUMBER%", "talked": "%CONVERSATION_DURATION%" }'
  },
  sms: {
    message: 'Call from %A_NUMBER% (%A_NAME%) ended at %TIME%',
    recipients: '+4520123456,+4530123456',
    from: 'Reception'
  },
  notes: 'Tell the sales team about calls to the 70 number'
}

Request body example - night mode on weekdays at 17:00

{
  type: 'TIMER',
  timers: [
    { day: 1, time: 1020 },
    { day: 2, time: 1020 },
    { day: 3, time: 1020 },
    { day: 4, time: 1020 },
    { day: 5, time: 1020 }
  ],
  setSwitch: {
    target: 'night',
    value: true
  },
  notes: 'Night mode on at 17:00'
}

Request body example - announcement when the door bell switch is turned on

{
  type: 'SWITCH_ON',
  target: 'SHARED:doorbell',
  call: {
    destination: '500',
    source: '900',
    autoAnswer: true
  },
  setSwitch: {
    target: 'SHARED:doorbell',
    value: false
  }
}

Request body example - only one member in a queue at a time

{
  type: 'QUEUE_MEMBER_JOIN',
  target: '23456789012345678901BCDE',
  queue: {
    action: 'EMPTY',
    queue: 'TRIGGER',
    extension: 'TRIGGER'
  },
  notes: 'Whoever joins the support queue is its only member'
}

Response

The created event, in the same format as Get - including the webhook secret.

Example

{
  _id: '12345678901234567890ABCD',
  customer: '1234567890123456789ABCDE',
  type: 'CALL_END',
  enabled: true,
  target: '+4570',
  timers: [],
  notes: 'Tell the sales team about calls to the 70 number',
  createdAt: '2026-11-04T08:12:44.000Z',
  webhook: {
    method: 'POSTJSON',
    url: 'https://hooks.example.com/pbx',
    json: '{ "event": "%EVENT_TYPE%", "caller": "%A_NUMBER%", "called": "%B_NUMBER%", "talked": "%CONVERSATION_DURATION%" }',
    secret: '6f1c0f2a9d0e4b7a8c3d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f708192a3'
  },
  sms: {
    message: 'Call from %A_NUMBER% (%A_NAME%) ended at %TIME%',
    recipients: '+4520123456,+4530123456',
    from: 'Reception'
  },
  updatedAt: '2026-11-04T08:12:44.000Z'
}

Errors

Error code Message Description
403 access_denied Insufficient access level, or the customer does not have hosted PBX
404 customer Customer not found
409 limit A customer can have at most 100 PBX events
422 customer Invalid ObjectId
422 type Not one of the permitted values
422 enabled Not a boolean
422 target Invalid phone number or start thereof (CALL types)
422 target Invalid switch name (SWITCH types - the target is missing or not a valid switch name)
422 target Queue not found / Conference not found / Extension not found
422 target MAC address or Extension not found (HOTDESK)
422 target Longer than 64 characters
422 timers[n].day Not a whole number 0-6
422 timers[n].time Not a whole number 0-1439
422 webhook.method Not one of the permitted values
422 webhook.url Invalid URL
422 webhook.url The URL must be http or https
422 webhook.url The URL may not point at a private, loopback or Telecom X address
422 webhook.json JSON missing (method POSTJSON)
422 webhook.secret The secret must be 16-128 printable characters without spaces
422 sms.recipients Invalid phone number(s)
422 sms.recipients At most 10 recipients
422 sms.message Message is missing
422 sms.from The sender must be an E.164 number or 1-11 letters, digits, spaces, dots, underscores or dashes
422 call.destination Invalid phone number
422 call.source Invalid phone number
422 setVariable.target Invalid variable name
422 setSwitch.target Invalid switch name
422 setSwitch.value On or off is missing
422 queue.action Not one of the permitted values
422 queue.queue Must be an id or TRIGGER
422 queue.queue Queue is missing (JOIN, LEAVE and EMPTY)
422 queue.queue A type event has no queue to take (TRIGGER with a type whose events have no queue)
422 queue.queue Queue not found
422 queue.extension Must be an id or TRIGGER
422 queue.extension Extension is missing (JOIN, LEAVE and LEAVE_ALL)
422 queue.extension A type event has no extension to take (TRIGGER with a type whose events have no extension)
422 queue.extension Extension not found
422 queue.priority Not a whole number 1-20
422 queue.exclusive Not a boolean
500 internal_error <Unspecified>