API : PBX : Groups list

API : PBX : Groups list

Introduction

A group contains a list of group members (extensions), and a list of controlling members (extensions). A group can be used for 3 purposes.

1. Simple call distribution

The group can be called, which in turn will call the groups members according to the chosen call distribution strategy.

2. Pickup, steal, spy

The controlling members can be permitted to:

Pickup a ringing phone from any group member, specifically or on the group.
Steal an ongoing call from any group member.
Listen in on an ongoing call by any group member (for coaching or monitoring purposes).

This can be done via API, star codes on phones or through programmable softkeys.

3. SetPresence, queueMember, viewOtherParty

Set presence for any group member.
Add/remove any member to any group.
See who any member is on a call with (number/name).

This is for use via Communicator apps.

Request

This request returns a list of all of the customers groups.

URL	https://api.telecomx.dk/pbx/group
Method	GET
Access level	PERSONAL (can only view groups the user is a controller on). VIEWER, MANAGE, OWNER if group 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.
	customer	`[optional]` Id of customer to show groups for. Defaults to the users own customer if not specified.
	sort	`[optional]` Sort by field: number (default), name, direct.
	expandExtension	`[optional]` True to expand members and controllers. Also sets full=true.
	expandGoto	`[optional]` True to expand goto id's into _id/type/number/name objects. Also sets full=true.

Query examples

https://api.telecomx.dk/pbx/group
https://api.telecomx.dk/pbx/group?customer=123458789012457890ABCD
https://api.telecomx.dk/pbx/group?filter=supporters
https://api.telecomx.dk/pbx/group?customer=12345678901234567890ABCD&full=true

Response

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

Group object (normal)
_id	Id	Unique id of the group.
name	String	Group name.
number	String	The phone number to dial to reach this group, null if it should not be dial-able.
redirect	String	Number to redirect to when execution starts. Used to quickly circumvent the group, e.g. redirect to a mobile.
notes	String	Notes about the group.
members	Number	Number of members in the group.
controllers	Number	Number of controllers in the group.
pickup	Boolean	True if controllers may pickup ringing phones in the group.
steal	Boolean	True if controllers may steal an ongoing call from a member extension.
spy	Boolean	True if controllers may listen in on an ongoing call on a member extension.
setPresence	Boolean	True if controllers may set presence for member extensions/employees.
queueMember	Boolean	True if controllers may add/remove member extensions from queues.
viewOtherParty	Boolean	True if controllers may see who member extensions are on a call with (number/name).
sms	Boolean	True if controllers may send group SMS to the groups members.
readCalendar	Boolean	True if controllers may read non-private events in members calendar.
writeCalendar	Boolean	True if controllers may create/update/delete events in members calendar.
readPhonebook	Boolean	True if controllers may read members phonebook.
writePhoneBook	Boolean	True if controllers may create/update/delete contacts in members phonebook.

Group object (full=true)
_id	Id	Unique id of the group.
customer	Id	Id of the customer the group belongs to.
name	String	Group name.
number	String	The phone number to dial to reach this group, null if it should not be dial-able.
startAudio	Id	A sound item to playback when the group is entered, null if not used.
redirect	String	Number to redirect to when execution starts. Used to quickly circumvent the group, e.g. redirect to a mobile.
notes	String	Notes about the group.
members	Array	The members of the group - extension id's.
controllers	Array	The controllers who may perform pickup, steal or spy on group members - extension id's.
pickup	Boolean	True if controllers may pickup ringing phones in the group.
steal	Boolean	True if controllers may steal an ongoing call from a member extension.
spy	Boolean	True if controllers may listen in on an ongoing call on a member extension.
setPresence	Boolean	True if controllers may set presence for member extensions/employees.
queueMember	Boolean	True if controllers may add/remove member extensions from queues.
viewOtherParty	Boolean	True if controllers may see who member extensions are on a call with (number/name).
sms	Boolean	True if controllers may send group SMS to the groups members.
readCalendar	Boolean	True if controllers may read non-private events in members calendar.
writeCalendar	Boolean	True if controllers may create/update/delete events in members calendar.
readPhonebook	Boolean	True if controllers may read members phonebook.
writePhoneBook	Boolean	True if controllers may create/update/delete contacts in members phonebook.
strategy	String	Call distribution strategy when the group is called: ALL - parallel ring all members. SEQUENTIAL - ring members one at a time for ringTime seconds. RANDOM - ring members one at a time in random order for ringTime seconds.
ringTime	Number	Number of seconds to ring before going to the next member, if strategy is SEQUENTIAL or RANDOM, otherwise time before going to timeout. 0 = ring forever.
timeoutGoto	Id	Id of diaplan item to goto when nobody answers within ringTime. Null if not used.

Members and Controllers items if expandExtension=true
_id	Id	Id of the extension.
number	String	The extensions phone number.
name	String	Name of the employee who uses the extension.

Goto items if expandGoto=true
_id	Id	Id of the dialplan item pointed to.
number	String	The number for the dialplan item.
type	String	Type of the dialplan item.
name	String	Name of the dialplan item.

Example - normal

{
  offset: 0,
  limit: 50,
  total: 25,
  groups: [
    {
      _id: '1234567890123457890ABCD',
      name: 'Support',
      number: '800',
      redirect: null,
      notes: 'Primary support ring group',
      members: 10,
      controllers: 1,
      pickup: true,
      steal: true,
      spy: false,
      setPresence: false,
      queueMember: true,
      viewOtherParty: false,
      sms: false,
      readCalendar: true,
      writeCalendar: false,
      readPhonebook: true,
      writePhonebook: false
    },
    {
      ...
    }
  ]

Example - full=true

{
  offset: 0,
  limit: 50,
  total: 25,
  groups: [
    {
      _id: '12345678901234567890ABCD',
      customer: '12345678901234567890AAAA',
      name: 'Support',
      number: '800',
      startAudio: null,
      notes: 'Primary support ring group',
      members: [ '123456789012345678900001', '123456789012345678900002'],
      controllers: [ '12345678901234567890AAAA' ],
      pickup: true,
      steal: true,
      spy: false,
      setPresence: false,
      queueMember: true,
      viewOtherParty: false,
      sms: false,
      readCalendar: true,
      writeCalendar: false,
      readPhonebook: true,
      writePhonebook: false,
      strategy: 'RANDOM',
      ringTime: 20,
      timeoutGoto: '1234567890123456890BBBB'
    },
    {
      ...
    }
  ]

Errors

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

Table of Contents