API : PBX : Extension list

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 returns a list of all of the customers extensions.

URL	https://api.telecomx.dk/pbx/extension
Method	GET
Access level	PERSONAL if employee is provided and it is the user self. VIEWER, MANAGE, OWNER if extensions belongs to the customer. RESELLER if customer belongs to the reseller or ADMIN.
Query	offset	`[optional]` Index of the first item to return, default 0.
	limit	`[optional]` The number of items to return, default 50, min 1, max 1000.
	filter	`[optional]` Search query that will match against searchable fields.
	full	`[optional]` True to include all settings.
	expandGoto	`[optional]` True to expand goto id's into _id/type/number/name objects. Also sets full=true.
	customer	`[optional]` Id of customer to show extensions for. Defaults to the users own customer if not specified.
	employee	`[optional]` Id of employee to show extensions for.
	includePhones	`[optional]` True to include a list of the phones that belongs to each extension. Also sets full=true.
	sort	`[optional]` Which property to sort result by: number, name (default), redirect, direct, employee.

Query examples

https://api.telecomx.dk/pbx/extension
https://api.telecomx.dk/pbx/extension?customer=123458789012457890ABCD
https://api.telecomx.dk/pbx/extension?customer=123458789012457890ABCD&employee=1234567890123456780AAAA
https://api.telecomx.dk/pbx/extension?customer=123458789012457890ABCD&employee=1234567890123456780AAAA&includePhones=true
https://api.telecomx.dk/pbx/extension?filter=donald
https://api.telecomx.dk/pbx/extension?customer=12345678901234567890ABCD&full=true

Response

JSON object
offset	Index of the first extension returned.
limit	Number of extensions to return. Note that the actual number of returned items may be lower.
total	Number of extensions that can be returned when offset and limit is not considered. This is to be used for paging through the data.
extensions	Array of extensions, see definition below.

Extension object (normal)
_id	Id	Unique id of the 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.
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.
employeeDeleteDate	Date	Given if the employee of this extension is set to be deleted, and this extension will be deleted at the same time.
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.

Extension object (full=true)
_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.
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.
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 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 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.
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[].notes	string	Notes from the phone, if any.
phones[].online	Boolean	True if the phone is connect/not blocked.
phones[].dnd	Boolean	Current DND state of the phone.

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 - normal

{
  offset: 0,
  limit: 50,
  total: 25,
  extensions: [
    {
      _id: '12345678901234567890ABCD',
      name: 'Donald Duck',
      number: '592',
      redirect: null,
      notes: 'The boss',
      employee: '12345678901234567890AAAA',
      direct: '+4570305051',
      primary: true
    },
    {
      ...
    }
  ]

Example - full=true

{
  offset: 0,
  limit: 50,
  total: 25,
  extensions: [
    {
      _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',
      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
        },
        goto: '123456789012345678901234'
      }
    },
    {
      ...
    }
  ]

Errors

Error code	Message	Description
403	access_denied	Insufficient access level
500	internal_error	<Unspecified>

WIKI

Table of Contents