API : PBX : Extension Get

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 return a single extension.

URL	https://api.telecomx.dk/pbx/extension/EXTENSION_ID
Method	GET
Access level	PERSONAL if extension belongs to the user, otherwise only _id, type, customer, name and number is visible. VIEWER, MANAGER or OWNER if user belongs to the customer. RESELLER if customer belongs to the reseller. ADMIN.
Param	EXTENSION_ID	Id of the extension (24 hex-char string)
Query	expandGoto	`[optional]` True to expand goto id's into _id/type/number/name objects
Query	includePhones	`[optional]` True to include the phones that are linked to the extension

Query examples

https://api.telecomx.dk/pbx/extension/1234567890ABCDEF12345678

Response

JSON object
_id	Id	Unique id of the extension.
type	String	Always 'EXTENSION'.
customer	Id	Id of the customer the extension belongs to.
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.
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.
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.
billingCustomer	ObjectID	Alternate customer to bill this extension to.
employeeDeleteDate	Date	Given if the employee of this extension is set to be deleted, and this extension will be deleted at the same time.
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 - 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.
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 - 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.
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.
If includePhones=true
phones	Array	List of phones that belongs to this extension.
phones._id	Id	Id of the phone (/pbx/sipphones id, /mvno id or external phone id).
phones.type	String	Type of phone: SIP, MVNO or EXTERNAL.
phones.model	String	Phone model - if available.
phones.identification	String	SIP phones: the MAC address if available else the notes. Mobile phones: the phone number. EXTERNAL: the phone number.
phones.online	Boolean	True if the phone is connect/not blocked.
phones.dnd	Boolean	Current DND state of the phone.
phones.notes	String	Notes field from the phone.
phones.product	Id	Id of product (type SIP only).
phones.ratePlan	Id	Id of rateplan (type MVNO only).
phones.newRatePlan	Id	Id of new rateplan (type MVNO only).

If expandGoto=true *goto properties are expanded to an object
_id	Id	Unique id of the dialplan item.
type	String	Type of item: EXTENSION - a local extension TRUNK - entry point for inbound calls CONFERENCE - a conference room where multiple parties can talk DIAL - dial a destination DISA - callback/dialtone PLAYBACK - play an audio file QUEUE - queue SET_VALUE - sets a value MENU_ROUTER - route based on menu selection TIME_ROUTER - route based on date/time URL_ROUTER - route based on URL call reply VALUE_ROUTER - route based on a value GROUP - a group of extensions that can be controlled and called.
name	String	Item name.
number	String	The phone number to dial to reach this item, null if it is not dial-able.

Example

{
  _id: '12345678901234567890ABCD',
  type: 'EXTENSION',
  customer: '12345678901234567890ADEF',
  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',
  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'
  }
}

Errors

Error code	Message	Description
400	bad_request	Id not found in requestURI
404	not_found	Extension not found
403	access_denied	Insufficient access level
500	internal_error	<Unspecified>

WIKI

Table of Contents