API : PBX : Extension Update

Introduction

An extension is a call-able endpoint. It can be configured with a local extension, direct number, and settings for how to dial out and what to do when the extension receives a call.

SIP phones and mobile phones can be part of an extension, and an extension can belong to an employee.

Request

This request will update an extension.

The whole object or as little as a single property can be set during an update, thus making all properties optional.

URL	https://api.telecomx.dk/pbx/extension/EXTENSION_ID
Method	POST
Access level	PERSONAL except for the following properties: number, employee, direct, primary, phonebook, noAnswer, busy, notes, autoMaster, inboundGoto, outbound.destinations, outbound.goto. MANAGER or OWNER if user belongs to the customer. RESELLER if customer belongs to the reseller. ADMIN.
params	EXTENSION_ID	Id of extension to update.
Body	customer	Id	Id of the customer the extension belongs to.
	name	String	Usage/function if not linked to an employee. If linked to an employee this is auto filled with the employees name.
	number	String	The phone number to dial to reach this extension.
	startAudio	Id	A sound item to playback when the extension is entered.
	redirect	String	Number to redirect to when execution starts. Used to quickly circumvent the extension.
	notes	String	Notes about the extension.
	employee	Id	Id of the employee who uses the extension, if any.
	direct	String	Direct number the extension can be called with from the outside.
	primary	Boolean	True if this is the primary extension of the employee.
	phonebook	Boolean	True if this extension must be included in the local phone book.
	callWaiting	Boolean	True to send calls to the extension even if it is already in a call.
	blockSecret	Boolean	If true, inbound calls with secret number will get rejected or caller will be prompted to reveal the phone number. Invalid phone numbers will also be treated like a secret number.
	billingCustomer	ObjectId	Alternate customer bill this extension to.
	autoMaster	Boolean	If true, this extension does not have to enter the master pincode when performing restricted actions.
	mobileUseOwnNumber	Boolean	If true, then calls made with a mobile phone will always present the mobile phones number on outbound calls.
	product	ObjectId	PBX_USER product assigned to this employee.
	startDate	Date	Date this employee will be billed from
	invoicedUntil	Date	When this employee is billed until
	Inbound call handling
	inboundGoto	Id	Dialplan item to send inbound calls to instead. Will only be invoked once pr. call.
	ringtone	Id	A music on hold category to use instead of a regular ringtone when the extension is called.
	musicOnHold	Id	Music on hold category to use in personal queue and when putting a call on hold.
	mobileDelay	Number	Number of seconds SIP phone(s) should ring before mobile phone(s) are also called. Valid values are: 0 (default), 3, 5, 8, 10, 15, 20, 25 or 30.
	onPresenceOffWork	String	What to do when presence state is OFF_WORK for the employee who owns the extension: AVAILABLE - accept call (default) BUSY - goto busy state handling BUSY_NOT_MOBILE - only accept calls from local or direct to mobile number BUSY_NOT_MOBILE_DIRECT - goto busy state handling, unless call is for mobile number directly WHITELIST - only accept calls from numbers on the whitelist WHITELIST_INT - only accept calls from numbers on the whitelist or from local callers
	onPresenceHoliday	String	What to do when presence state is HOLIDAY for the employee who owns the extension: AVAILABLE - accept call (default) BUSY - goto busy state handling BUSY_NOT_MOBILE - only accept calls from local or direct to mobile number BUSY_NOT_MOBILE_DIRECT - goto busy state handling, unless call is for mobile number directly WHITELIST - only accept calls from numbers on the whitelist WHITELIST_INT - only accept calls from numbers on the whitelist or from local callers
	onPresenceBusy	String	What to do when presence state is BUSY for the employee who owns the extension: AVAILABLE - accept call BUSY - goto busy state handling BUSY_NOT_MOBILE - goto busy state handling, unless call is for mobile number directly or from local BUSY_NOT_MOBILE_DIRECT - goto busy state handling, unless call is for mobile number directly WHITELIST - only accept calls from numbers on the extensions whitelist WHITELIST_INT - only accept calls from numbers on the extension whitelist or from local callers.
	noAnswer.timeout	Number	Number of seconds to ring the extension before timeout occurs, 5-60 seconds.
	noAnswer.extAction	String	Action to take when an external caller times out: NOTHING - keep ringing (default). VOICEMAIL - send to voicemail. NUMBER - divert to the phone number in noAnswer.extNumber. GOTO - jump to the dialplan item specified in noAnswer.extGoto.
	noAnswer.extNumber	String	Number to divert to when an external caller times out and action is NUMBER.
	noAnswer.extGoto	Id	Dialplan item to jump to when an external caller times out and action is GOTO.
	noAnswer.intAction	String	Action to take when a local caller times out: NOTHING - keep ringing (default). VOICEMAIL - send to voicemail. NUMBER - divert to the phone number in noAnswer.intNumber. GOTO - jump to the dialplan item specified in noAnswer.intGoto.
	noAnswer.intNumber	String	Number to divert to when a local caller times out and action is NUMBER.
	noAnswer.intGoto	Id	Dialplan item to jump to when a local caller times out and action is GOTO.
	noAnswer.mobileAction	String	What to do for direct to mobile calls on no answer: EXTERNAL - use settings from external NOTHING - keep ring without timeout (default) VOICEMAIL - send caller to voicemail NUMBER - send caller to number in noAnswer.mobileNumber GOTO - send to dialplan item in noAnswer.mobileGoto
	noAnswer.mobileNumber	String	Number to redirect caller to if noAnswer.mobileAction is NUMBER.
	noAnswer.mobileGoto	ObjectID	Id of dialplan object to send caller to if noAnswer.mobileAction is GOTO.
	busy.extAction	String	Action to take when an external caller calls and the extension is busy: BUSY - signal busy state/tone (default). VOICEMAIL - send to voicemail. NUMBER - divert to the phone number in busy.extNumber. GOTO - jump to the dialplan item specified in busy.extGoto. QUEUE - send caller to personal queue.
	busy.extNumber	String	Number to divert to when an external caller calls and the extension is busy and action is NUMBER.
	busy.extGoto	Id	Dialplan item to jump to when an external caller calls and the extension is busy and action is GOTO.
	busy.intAction	String	Action to take when a local caller calls and the extension is busy: BUSY - signal busy state/tone (default). VOICEMAIL - send to voicemail. NUMBER - divert to the phone number in busy.extNumber. GOTO - jump to the dialplan item specified in busy.extGoto. QUEUE - send caller to personal queue. BARGE - announce that the extension is busy but that the caller can press 1 to get through.
	busy.intNumber	String	Number to divert to when a local caller calls and the extension is busy and action is NUMBER.
	busy.intGoto	Id	Dialplan item to jump to when a local caller calls and the extension is busy and action is GOTO.
	busy.mobileAction	String	What to do for direct to mobile callers when busy: EXTERNAL - use settings from external BUSY - playback/signal BUSY VOICEMAIL - send caller to voicemail NUMBER - send caller to number in busy.mobileNumber GOTO - send to dialplan item in busy.mobileGoto QUEUE - send caller to personal queue
	busy.mobileNumber	String	Number to redirect caller to if busy.mobileAction is NUMBER.
	busy.mobileGoto	ObjectID	Id of dialplan object to send caller to if busy.mobileAction is GOTO.
	Outbound call handling
	outbound.destinations	String	Call restrictions when dialing out: ANY - can call any number NONE - cannot dial out LOCAL - can only dial local extensions NATIONAL - can only dial local extensions and nationals destinations.
	outbound.callerId.onPresenceWork	String	Number to present when making outbound calls. Choose from default PBX number, direct number, mobile phone number, a number on a trunk marked for sharing or `SECRET` to not present a number. Defaults to direct number or default PBX number.
	outbound.callerId.onPresenceWorkAsk	Boolean	If true, then the user gets the option to change to the number in outbound.callerId.onPresenceOffWork when calling out. A beep sounds and if the user press a key within 2 seconds, the callerId is changed.
	outbound.callerId.onPresenceOffWork	String	Number to present when making outbound calls. Choose from default PBX number, direct number, mobile phone number, a number on a trunk marked for sharing or `SECRET` to not present a number. Defaults to direct number or default PBX number.
	outbound.callerId.onPresenceOffWorkAsk	Boolean	If true, then the user gets the option to change to the number in outbound.callerId.onPresenceWork when calling out. A beep sounds and if the user press a key within 2 seconds, the callerId is changed.
	outbound.callerId.onNextCall	String	Number to present on next outbound call. Choose from default PBX number, direct number, mobile phone number, a number on a trunk marked for sharing or `SECRET` to not present a number. Ignored when null/blank.
	outbound.goto	Id	A dialplan item to goto when dialing out. Can be used to limit, redirect etc. the extension when making outbound calls. Default null.
	phones.sip	Array	`[optional]` Array of id's of SIP phones that belongs to the extension.
	phones.mvno	Array	`[optional]` Array of id's of MVNO accounts that belongs to the extension.
	phones.external	Array	`[optional]` Array of external phone numbers.

Request body example

{
  number: '703',
  startAudio: '12345789012345678ABCDEF',
  employee: '12345678901234567890AAAA',
  outbound: {
    destinations: 'ANY'
  }
}

Response

JSON object
_id	Id	Unique id of the extension.
type	String	Always 'EXTENSION'.
name	String	Name of employee who uses the extension, or usage/function if not linked to an employee.
number	String	The phone number to dial to reach this extension, null if it is not dial-able.
startAudio	Id	A sound item to playback when the extension is entered, null if not used.
redirect	String	Number to redirect to when execution starts. Used to quickly circumvent the extension.
notes	String	Notes about the extension.
employee	Id	Id of the employee who uses the extension, if any.
direct	String	Direct number the extension can be called with from the outside, null if none.
primary	Boolean	True if this is the primary extension of the employee.
phonebook	Boolean	True if this extension must be included in the local phone book.
callWaiting	Boolean	True to send calls to the extension even if it is already in a call.
blockSecret	Boolean	If true, inbound calls with secret number will get rejected or caller will be prompted to reveal the phone number. Invalid phone numbers will also be treated like a secret number.
billingCustomer	ObjectId	Alternate customer bill this extension to.
autoMaster	Boolean	If true, this extension does not have to enter the master pincode when performing restricted actions.
mobileUseOwnNumber	Boolean	If true, then calls made with a mobile phone will always present the mobile phones number on outbound calls.
product	ObjectId	PBX_EXTENSION product assigned to this extension.
startDate	Date	Date this extension will be billed from
invoicedUntil	Date	When this extension is billed until
Inbound call handling
inboundGoto	Id	Dialplan item to send inbound calls to instead. Will only be invoked once pr. call.
ringtone	Id	A music on hold category to use instead of a regular ringtone when the extension is called.
musicOnHold	Id	Music on hold category to use in personal queue and when putting a call on hold.
mobileDelay	Number	Number of seconds SIP phone(s) should ring before mobile phone(s) are also called. Valid values are: 0 (default), 3, 5, 8, 10, 15, 20, 25 or 30.
onPresenceOffWork	String	What to do when presence state is OFF_WORK for the employee who owns the extension: AVAILABLE - accept call BUSY - goto busy state handling BUSY_NOT_MOBILE - only accept calls from local or direct to mobile number BUSY_NOT_MOBILE_DIRECT - goto busy state handling, unless call is for mobile number directly WHITELIST - only accept calls from numbers on the whitelist WHITELIST_INT - only accept calls from numbers on the whitelist or from local callers
onPresenceHoliday	String	What to do when presence state is HOLIDAY for the employee who owns the extension: AVAILABLE - accept call BUSY - goto busy state handling BUSY_NOT_MOBILE - only accept calls from local or direct to mobile number BUSY_NOT_MOBILE_DIRECT - goto busy state handling, unless call is for mobile number directly WHITELIST - only accept calls from numbers on the whitelist WHITELIST_INT - only accept calls from numbers on the whitelist or from local callers
onPresenceBusy	String	What to do when presence state is BUSY for the employee who owns the extension: AVAILABLE - accept call BUSY - goto busy state handling BUSY_NOT_MOBILE - goto busy state handling, unless call is for mobile number directly or from local BUSY_NOT_MOBILE_DIRECT - goto busy state handling, unless call is for mobile number directly WHITELIST - only accept calls from numbers on the extensions whitelist WHITELIST_INT - only accept calls from numbers on the extension whitelist or from local callers.
noAnswer.timeout	Number	Number of seconds to ring the extension before timeout occurs, 5-60 seconds.
noAnswer.extAction	String	Action to take when an external caller times out: NOTHING - keep ringing. VOICEMAIL - send to voicemail. NUMBER - divert to the phone number in noAnswer.extNumber. GOTO - jump to the dialplan item specified in noAnswer.extGoto. Default NOTHING.
noAnswer.extNumber	String	Number to divert to when an external caller times out and action is NUMBER.
noAnswer.extGoto	Id	Dialplan item to jump to when an external caller times out and action is GOTO.
noAnswer.intAction	String	Action to take when a local caller times out: NOTHING - keep ringing. VOICEMAIL - send to voicemail. NUMBER - divert to the phone number in noAnswer.intNumber. GOTO - jump to the dialplan item specified in noAnswer.intGoto. Default NOTHING.
noAnswer.intNumber	String	Number to divert to when a local caller times out and action is NUMBER.
noAnswer.intGoto	Id	Dialplan item to jump to when a local caller times out and action is GOTO.
noAnswer.mobileAction	String	What to do for direct to mobile calls on no answer: EXTERNAL - use settings from external NOTHING - keep ring without timeout (default) VOICEMAIL - send caller to voicemail NUMBER - send caller to number in noAnswer.mobileNumber GOTO - send to dialplan item in noAnswer.mobileGoto
noAnswer.mobileNumber	String	Number to redirect caller to if noAnswer.mobileAction is NUMBER.
noAnswer.mobileGoto	ObjectID	Id of dialplan object to send caller to if noAnswer.mobileAction is GOTO.
busy.extAction	String	Action to take when an external caller calls and the extension is busy: BUSY - signal busy state/tone (default). VOICEMAIL - send to voicemail. NUMBER - divert to the phone number in busy.extNumber. GOTO - jump to the dialplan item specified in busy.extGoto. QUEUE - send caller to personal queue.
busy.extNumber	String	Number to divert to when an external caller calls and the extension is busy and action is NUMBER.
busy.extGoto	Id	Dialplan item to jump to when an external caller calls and the extension is busy and action is GOTO.
busy.intAction	String	Action to take when a local caller calls and the extension is busy: BUSY - signal busy state/tone (default). VOICEMAIL - send to voicemail. NUMBER - divert to the phone number in busy.extNumber. GOTO - jump to the dialplan item specified in busy.extGoto. QUEUE - send caller to personal queue. BARGE - announce that the extension is busy but that the caller can press 1 to get through.
busy.intNumber	String	Number to divert to when a local caller calls and the extension is busy and action is NUMBER.
busy.intGoto	Id	Dialplan item to jump to when a local caller calls and the extension is busy and action is GOTO.
busy.mobileAction	String	What to do for direct to mobile callers when busy: EXTERNAL - use settings from external BUSY - playback/signal BUSY VOICEMAIL - send caller to voicemail NUMBER - send caller to number in busy.mobileNumber GOTO - send to dialplan item in busy.mobileGoto QUEUE - send caller to personal queue
busy.mobileNumber	String	Number to redirect caller to if busy.mobileAction is NUMBER.
busy.mobileGoto	ObjectID	Id of dialplan object to send caller to if busy.mobileAction is GOTO.
Outbound call handling
outbound.destinations	String	Call restrictions when dialing out: ANY - can call any number NONE - cannot dial out LOCAL - can only dial local extensions NATIONAL - can only dial local extensions and nationals destinations.
outbound.callerId.onPresenceWork	String	Number to present when making outbound calls. Choose from default PBX number, direct number, mobile phone number, a number on a trunk marked for sharing or `SECRET` to not present a number. Defaults to direct number or default PBX number.
outbound.callerId.onPresenceWorkAsk	Boolean	If true, then the user gets the option to change to the number in outbound.callerId.onPresenceOffWork when calling out. A beep sounds and if the user press a key within 2 seconds, the callerId is changed.
outbound.callerId.onPresenceOffWork	String	Number to present when making outbound calls. Choose from default PBX number, direct number, mobile phone number, a number on a trunk marked for sharing or `SECRET` to not present a number. Defaults to direct number or default PBX number.
outbound.callerId.onPresenceOffWorkAsk	Boolean	If true, then the user gets the option to change to the number in outbound.callerId.onPresenceWork when calling out. A beep sounds and if the user press a key within 2 seconds, the callerId is changed.
outbound.callerId.onNextCall	String	Number to present on next outbound call. Choose from default PBX number, direct number, mobile phone number, a number on a trunk marked for sharing or `SECRET` to not present a number. Ignored when null/blank.
outbound.goto	Id	A dialplan item to goto when dialing out. Can be used to limit, redirect etc. the extension when making outbound calls. Default null.

Example

{
  _id: '12345678901234567890ABCD',
  type: 'EXTENSION',
  name: 'Donald Duck',
  number: '592',
  startAudio: null,
  redirect: null,
  notes: 'The boss',
  employee: '12345678901234567890AAAA',
  direct: '+4570305051',
  primary: true,
  phonebook: true,
  callWaiting: true,
  blockSecret: true,
  autoMaster: false,
  mobileUseOwnNumber: false,
  ringtone: '12345678901234567890BBBB',
  musicOnHold: '12345678901234567890CCCC',
  mobileDelay: 10,
  onPresenceOffWork: 'AVAILABLE',
  onPresenceHoliday: 'BUSY',
  onPresenceBusy: 'BUSY',
  startDate: ISODate('2022-03-31T23:00:00'),
  invoicedUntil: null,
  product: ObjectID('1234567890ABCD1234567890'),
  noAnswer: {
    timeout: 30,
    extAction: 'VOICEMAIL',
    extNumber: null,
    extGoto: null
    intAction: 'NUMBER',
    intNumber: '100',
    intGoto: null,
    mobileAction: 'EXTERNAL',
    mobileNumber: null,
    mobileGoto: null
  },
  busy: {
    extAction: 'QUEUE',
    extNumber: null,
    extGoto: null,
    intAction: 'NUMBER',
    intNumber: '100',
    intGoto: null,
    mobileAction: 'EXTERNAL',
    mobileNumber: null,
    mobileGoto: null
  },
  outbound: {
    destinations: 'NATIONAL',
    callerId: {
      onPresenceWork: '+4570305050',
      onPresenceWorkAsk: true,
      onPresenceOffWork: '+4571919998',
      onPresenceOffWorkAsk: true,
      onNextCall: null
    },
    goto: '123456789012345678901234'
  },
  phones: {
    sip: ['12345678901234567890AAAA'],
    mvno: ['1234567890124567890CCCC']
  }
}

Errors

Error code	Message	Description
400	bad_request	Id not found in request URI
404	not_found	Extension not found
404	customer	Customer not found or not active
422	name	Name must be at least 3 characters
409	number	Number is in use by another dialplan item
422	number	Number is invalid, only 0-9 is allowed and no public service numbers
422	redirect	Redirect number is invalid, only + 0-9, # and * is allowed
404	redirect	Redirect number is local but does not point to an existing dialplan item
404	startAudio	Start audio file not found
404	employee	Employee not found
403	direct	Number does not belong to customer
422	direct	The SIP account the number belongs to is not configured for hosted PBX usage
409	direct	Direct number is used by another extension or trunk
404	ringtone	The music on hold class does not exist
404	musicOnHold	The music on hold class does not exist
422	mobileDelay	Mobile delay is invalid - only 0, 3, 5, 8, 10, 15, 20, 25, 30 is allowed
409	onPresenceOffWork	Value is not one of the permitted values
409	onPresenceHoliday	Value is not one of the permitted values
409	onPresenceBusy	Value is not one of the permitted values
422	noAnswer.timeout	Invalid timeout - must be 5, 10, 15, 20, 25, 30, 45 or 60 seconds
422	noAnswer.extAction	Value is not one of the permitted values
422	noAnswer.intAction	Value is not one of the permitted values
422	noAnswer.mobileAction	Value is not one of the permitted values
422	noAnswer.extNumber	Not a valid phone number
422	noAnswer.extNumber	A valid phone number is required
404	noAnswer.extNumber	The number specified is local and not in use
422	noAnswer.intNumber	Not a valid phone number
422	noAnswer.intNumber	A valid phone number is required
404	noAnswer.intNumber	The number specified is local and not in use
422	noAnswer.mobileNumber	Not a valid phone number
422	noAnswer.mobileNumber	A valid phone number is required
404	noAnswer.mobileNumber	The number specified is local and not in use
404	noAnswer.extGoto	Dialplan item not found
404	noAnswer.intGoto	Dialplan item not found
404	noAnswer.mobileGoto	Dialplan item not found
422	busy.extAction	Value is not one of the permitted values
422	busy.intAction	Value is not one of the permitted values
422	busy.mobileAction	Value is not one of the permitted values
422	busy.extNumber	Not a valid phone number
404	busy.extNumber	The number specified is local and not in use
422	busy.extNumber	A valid phone number is required
422	busy.intNumber	Not a valid phone number
422	busy.intNumber	A valid phone number is required
404	busy.intNumber	The number specified is local and not in use
422	busy.mobileNumber	Not a valid phone number
404	busy.mobileNumber	The number specified is local and not in use
422	busy.mobileNumber	A valid phone number is required
404	busy.extGoto	Dialplan item not found
404	busy.intGoto	Dialplan item not found
404	busy.mobileGoto	Dialplan item not found
422	whitelist[]	Not a valid phone number
422	blacklist[]	Not a valid phone number
422	billingCustomer	An extension can not be assigned a billing customer, not assosciated with the extension's customer.
422	outbound.destinations	Value is not one of the permitted values
422	outbound.callerId.onPresenceWork	Not a valid phone number
422	outbound.callerId.onPresenceOffWork	Not a valid phone number
404	outbound.callerId.onPresenceWork	Number not found or not available
404	outbound.callerId.onPresenceOffWork	Number not found or not available
404	outbound.callerId.onNextCall	Number not found or not available
404	outbound.goto	Dialplan item not found
404	phones.sip[]	SIP Phone not found
404	phones.mvno[]	MVNO account not found
404	phones.mvno[]	MVNO account not configured for hosted PBX
403	access_denied	Insufficient access level
500	internal_error	<Unspecified>

WIKI

Table of Contents