API : PBX : Group Update

API : PBX : Group Update

Introduction

A group contains a list of group members (extensions), and a list of controlling members (extensions). A group can be used for 2 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, sms

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

This is for use via Communicator apps.

Request

This request will update a group.

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/group/GROUP_ID
Method	POST
Access level	MANAGER or OWNER if user belongs to the customer. RESELLER if customer belongs to the reseller. ADMIN.
params	GROUP_ID	Id	Id of the group to update.
Body	customer	Id	Id of the customer the group belongs to.
	name	String	Group name.
	number	String	The local 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 dialplan item to goto when nobody answers within ringTime. Null if not used.

Request body example

{
  name: 'VIP support',
  number: '888'
}

Response

JSON object
_id	Id	Unique id of the group.
type	String	Always '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 dialplan item to goto when nobody answers within ringTime. Null if not used.

Example

{
  _id: '12345678901234567890ABCD',
  type: 'GROUP',
  customer: '12345678901234567890AAAA',
  name: 'VIP support',
  number: '888',
  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
400	bad_request	Id not found in request URI
422	name	Name must be at least 3 characters
403	number	Number is a protected public service number
409	number	Number is in use by another dialplan item
422	number	Number is invalid, only 0-9, # and * is allowed
404	customer	Customer not found or not active
404	startAudio	Start audio file not found
404	redirect	Redirect number is local but does not point to an existing dialplan item
422	redirect	Redirect number is invalid, only + 0-9, # and * is allowed
404	members[x]	Member extension not found
404	controllers[x]	Controller extension not found
404	timeoutGoto	Dialplan item not found
403	access_denied	Insufficient access level
500	internal_error	<Unspecified>

Table of Contents