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.
	timers[].date	Date	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>

WIKI

Table of Contents