Conference Bridge Reference Guide

Getting Started

The CarrierX service offers a hosted conference bridge known as conference.

You will need to provision the Application Endpoint type conference in your account prior to accessing its API Reference Guide. For immediate help provisioning conference,


Quick Start Guide: How to Provision an Application Endpoint

Upon successful provisioning of your conference Application Endpoint, you may access the conference API using this base URL:


Base URL: https://api.carrierx.com/conference/v1

All data is sent and received in the JSON format and all of your API requests will require authentication.

Top Level Resources

As you begin to explore the API you will find a logical URL structure which helps you easily access all important resources within the Conference Bridge. The following resources are considered top level resources:

/subscribers
/meetingRooms
/callflows
/didGroups
/dids
/calls
/meetings

URL Structure Sample - Subscribers

Here is an example of how to format your url to perform a GET for all subscribers:

 GET https://api.carrierx.com/conference/v1/subscribers

Secondary Resources

In addition to your Top Level resources (listed above) are "Secondary Resources." These are resources that can be retrieved once you have executed a POST on Top Level resources.

For example:

/subscribers/247/meetingRooms
/subscribers/247/meetingRooms/283848/keychain
/meetings/283848/attributes

The above formatted urls are examples of requests that can be made once the system has assigned unique identifiers for a Subscriber, for meetingrooms or for a specific meeting number.

Understanding a Subscriber

A Subscriber is either a real person or an organization that is registered on your conference bridge. A Subscriber will have the following attributes:

have a name, or a phone number, or an e-mail address - perhaps all the above,
may have meeting room information,
does not have access codes,
has reference information to another Subscriber that was responsible for creating it, thus defining its hierarchy.

Important:

1. A Subscriber that does not have a parent is referred to as an Administrator.

2. All other Subscriber types are considered "non-admin" types (non-operator) and are only able to see their "own" information, or the information of subordinates (such as calls, meetings, reports, etc) that were created as dependents.

3. Access codes are properties of meeting keys, which belong to a meeting room, that in turn belongs to a Subscriber.

Get List of Subscribers

This call will return the list of subscribers matching the filter criteria; the list is provided according to the specified order; offset and limit parameters help to implement paging on the web application; includeFields and excludeFields define what fields should be included or excluded from the output.

Note: field meetingRooms will be populated with the list of meeting rooms this subscriber is associated with and can possibly attend.

METHOD	URL
GET	/subscribers

Sample URL


curl -X GET --header "Accept: application/json;qs=1"  -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/subscribers?offset=0&limit=20&order=login&excludeFields=meetingRooms"

Request Parameters

Parameter	Data Type	Description
offset	integer	Amount of items to be skipped in the response. Default value is `0`
limit	integer	Number of items to be shown in the response. The value should not exceed 1000. Default value is `10`
filter	string	Specify filter for the items in the response. Example: role eq 3 Supported operations are (eq, ne, gt, ge, lt, le, and, like, ilike) Several filters can be combined together. Example: role eq 3 and login like 'Test%'.
order	string	Specifying any single subscriber field name and sort direction. Empty string or null or no order parameter specified means no order. The default direction is ascending and asc can be omitted, for descending order use desc.
includeFields	string	Comma separated list of fields that should be included in the response
excludeFields	string	Comma separated list of fields that should be excluded from the response

Sample Response

 {
  "authenticationToken": "MjAyODU2NDU3MA==",
  "created": 1478704919000,
  "didGroupReferences": [
      {
         "didGroupId": 116,
         "state": 0
      }
  ],
  "externalId": -1,
  "login": "2_conference_859",
  "parentSid": "a2Jy91nOnvfAYY32q-dtzRSbt-X3ykOf",
  "role": 3,
  "sid": "a3r691jarPcaPym1ZSZeKSak52wAMztZ"
}

Response Parameters

Attribute	Data Type	Description
authenticationToken `opt`	string	Subscriber’s authentication token (encrypted analogue of password), i.e. security token used to prove subscriber’s identity; the token is generated by the bridge on update of the user’s password. There are 2 ways to authenticate the subscriber: login, password pair sid /authenticationToken pair The token is used in addition to or in place of a password to prove that the subscriber is who he claims to be
created `opt`	integer	Date and time when the record was created; assigned by the server
email	string	Subscriber’s e-mail, the length is 64 characters max
externalID	integer	Subscriber identifier in external system
firstName	string	Subscriber real first name, max length is 50 characters
lastName	string	Subscriber real last name, max length is 50 characters
login	string	Login to access the web interface and web services API (*): 50 characters max; should be unique among all subscribers on the server; if used to identify subscriber in a call flow, should consist of digits.
parentSid	string	Secure ID of the parent subscriber
password	string	Password to log into the web interface and API: 20 characters max; only used during object creation and never returned as a plain text
phoneNumber	string	Subscriber’s phone number used if server needs to dial-out to this subscriber, max length is 24 characters
role	integer	Subscriber’s role. Possible values: 1 – admin 2 – operator 3 – user
didGroupReference	array	References to DID groups with the phone numbers to be dialed to enter the given Meeting
ext	string	Extension (max 24 characters)
details	string	Additional information (max 256 characters)
callback	object	Callback object. For more details, refer to the Callback section
meetingRooms	array	Meeting rooms this subscriber can possibly attend. Refer to MeetingRoom section for more details.

Callback Object

Attribute	Data Type	Description
id	integer	Callback ID
url	string	External URL to be called when an event associated to this subscription is fired; contains URL to send push-notifications when the subscriber’s meetings started. Example: https://bin.conference.com/logger When the event occurs, the server makes http-post to the specified URL and transfers there the event information in json-format containing: date/time when the event occurred; meeting number that has the event; source of the event; details about the meeting event (e.g. the meeting was started or ended, the call was started or ended, the recording was started or stopped, etc.)
urlToNotify	string	External URL to be called when an event associated to this subscription is fired, and the push-notification failed to reach the url.

DidGroupReferences

DidGroupReference (DID Group Reference) class represents the set of didGroupId (DID group identifier) and its state. The array of these references is used to determine DID groups with the phone numbers to be dialed to enter the given meeting (Meeting Room)

Attribute	Data Type	Description
didGroupId	integer	DID Group ID
state	integer	State of the DID Group. Possible values: 0 – active (default) 1 – invalidated 2 – disabled

Get Subscriber by SID

This method returns full details for the subscriber referenced by the secure ID {sid}

METHOD	URL
GET	/subscribers/{sid}

Sample URL


curl -X GET --header "Accept: application/json" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/subscribers/sd-e9wDzBfezItzjykxK7sF2Jof-A-Yw?excludeFields=meetingRooms"

Request Parameters

Parameter	Data Type	Description
sid `req`	string	Subscriber secure ID
includeFields	string	Comma separated list of fields that should be included into the response
excludeFields	string	Comma separated list of fields that should be excluded from the response

Sample Response

 {
  "authenticationToken": "com.conference.model.string.default",
  "created": 1474448652000,
  "didGroupReferences": [],
  "externalId": -1,
  "firstName": "Oleksii",
  "lastName": "Sapon",
  "login": "alexiuscrow",
  "parentSid": "a2Jy91nOnvfAYY32q-dtzRSbt-X3ykOf",
  "role": 3,
  "sid": "irww9-Vq7vczQzTfXmc0q8zIH.TEe3Qm"
}

Response Parameters

Attribute	Data Type	Description
authenticationToken `opt`	string	Subscriber’s authentication token (encrypted analogue of password), i.e. security token used to prove subscriber’s identity; the token is generated by the bridge on update of the user’s password. There are 2 ways to authenticate the subscriber: login, password pair sid /authenticationToken pair The token is used in addition to or in place of a password to prove that the subscriber is who he claims to be
created `opt`	integer	Date and time when the record was created; assigned by the server
email	string	Subscriber’s e-mail, the length is 64 characters max
externalID	integer	Subscriber identifier in external system
firstName	string	Subscriber real first name, max length is 50 characters
lastName	string	Subscriber real last name, max length is 50 characters
login	string	Login to access the web interface and web services API (*): 50 characters max; should be unique among all subscribers on the server; if used to identify subscriber in a call flow, should consist of digits.
parentSid	string	Secure ID of the parent subscriber
password	string	Password to log into the web interface and API: 20 characters max; only used during object creation and never returned as a plain text
phoneNumber	string	Subscriber’s phone number used if server needs to dial-out to this subscriber, max length is 24 characters
role	integer	Subscriber’s role. Possible values: 1 – admin 2 – operator 3 – user
didGroupReference	array	References to DID groups with the phone numbers to be dialed to enter the given Meeting
ext	string	Extension (max 24 characters)
details	string	Additional information (max 256 characters)
callback	object	Callback object. For more details, refer to the Callback section
meetingRooms	array	Meeting rooms this subscriber can possibly attend. Refer to MeetingRoom section for more details.

Create a New Subscriber

This call creates a new Subscriber with details posted in the data input parameter. The mandatory fields are: login, password, and role.

METHOD	URL
POST	/subscribers/

Sample URL


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -u <your_user_name>:<your_password> -d "{"firstName":"John", "lastName":"Smith", "login":"JE", "phoneNumber":"9197473626", "password":"test", "role":3}" "https://api.carrierx.com/conference/v1/subscribers"

Request Parameters

Parameter	Data Type	Description
sid `req`	string	Subscriber secure ID
includeFields	string	Comma separated list of fields that should be included into the response
excludeFields	string	Comma separated list of fields that should be excluded from the response

Sample Response

 {
  "authenticationToken": "com.conference.model.string.default",
  "created": 1474448652000,
  "didGroupReferences": [],
  "externalId": -1,
  "firstName": "John",
  "lastName": "Smith",
  "login": "JE",
  "parentSid": "a2Jy91nOnvfAYY32q-dtzRSbt-X3ykOf",
  "role": 3,
  "sid": "117m9wPOOPdZvnK3dF5TqrJwRHLPpaBv"
}

Response Parameters

Attribute	Data Type	Description
authenticationToken `opt`	string	Subscriber’s authentication token (encrypted analogue of password), i.e. security token used to prove subscriber’s identity; the token is generated by the bridge on update of the user’s password. There are 2 ways to authenticate the subscriber: login, password pair sid /authenticationToken pair The token is used in addition to or in place of a password to prove that the subscriber is who he claims to be
created `opt`	integer	Date and time when the record was created; assigned by the server
email	string	Subscriber’s e-mail, the length is 64 characters max
externalID	integer	Subscriber identifier in external system
firstName	string	Subscriber real first name, max length is 50 characters
lastName	string	Subscriber real last name, max length is 50 characters
login	string	Login to access the web interface and web services API (*): 50 characters max; should be unique among all subscribers on the server; if used to identify subscriber in a call flow, should consist of digits.
parentSid	string	Secure ID of the parent subscriber
password	string	Password to log into the web interface and API: 20 characters max; only used during object creation and never returned as a plain text
phoneNumber	string	Subscriber’s phone number used if server needs to dial-out to this subscriber, max length is 24 characters
role	integer	Subscriber’s role. Possible values: 1 – admin 2 – operator 3 – user
didGroupReference	array	References to DID groups with the phone numbers to be dialed to enter the given Meeting
ext	string	Extension (max 24 characters)
details	string	Additional information (max 256 characters)
callback	object	Callback object. For more details, refer to the Callback section
meetingRooms	array	Meeting rooms this subscriber can possibly attend. Refer to MeetingRoom section for more details.

Update an Existing Subscriber

This call updates an existing subscriber referenced by the security identifier {sid} with the new information posted in the data input parameter. Note: get the subscriber info first, change some info and then call this method to update the information.

METHOD	URL
PUT	/subscribers/{sid}

Sample URL


curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json"  -u <your_user_name>:<your_password> -d "{"password":"JE123"}" "https://api.carrierx.com/conference/v1/subscribers/117m9wPOOPdZvnK3dF5TqrJwRHLPpaBv"

Request Parameters

Parameter	Data Type	Description
sid `req`	string	Subscriber secure ID
data	string	The Subscriber object properties: sid (can be omitted, but if specified must match to {sid} from the PUT URL), details, email, firstName, lastName, login (), parented (), password (), phoneNumber, role (), meetingRooms (if you would like to update subscriber’s meeting rooms for the subscriber)

Sample Response

 {
  "authenticationToken": "com.conference.model.string.default",
  "created": 1474448652000,
  "didGroupReferences": [],
  "externalId": -1,
  "firstName": "John",
  "lastName": "Smith",
  "login": "JE",
  "parentSid": "a2Jy91nOnvfAYY32q-dtzRSbt-X3ykOf",
  "role": 3,
  "sid": "117m9wPOOPdZvnK3dF5TqrJwRHLPpaBv"
}

Response Parameters

Attribute	Data Type	Description
authenticationToken `opt`	string	Subscriber’s authentication token (encrypted analogue of password), i.e. security token used to prove subscriber’s identity; the token is generated by the bridge on update of the user’s password. There are 2 ways to authenticate the subscriber: login, password pair sid /authenticationToken pair The token is used in addition to or in place of a password to prove that the subscriber is who he claims to be
created `opt`	integer	Date and time when the record was created; assigned by the server
email	string	Subscriber’s e-mail, the length is 64 characters max
externalID	integer	Subscriber identifier in external system
firstName	string	Subscriber real first name, max length is 50 characters
lastName	string	Subscriber real last name, max length is 50 characters
login	string	Login to access the web interface and web services API (*): 50 characters max; should be unique among all subscribers on the server; if used to identify subscriber in a call flow, should consist of digits.
parentSid	string	Secure ID of the parent subscriber
password	string	Password to log into the web interface and API: 20 characters max; only used during object creation and never returned as a plain text
phoneNumber	string	Subscriber’s phone number used if server needs to dial-out to this subscriber, max length is 24 characters
role	integer	Subscriber’s role. Possible values: 1 – admin 2 – operator 3 – user
didGroupReference	array	References to DID groups with the phone numbers to be dialed to enter the given Meeting
ext	string	Extension (max 24 characters)
details	string	Additional information (max 256 characters)
callback	object	Callback object. For more details, refer to the Callback section
meetingRooms	array	Meeting rooms this subscriber can possibly attend. Refer to MeetingRoom section for more details.

Remove and Existing Subscriber

Deletes specific subscriber referenced by the {sid} and all his subordinate meeting rooms from the server.

METHOD	URL
DELETE	/subscribers/{sid}

Sample URL


curl -X DELETE --header "Accept: application/json" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/subscribers/117m9wPOOPdZvnK3dF5TqrJwRHLPpaBv"

Request Parameters

Parameter	Data Type	Description
sid `req`	string	Subscriber secure ID

Delete Media Resources

Deletes several media files for the specified Subscriber.

METHOD	URL
DELETE	/subscribers/{sid}/files

Sample URL


curl -X DELETE --header "Content-Type: application/json" --header "Accept: application/json" -u <your_user_name>:<your_password> -d "["FirstFile.mp3","SecondFile.mp3"]" "https://api.carrierx.com/conference/v1/subscribers/Dv4Z9xKWlvfL-OXKhcTPxDUj3HjAvucN/files"

Request Parameters

Parameter	Data Type	Description
sid `req`	string	Subscriber secure ID
body	string	Audio files to be removed

Get List of Media Resources

This call returns the list of media resources for the specified Subscriber in the indicated order.

METHOD	URL
GET	/subscribers/{sid}/files

Sample URL


curl -X GET --header "Accept: application/json;qs=1" -u <your_user_name>:<your_password> https://api.carrierx.com/conference/v1/subscribers/do3x9.WkIfcEO.-wYlWdFseo.TF1nwYx?excludeFields=meetingRooms"

Request Parameters

Parameter	Data Type	Description
sid `req`	string	Subscriber secure ID
order	string	Order of items in the response. Example: size desc

Sample Response

 {
  "fileDescriptors": [
      {
          "date": 1473840790000,
          "duration": 26112,
          "name": "CommanderAustralia.mp3",
          "size": 1044480,
          "url": "/storage/subscribers/a2Jy91nOnvfAYY32q-dtzRSbt-X3ykOf/CommanderAustralia.mp3"
      }
  ],
  "last": 0,
  "offset": 0,
  "total": 1
}

Response Parameters

Attribute	Data Type	Description
date	integer	Date when the file was uploaded
duration	integer	Duration of the file
name	string	File name
size	integer	File size
url	string	URL to the file location

Upload Media File

This call uploads the media files for the specified subscriber.

METHOD	URL
POST	/subscribers/{sid}/files

Sample URL


curl -X POST --header "Content-Type: multipart/form-data" --header "Accept: application/json" -u <your_user_name>:<your_password> https://api.carrierx.com/conference/v1/subscribers/GS9o9wJa1fet4uPL2mveShfKDvt6iQFW/files

Request Parameters

Parameter	Data Type	Description
sid `req`	string	Subscriber secure ID
file	file	Media file to be uploaded for the specified subscriber

Delete Media File

This call uploads the media files for the specified subscriber.

METHOD	URL
DELETE	/subscribers/{sid}/files/{fileName}

Sample URL


curl -X DELETE --header "Accept: application/json" -u -u <your_user_name>:<your_password> "https:// /subscribers/GS9o9wJa1fet4uPL2mveShfKDvt6iQFW/files/1.mp3"

Request Parameters

Parameter	Data Type	Description
sid `req`	string	Subscriber secure ID
file	string	Name of the file to be removed.

Meeting Rooms

Meeting Room data structure is designed to uniquely identify the meeting, and is used to manage the meeting attributes. Meeting room is part of subscriber definition (the meeting room info always belongs to the subscriber). Each subscriber can have multiple meeting rooms, i.e. meetings the subscriber can attend.

Meeting Room:

represents subscriber’s meeting configuration and contains the meeting number;
defines overridden call flow attributes values exposed by the primary DID group attributes (the attribute's group for meeting’s attributes is equal to MEETING, see details in section CallFlow’s Attribute);
contains the meeting keys information representing access code, role that could be used, and references to DID groups to join the concrete meeting.
NOTE: MeetingRoom object can exist only if there is a subscriber that owns this meeting room, and if this meeting room has a meeting number that is referred by him.

NOTE: The meeting number must be unique across the bridge; different subscribers cannot have the meeting rooms with the same meeting number.

NOTE: The subscriber deletion performs cascade deletion of all associated meeting room records. Additionally, it is possible to override some attributes exposed by default callflow so this meeting room info can define a customized behavior.

Get List of Meeting Rooms

Returns the list of all meeting rooms that match the filter and are provided according to the specified order; offset and limit parameters help to implement paging on the web application; includeFields and excludeFields parameters define what fields should be included or excluded from the output.

METHOD	URL
GET	/meetingRooms

Sample URL


curl -X GET --header "Accept: application/json;qs=1" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/meetingRooms?offset=0&limit=20&order=meetingNumber&excludeFields=attributes"

Request Parameters

Parameter	Data Type	Description
offset	integer	Amount of items to be skipped in the response. Default value is `0`
limit	integer	Number of items to be shown in the response. The value should not exceed 1000. Default value is `10`
filter	string	Specify filter for the items in the response. Example: primaryDidGroupId eq 1 Supported operations are (eq, ne, gt, ge, lt, le, and, like, ilike) Several filters can be combined together. Example: primaryDidGroupId eq 1 and description ilike '%Test%'
order	string	Specifying any single subscriber field name and sort direction. Empty string or null or no order parameter specified means no order. The default direction is ascending and asc can be omitted, for descending order use desc.
includeFields	string	Comma separated list of fields that should be included in the response
excludeFields	string	Comma separated list of fields that should be excluded from the response

Sample Response

    {
          "description": "main test",
          "didGroupReferences": [
              {
                  "didGroupId": 1,
                  "state": 0
              }
          ],
          "keychain": [
              {
                  "accessCode": "2472",
                  "id": 2,
                  "role": 2
              },
              {
                  "accessCode": "2471",
                  "id": 1,
                  "role": 1
              }
          ],
          "meetingNumber": 247,
          "primaryDidGroupId": 1,
          "subscriberSid": "zW3y9-50f-f-bxT1aKAbnOSFiwgXgsZo"
      }

Response Parameters

Attribute	Data Type	Description
attributes	array	List of attributes and their values imposed by the call flow of the primary DID group this meeting is assigned to; the attribute's group for them is equal to MEETING. These attributes are used to override (overwrite) their values for this particular meeting room or the values taken from parent or defaults; they specify MeetingRoom behavior
description	string	Description of the meeting; if meetingNumber is omitted, holds new meeting description; the length is 256 characters max
DidGroupReference	array	References to DID groups with the phone numbers to be dialed to enter the given Meeting.
keychain	array	List of meeting keys (credentials: sets of role and access code to be used to enter the given MeetingRoom. See the MeetingKey section.
meetingNumber	integer	Number of the meeting to which this user will be assigned after successful authentication. It should be unique across other meeting numbers; 0 means create a new one
primaryDidGroupId	integer	ID of the primary DID Group object that this meeting room is associated with, the primary DID Group defines the set of available call flow attributes overridden for the meeting defined by the meeting room
subscriberSid	string	The security identifier of the subscriber this meeting room is associated with, i.e. the sid of the subscriber that owns this meeting room

Create a New Meeting Room

This call will create a new meeting room with the details posted in the data input parameter.

METHOD	URL
POST	/meetingRooms

Sample URL


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -u <your_user_name>:<your_password> -d "{"meetingNumber":156156, "callFlowId":2, "primaryDidGroupId": 1}" "https://api.carrierx.com/conference/v1/meetingRooms"

Request Parameters

Sample Response

{
  "attributes": [],
  "didGroupReferences": [
      {
          "didGroupId": 1,
          "state": 0
      }
  ],
  "keychain": [],
  "meetingNumber": 156156,
  "primaryDidGroupId": 1,
  "subscriberSid": "a2Jy91nOnvfAYY32q-dtzRSbt-X3ykOf"
}

Response Parameters

Attribute	Data Type	Description
attributes	array	List of attributes and their values imposed by the call flow of the primary DID group this meeting is assigned to; the attribute's group for them is equal to MEETING. These attributes are used to override (overwrite) their values for this particular meeting room or the values taken from parent or defaults; they specify MeetingRoom behavior
description	string	Description of the meeting; if meetingNumber is omitted, holds new meeting description; the length is 256 characters max
DidGroupReference	array	References to DID groups with the phone numbers to be dialed to enter the given Meeting.
keychain	array	List of meeting keys (credentials: sets of role and access code to be used to enter the given MeetingRoom. See the MeetingKey section.
meetingNumber	integer	Number of the meeting to which this user will be assigned after successful authentication. It should be unique across other meeting numbers; 0 means create a new one
primaryDidGroupId	integer	ID of the primary DID Group object that this meeting room is associated with, the primary DID Group defines the set of available call flow attributes overridden for the meeting defined by the meeting room
subscriberSid	string	The security identifier of the subscriber this meeting room is associated with, i.e. the sid of the subscriber that owns this meeting room

Remove a Meeting Room

Deletes specific meeting room referenced by the meeting number {meetingNumber} and all its subordinate meeting keys from the server.

Note: All assigned confUsers will be deleted too.

METHOD	URL
DELETE	/meetingRooms/{meetingNumber}

Sample URL


curl -X DELETE --header "Accept: application/json" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/meetingRooms/452650

Request Parameters

Parameter	Data Type	Description
meetingNumber `req`	integer	Meeting number of the meeting room that should be deleted

Get Meeting Room by ID

Returns the full details about the single meeting room referenced by the meeting number.

METHOD	URL
DELETE	/meetingRooms/{meetingNumber}/

Sample URL


curl -X GET --header "Accept: application/json;qs=1" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/meetingRooms/156156?excludeFields=attributes"

Response Parameters

Parameter	Data Type	Description
meetingNumber	integer	Meeting number of the meeting room

Sample Response

 {
  "attributes": [],
  "description": "Another description",
  "didGroupReferences": [
      {
          "didGroupId": 1,
          "state": 0
      }
  ],
  "keychain": [],
  "meetingNumber": 156156,
  "primaryDidGroupId": 1,
  "subscriberSid": "a2Jy91nOnvfAYY32q-dtzRSbt-X3ykOf"
}

Response Parameters

Attribute	Data Type	Description
attributes	array	List of attributes and their values imposed by the call flow of the primary DID group this meeting is assigned to; the attribute's group for them is equal to MEETING. These attributes are used to override (overwrite) their values for this particular meeting room or the values taken from parent or defaults; they specify MeetingRoom behavior
description	string	Description of the meeting; if meetingNumber is omitted, holds new meeting description; the length is 256 characters max
DidGroupReference	array	References to DID groups with the phone numbers to be dialed to enter the given Meeting.
keychain	array	List of meeting keys (credentials: sets of role and access code to be used to enter the given MeetingRoom. See the MeetingKey section.
meetingNumber	integer	Number of the meeting to which this user will be assigned after successful authentication. It should be unique across other meeting numbers; 0 means create a new one
primaryDidGroupId	integer	ID of the primary DID Group object that this meeting room is associated with, the primary DID Group defines the set of available call flow attributes overridden for the meeting defined by the meeting room
subscriberSid	string	The security identifier of the subscriber this meeting room is associated with, i.e. the sid of the subscriber that owns this meeting room

Update the Existing Meeting Room

Updates existing meeting room referenced by the meeting number {meetingNumber} provided with the new information posted in the data input parameter. Please make sure you filled all information that needs to be in the updated meeting room. Recommendation is to get the meeting room info first, change some info and then call this method to update the information

METHOD	URL
GET	/meetingRooms/{meetingNumber}

Sample URL


curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json" -u <your_user_name>:<your_password> -d "{"description":"Another description"}" "https://api.carrierx.com/conference/v1/meetingRooms/156156"

Request Parameters

Parameter	Data Type	Description
meetingNumber `req`	integer	The meeting number of the meeting room that should be updated
data	string	Fields to update

Sample Response

 {
  "attributes": [],
  "description": "Another description",
  "didGroupReferences": [
      {
          "didGroupId": 1,
          "state": 0
      }
  ],
  "keychain": [],
  "meetingNumber": 156156,
  "primaryDidGroupId": 1,
  "subscriberSid": "a2Jy91nOnvfAYY32q-dtzRSbt-X3ykOf"
}

Response Parameters

Attribute	Data Type	Description
attributes	array	List of attributes and their values imposed by the call flow of the primary DID group this meeting is assigned to; the attribute's group for them is equal to MEETING. These attributes are used to override (overwrite) their values for this particular meeting room or the values taken from parent or defaults; they specify MeetingRoom behavior
description	string	Description of the meeting; if meetingNumber is omitted, holds new meeting description; the length is 256 characters max
DidGroupReference	array	References to DID groups with the phone numbers to be dialed to enter the given Meeting.
keychain	array	List of meeting keys (credentials: sets of role and access code to be used to enter the given MeetingRoom. See the MeetingKey section.
meetingNumber	integer	Number of the meeting to which this user will be assigned after successful authentication. It should be unique across other meeting numbers; 0 means create a new one
primaryDidGroupId	integer	ID of the primary DID Group object that this meeting room is associated with, the primary DID Group defines the set of available call flow attributes overridden for the meeting defined by the meeting room
subscriberSid	string	The security identifier of the subscriber this meeting room is associated with, i.e. the sid of the subscriber that owns this meeting room

Call Flows

Call flow is a unique meeting service setup registered on the bridge, the logic that is used to process the meeting calls. This is the process a call goes through from call setup to processing, and tear down. It includes the logic, DTMF key-presses used, functions, and the recorded prompts. Each script takes several parameters (like welcome prompt). Call flows cannot be dynamically created by user as they need to be put into the proper place on the file system and need to be configured by administrator. However, end-user should be able to change attributes of already registered call flows in order to customize their behavior.

The set of attributes depends on the callflow. So when a user calls the meeting DID, it gets attributes exposed by the call flow. Some of these attributes can be already altered by the DID Group and DID. After the user has provided his access code and his authentication has succeeded, some attributes can be overwritten again by the attributes of the primary DID Group assigned to the meeting room (MeetingRoom) where the user was authorized and by the attributes of this meeting room.

NOTE: list of attributes is always defined by a call flow. Values of any attribute may be overwritten by DID Group and MeetingRoom’s primary DID Group; depending on the attribute’s group (see below) its value could be also overridden by DID or Meeting Room.

The hierarchy of the call flow attributes values is either formed as:

Call Flow -> DID Group -> DID

or it is formed as:

Call Flow -> Meeting Room’s Primary DID Group -> Meeting Room

Each attribute can be allowed or disallowed for modification by the administrator. The group property of the Attribute defines level what the attribute can be overridden at. The call flow offers default values for each attribute.
For each specific attribute its value usually could be overridden:

either at DID Group -> DID level (group property equals to 3 in this case)
or
at Meeting Room’s Primary DID Group -> Meeting Room level (group property equals to 5 in this case)

Each attribute has name, type and value. Depending on the type, web application should apply one or another validation rule. Also attribute has a "role" so meeting room info can only "see" those attributes which role matches their own role.

Get List of Call Flows

Returns the list of call flows which match the filter provided according to the specified order; offset and limit parameters help to implement paging on the web application; includeFields and excludeFields parameters define what fields should be included or excluded from the output.

METHOD	URL
GET	/callFlows

Sample URL


curl -X GET --header "Accept: application/json;qs=1" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/callFlows?offset=0&limit=20&excludeFields=attributeTemplates

Request Parameters

Parameter	Data Type	Description
offset	integer	Amount of items to be skipped in the response. Default value is `0`
limit	integer	Number of items to be shown in the response. The value should not exceed 1000. Default value is `10`
filter	string	Specify filter for the items in the response. Example: name like 'PL%' Supported operations are (eq, ne, gt, ge, lt, le, and, like, ilike) Several filters can be combined together. Example: id gt 0 and id lt 5
order	string	Specifies order of items in the response: `asc`, `desc` Example: `id desc` The default order is ascending.
include_fields	string	Comma separated list of fields that should be included in the response
exclude_fields	string	Comma separated list of fields that should be excluded from the response

Sample Response

 {
  "callFlows": [
      {
          "id": 2,
          "name": "CONF",
          "path": "/usr/local/DNCA/callflows/CONF"
      },
      {
          "id": 4,
          "name": "SPECTEL",
          "path": "/usr/local/DNCA/callflows/SPECTEL"
      },
      {
          "id": 3,
          "name": "PLAYBACK",
          "path": "/usr/local/DNCA/callflows/PLAYBACK"
      },
      {
          "id": 1,
          "name": "OPERATOR",
          "path": "/usr/local/DNCA/callflows/OPERATOR"
      }
  ],
  "last": 3,
  "offset": 0,
  "total": 4
}

Response Parameters

Attribute	Data Type	Description
description	string	Description of the attribute
enumValues	string	If type is Enum, i.e. TYPE_CHOICE (5L), this variable holds possible choices like choice1,choice2,choice3 (for example on,off), this is read-only field populated by server
group	integer	Meeting access group (role) bitmask flag this attribute belongs to (i.e. the owner of the attribute) consisting of 3 bits for Call Flow / DID Group, DID, and Meeting Room (); and each of these bits determines at what level the call flow attribute value could be overridden or not: bit 0 (CallFlow and DidGroup) – 0 (02) value of this flag determines that the call flow attribute could not be overridden for call flow and DID group, 1 (12) value of this flag determines that the call flow attribute could be overridden for call flow and DID group; bit 1 (Did) – 0 (02) value of this flag determines that the call flow attribute could not be overridden for DID, 1 (12) value of this flag determines that the call flow attribute could be overridden for DID; bit 2 (MeetingRoom) – 0 (02) value of this flag determines that the call flow attribute could not be overridden for Meeting Room, 1 (12) value of this flag determines that the call flow attribute could be overridden for Meeting Room. For example:* value 1 (0012, ROLE_CALLFLOW) means that the call flow attribute could be overridden by call flow and DID group; value 2 (0102, ROLE_DID) means that the call flow attribute could be overridden by DID; value 3 (0112, ROLE_CALLFLOW + ROLE_DID) means that the call flow attribute could be overridden by call flow, DID group and DID; value 4 (1002, ROLE_MEETING) means that the call flow attribute could be overridden by meeting room; value 5 (1012, ROLE_CALLFLOW + ROLE_MEETING) means that the call flow attribute could be overridden by call flow, DID group and meeting room.
name	string	Attribute name like "meeting_exittones"

type	integer	Attribute type like TYPE_STRING (0), TYPE_INT (2), TYPE_DTMF (3), TYPE_ROLE (4), TYPE_CHOICE (5) (*)
value	string	Attribute value like "on", "hp", "8", etc. ()

Get a Single Call Flow

Returns the full details about the call flow referenced by the {ID} provided.

METHOD	URL
GET	/callFlows/{ID}

Sample URL


curl -X GET --header "Accept: application/json;qs=1" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/callFlows/2?excludeFields=attributeTemplates"

Request Parameters

Parameter	Data Type	Description
id `req`	integer	The callFlow identifier
includeFields	string	Comma separated list of fields that should be included in response
exclude_fields	string	Comma separated list of fields that should be excluded from response.

Sample Response

 {
  "id": 2,
  "name": "CONF",
  "path": "/usr/local/DNCA/callflows/CONF"
}

Response Parameters

Attribute	Data Type	Description
description	string	Description of the attribute
enumValues	string	If type is Enum, i.e. TYPE_CHOICE (5L), this variable holds possible choices like choice1,choice2,choice3 (for example on,off), this is read-only field populated by server
group	integer	Meeting access group (role) bitmask flag this attribute belongs to (i.e. the owner of the attribute) consisting of 3 bits for Call Flow / DID Group, DID, and Meeting Room (); and each of these bits determines at what level the call flow attribute value could be overridden or not: bit 0 (CallFlow and DidGroup) – 0 (02) value of this flag determines that the call flow attribute could not be overridden for call flow and DID group, 1 (12) value of this flag determines that the call flow attribute could be overridden for call flow and DID group; bit 1 (Did) – 0 (02) value of this flag determines that the call flow attribute could not be overridden for DID, 1 (12) value of this flag determines that the call flow attribute could be overridden for DID; bit 2 (MeetingRoom) – 0 (02) value of this flag determines that the call flow attribute could not be overridden for Meeting Room, 1 (12) value of this flag determines that the call flow attribute could be overridden for Meeting Room. For example:* value 1 (0012, ROLE_CALLFLOW) means that the call flow attribute could be overridden by call flow and DID group; value 2 (0102, ROLE_DID) means that the call flow attribute could be overridden by DID; value 3 (0112, ROLE_CALLFLOW + ROLE_DID) means that the call flow attribute could be overridden by call flow, DID group and DID; value 4 (1002, ROLE_MEETING) means that the call flow attribute could be overridden by meeting room; value 5 (1012, ROLE_CALLFLOW + ROLE_MEETING) means that the call flow attribute could be overridden by call flow, DID group and meeting room.
name	string	Attribute name like "meeting_exittones"

type	integer	Attribute type like TYPE_STRING (0), TYPE_INT (2), TYPE_DTMF (3), TYPE_ROLE (4), TYPE_CHOICE (5) (*)
value	string	Attribute value like "on", "hp", "8", etc. ()

Update the Existing Conference Profile

This call will update the existing callFlow object

METHOD	URL
PUT	/callFlows/{ID}

Sample URL


curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json" -u <your_user_name>:<your_password> -d '{"name":"Another name"}' "https://api.carrierx.com/conference/v1/callFlows/3"

Request Parameters

Parameter	Data Type	Description
did_sid `req`	string	DID secure ID
body	...	Body of the DID to be updated

Example Response

 {
  "attributeTemplates": [
      {
          "description": "Delay before answer (s)",
          "enumValues": "",
          "group": 3,
          "name": "call_delay",
          "type": 2,
          "value": "2"
      },
      {
          "description": "Maximal calls duration (s)",
          "enumValues": "",
          "group": 5,
          "name": "call_maxduration",
          "type": 2,
          "value": "21600"
      },
      {
          "description": "Call operator after number of unsuccessful attempts to enter access code",
          "enumValues": "",
          "group": 1,
          "name": "call_operator_after",
          "type": 2,
          "value": "3"
      },
      {
          "description": "Language",
          "enumValues": "",
          "group": 5,
          "name": "conference_language",
          "type": 0,
          "value": "EN"
      },
      {
          "description": "Authorize method",
          "enumValues": "local,wydeldap,wyderadius,wyderest",
          "group": 1,
          "name": "dnis_authorizemethod",
          "type": 5,
          "value": "local"
      },
      {
          "description": "Billing rule",
          "enumValues": "default",
          "group": 1,
          "name": "dnis_billingrule",
          "type": 5,
          "value": "default"
      },
      {
          "description": "Maximal number of calls per DNIS",
          "enumValues": "",
          "group": 3,
          "name": "dnis_maxcalls",
          "type": 2,
          "value": "-1"
      },
      {
          "description": "Reffered DNIS number",
          "enumValues": "",
          "group": 3,
          "name": "dnis_number",
          "type": 0,
          "value": "12"
      },
      {
          "description": "Welcome prompt",
          "enumValues": "",
          "group": 3,
          "name": "dnis_welcomeprompt",
          "type": 7,
          "value": "default"
      }
  ],
  "id": 3,
  "name": "Another name",
  "path": "/usr/local/DNCA/callflows/PLAYBACK"
}

Response Parameters

Attribute	Data Type	Description
description	string	Description of the attribute
enumValues	string	If type is Enum, i.e. TYPE_CHOICE (5L), this variable holds possible choices like choice1,choice2,choice3 (for example on,off), this is read-only field populated by server
group	integer	Meeting access group (role) bitmask flag this attribute belongs to (i.e. the owner of the attribute) consisting of 3 bits for Call Flow / DID Group, DID, and Meeting Room (); and each of these bits determines at what level the call flow attribute value could be overridden or not: bit 0 (CallFlow and DidGroup) – 0 (02) value of this flag determines that the call flow attribute could not be overridden for call flow and DID group, 1 (12) value of this flag determines that the call flow attribute could be overridden for call flow and DID group; bit 1 (Did) – 0 (02) value of this flag determines that the call flow attribute could not be overridden for DID, 1 (12) value of this flag determines that the call flow attribute could be overridden for DID; bit 2 (MeetingRoom) – 0 (02) value of this flag determines that the call flow attribute could not be overridden for Meeting Room, 1 (12) value of this flag determines that the call flow attribute could be overridden for Meeting Room. For example:* value 1 (0012, ROLE_CALLFLOW) means that the call flow attribute could be overridden by call flow and DID group; value 2 (0102, ROLE_DID) means that the call flow attribute could be overridden by DID; value 3 (0112, ROLE_CALLFLOW + ROLE_DID) means that the call flow attribute could be overridden by call flow, DID group and DID; value 4 (1002, ROLE_MEETING) means that the call flow attribute could be overridden by meeting room; value 5 (1012, ROLE_CALLFLOW + ROLE_MEETING) means that the call flow attribute could be overridden by call flow, DID group and meeting room.
name	string	Attribute name like "meeting_exittones"

type	integer	Attribute type like TYPE_STRING (0), TYPE_INT (2), TYPE_DTMF (3), TYPE_ROLE (4), TYPE_CHOICE (5) (*)
value	string	Attribute value like "on", "hp", "8", etc. ()

DID Groups

DID is a unique set of numbers registered on the bridge that is outpulsed by a phone carrier that indicates the intended destination for a particular call. This data structure holds information about registered DID (called phone numbers) on the bridge; it could also contain specific attributes values that override attribute values defined for callflow and DID group. Besides the phone number (usually 10 digits length), each DID has a reference to a DID group.
DIDs of the same call flow if they use the same access codes are being grouped into DID groups. DID group is a part of the meeting key definition. DID object can exist only if there is the DID group that owns this DID.
Note: The DID group deletion performs cascade delete of all grouped DID records.

Get List of DIDs

This method returns the list of DIDs (phone numbers) registered on the bridge that match the filter in the specified order; offset and limit parameters help to implement paging on the web application; includeFields and excludeFields parameters define what fields should be included or excluded from the output.

METHOD	URL
GET	/dids

Sample URL


curl -X GET --header "Accept: application/json;qs=1" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/dids?offset=0&limit=20&excludeFields=attributes%2Caliases"

Response Parameters

Parameter	Data Type	Description
offset	integer	Amount of items to be skipped in the response. Default is `0`
limit	integer	Number of items to be shown in the response. The value should not exceed 1000. Default is `10`
filter	string	Specify filter for the items in the response. Example: name like 'PL%' Supported operations are (eq, ne, gt, ge, lt, le, and, like, ilike) Several filters can be combined together. Example: id gt 0 and id lt 5
order	string	Specifies order of items in the response: `asc`, `desc` Example: `common_name desc` `country_code asc` The default order is ascending.
include_fields	string	Comma separated list of fields that should be included in the response
exclude_fields	string	Comma separated list of fields that should be excluded from the response

Sample Response

 {
  "dids": [
      {
          "countryCode": "US",
          "description": "main CONF",
          "didGroupId": 1,
          "id": 3,
          "phoneNumber": "10",
          "state": -1
      },

Response Parameters

Attribute	Data Type	Description
attributes	array	DID attributes inherited from callflow; override attribute values defined for callflow and DID group
countryCode	string	The region where a phone number is from; ISO 3166-1 two-letter country-code format is used for this field
description	string	ISO 3166-1 alpha-2 code of this country
didGroupId	integer	ID of the DID group this DID belongs to
id	integer	Unique DID identifier assigned by the server
phoneNumber	string	The telephone number or the number pattern ("", "712", "8665080013", etc.), or name if connected to VOIP switch (*)
state	integer	This flag determines the status of the DID: 0 – Active 1 – Invalidated / Inactive 2 – Deleted / Disabled

DID Attributes Properties

Attribute	Data Type	Description
name	string	Attribute name
description	string	Attribute description
type	integer	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 – db reference 7 – upload
enumValues	string	Possible attribute values if type == 5
value	string	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 – db reference 7 – upload

Create New DID

Сreates a new DID with the details posted in the data input parameter. Please note that only administrator can create new DIDs.

METHOD	URL
POST	/dids

Sample URL


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -u <your_user_name>:<your_password> -d "{"didGroupId":835, "description":"test did", "phoneNumber":"8665080013"}" "https://api.carrierx.com/conference/v1/dids"

Response Parameters

Parameter	Data Type	Description
body	string	The Did object properties: id (ignored), didGroupId (), phoneNumber (), description, state, attributes

Sample Response

 {
  "attributes": [],
  "countryCode": "US",
  "description": "test did",
  "didGroupId": 835,
  "id": 839,
  "phoneNumber": "8665080013",
  "state": -1
}

Response Parameters

Attribute	Data Type	Description
attributes	array	DID attributes inherited from callflow; override attribute values defined for callflow and DID group
countryCode	string	The region where a phone number is from; ISO 3166-1 two-letter country-code format is used for this field
description	string	ISO 3166-1 alpha-2 code of this country
didGroupId	integer	ID of the DID group this DID belongs to
id	integer	Unique DID identifier assigned by the server
phoneNumber	string	The telephone number or the number pattern ("", "712", "8665080013", etc.), or name if connected to VOIP switch (*)
state	integer	This flag determines the status of the DID: 0 – Active 1 – Invalidated / Inactive 2 – Deleted / Disabled

DID Attributes Properties

Attribute	Data Type	Description
name	string	Attribute name
description	string	Attribute description
type	integer	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 - db reference 7 - upload
enumValues	string	Possible attribute values if type == 5
value	string	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 - db reference 7 - upload

Remove a Single DID

Deletes specific DID referenced by the {ID} from the server. Please note that only administrator has a permission to delete DID.

METHOD	URL
DELETE	/dids/{id}

Sample URL


curl -X DELETE --header "Accept: application/json" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/dids/6"

Response Parameters

Parameter	Data Type	Description
id	integer	ID of the DID which needs to be removed

Get a Single DID by ID

Returns full details for the DID which ID is provided

METHOD	URL
GET	/dids/{id}

Sample URL


curl -X GET --header "Accept: application/json;qs=1" --u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/dids/52?excludeFields=attributes%2Caliases"

Response Parameters

Parameter	Data Type	Description
id	integer	DID identifier
includeFields	string	Comma separated list fields that should be included in response. Example: id,phoneNumber
excludeFields	string	Comma separated list fields that should be excluded from response. Example: attributes,aliases

Sample Response

 {
  "countryCode": "US",
  "didGroupId": 51,
  "id": 52,
  "phoneNumber": "15162065098",
  "state": -1
}

Response Parameters

Attribute	Data Type	Description
attributes	array	DID attributes inherited from callflow; override attribute values defined for callflow and DID group
countryCode	string	The region where a phone number is from; ISO 3166-1 two-letter country-code format is used for this field
description	string	ISO 3166-1 alpha-2 code of this country
didGroupId	integer	ID of the DID group this DID belongs to
id	integer	Unique DID identifier assigned by the server
phoneNumber	string	The telephone number or the number pattern ("", "712", "8665080013", etc.), or name if connected to VOIP switch (*)
state	integer	This flag determines the status of the DID: 0 – Active 1 – Invalidated / Inactive 2 – Deleted / Disabled

DID Attributes Properties

Attribute	Data Type	Description
name	string	Attribute name
description	string	Attribute description
type	integer	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 - db reference 7 - upload
enumValues	string	Possible attribute values if type == 5
value	string	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 - db reference 7 - upload

Update an Existing DID

updates existing DID referenced by the identifier {ID} with the new information posted in the data input parameter. Please note that only administrator has a permission to update DID.

METHOD	URL
PUT	/dids/{id}

Sample URL


curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json" -u <your_user_name>:<your_password> -d "{"description":"Another description"}" "https://api.carrierx.com/conference/v1/dids/839"

Response Parameters

Parameter	Data Type	Description
id	integer	DID identifier
body	string	Fields to update Example: To change description: {"description":"another description"}

Sample Response

 {
  "attributes": [],
  "countryCode": "US",
  "description": "Another description",
  "didGroupId": 835,
  "id": 839,
  "phoneNumber": "8665080013",
  "state": -1
}

Response Parameters

Attribute	Data Type	Description
attributes	array	DID attributes inherited from callflow; override attribute values defined for callflow and DID group
countryCode	string	The region where a phone number is from; ISO 3166-1 two-letter country-code format is used for this field
description	string	ISO 3166-1 alpha-2 code of this country
didGroupId	integer	ID of the DID group this DID belongs to
id	integer	Unique DID identifier assigned by the server
phoneNumber	string	The telephone number or the number pattern ("", "712", "8665080013", etc.), or name if connected to VOIP switch (*)
state	integer	This flag determines the status of the DID: 0 – Active 1 – Invalidated / Inactive 2 – Deleted / Disabled

DID Attributes Properties

Attribute	Data Type	Description
name	string	Attribute name
description	string	Attribute description
type	integer	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 – db reference 7 – upload
enumValues	string	Possible attribute values if type == 5
value	string	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 – db reference 7 – upload

DID Groups

The DidGroup data structure represents a group of DIDs that use a concrete call flow and belong to a specific subscriber.

Parent subscriber can see all DidGroups owned by all his child subscribers. Child subscribers can see their own DidGroups and the ones that belong to their parent, but cannot see DidGroups of each other.
Different DID groups can be used to connect to the same meeting.
DID Group can contain specific attributes values that override attribute values defined for the callflow
Different DID groups can be based on the same callflows, but have different attributes ( for example: welcome prompt).

Get List of DID Groups

Returns the list of DID groups registered on the bridge which match the filter provided according to the specified order; there are two parameters offset and limit to help to implement paging on the web application; there are also two parameters includeFields and excludeFields defining what fields should be included or excluded from the output.

METHOD	URL
GET	/didGroups

Sample URL


curl -X GET --header "Accept: application/json;qs=1" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/didGroups?offset=0&limit=20&excludeFields=attributes"

Request Parameters

Parameter	Data Type	Description
offset	integer	Amount of items to be skipped in the response
limit	integer	Number of items to be shown
filter	string	Specify filter for the items in the response. Example: name like 'PL%' Supported operations are (eq, ne, gt, ge, lt, le, and, like, ilike) Several filters can be combined together. Example: id gt 0 and id lt 5
includeFields	string	Comma seperated fields that should be included in the response
excludeFields	string	Comma separated fields that should be excluded from the response

Sample Response

 {
  "didGroups": [
      {
          "callFlowId": 2,
          "description": "",
          "dids": [
              {
                  "attributes": [],
                  "countryCode": "US",
                  "description": "Another description",
                  "didGroupId": 835,
                  "id": 839,
                  "phoneNumber": "8665080013",
                  "state": -1
              },

Response Parameters

Attribute	Data Type	Description
attributes	array	DID group attributes inherited from callflow; override attribute values defined for callflow; may be overwritten by DID attributes
callFlowId	string	ID of the call flow this DID group belongs to (*); all DIDs from the group belong to the same call flow
description	string	Description of the DID group
dids	integer	DIDs that belong to this group
id	string	Unique DID group identifier assigned by the server
subscriberID	string	ID of the subscriber the DID group belongs to
name	string	The name of DID group
state	integer	Specifies a possible owner of attribute: 0 bit - CallFlow, 1 bit - Did, 2 bit - MeetingRoom

DidGroup Attributes Properties

Attribute	Data Type	Description
name	string	Attribute name
description	string	Attribute description
type	integer	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 – reference 7 – upload
enumValues	string	Possible attribute values if type == 5
value	string	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 – db reference 7 – upload

Create a New DID Group

This call creates a new DID group with the details posted in the data input parameter. Please note that only administrator can create new DID group.

METHOD	URL
POST	/didGroups/

Sample URL


curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -u <your_user_name>:<your_password> -d "{"name":"Testing", "callFlowId":2, "description":"New did group for testing"}" "https://api.carrierx.com/conference/v1/didGroups"

Response Parameters

Parameter	Data Type	Description
body	object	The DidGroup object properties: id (ignored), name (), callFlowId (), description, state, dids (if you would like to create DIDs simultaneously with the Did group creation, you should populate dids property of the DidGroup class)

Sample Response

 {
  "attributes": [],
  "callFlowId": 2,
  "description": "New did group for testing",
  "id": 840,
  "name": "Testing",
  "state": -1,
  "subscriberSid": "a2Jy91nOnvfAYY32q-dtzRSbt-X3ykOf"
}

Response Parameters

Attribute	Data Type	Description
attributes	array	DID group attributes inherited from callflow; override attribute values defined for callflow; may be overwritten by DID attributes
callFlowId	string	ID of the call flow this DID group belongs to (*); all DIDs from the group belong to the same call flow
description	string	Description of the DID group
dids	integer	DIDs that belong to this group
id	string	Unique DID group identifier assigned by the server
subscriberID	string	ID of the subscriber the DID group belongs to
name	string	The name of DID group
state	integer	Specifies a possible owner of attribute: 0 bit - CallFlow, 1 bit - Did, 2 bit - MeetingRoom

DidGroup Attributes Properties

Attribute	Data Type	Description
name	string	Attribute name
description	string	Attribute description
type	integer	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 – reference 7 – upload
enumValues	string	Possible attribute values if type == 5
value	string	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 – db reference 7 – upload

Remove DID Group

The call deletes specific DID group referenced by the {ID} from the server. Please note that only administrator has a permission to delete DID group.

METHOD	URL
DELETE	/didGroups/{id}

Sample URL


curl -X DELETE --header "Accept: application/json;qs=1" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/didGroups/4206"

Response Parameters

Parameter	Data Type	Description
id	integer	ID of the DIDGroup to be removed

Get a Single DID Group by ID

Thte call returns the full details about the DID group referenced by the {ID} provided.

METHOD	URL
GET	/dids/{id}

Sample URL


curl -X GET --header "Accept: application/json;qs=1" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/didGroups/840?excludeFields=attributes"

Response Parameters

Parameter	Data Type	Description
id	integer	GroupDID identifier
includeFields	string	Comma separated list fields that should be included in response.
excludeFields	string	Comma separated list fields that should be excluded from response.

Sample Response

 {
  "callFlowId": 2,
  "description": "New did group for testing",
  "id": 840,
  "name": "Testing",
  "state": -1,
  "subscriberSid": "a2Jy91nOnvfAYY32q-dtzRSbt-X3ykOf"
}

Response Parameters

Attribute	Data Type	Description
attributes	array	DID group attributes inherited from callflow; override attribute values defined for callflow; may be overwritten by DID attributes
callFlowId	string	ID of the call flow this DID group belongs to (*); all DIDs from the group belong to the same call flow
description	string	Description of the DID group
dids	integer	DIDs that belong to this group
id	string	Unique DID group identifier assigned by the server
subscriberID	string	ID of the subscriber the DID group belongs to
name	string	The name of DID group
state	integer	Specifies a possible owner of attribute: 0 bit - CallFlow, 1 bit - Did, 2 bit - MeetingRoom

DidGroup Attributes Properties

Attribute	Data Type	Description
name	string	Attribute name
description	string	Attribute description
type	integer	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 – reference 7 – upload
enumValues	string	Possible attribute values if type == 5
value	string	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 – db reference 7 – upload

DID Attributes Properties

Attribute	Data Type	Description
name	string	Attribute name
description	string	Attribute description
type	integer	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 - db reference 7 - upload
enumValues	string	Possible attribute values if type == 5
value	string	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 - db reference 7 - upload

Update an Existing DID Group

updates existing DID referenced by the identifier {ID} with the new information posted in the data input parameter. Please note that only administrator has a permission to update DID..

METHOD	URL
PUT	/didGroups/{id}

Sample URL


curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json" -u <your_user_name>:<your_password> -d "{"name":"Another name"}" "https://api.carrierx.com/conference/v1/didGroups/840"

Response Parameters

Parameter	Data Type	Description
id	integer	DID Group identifier
body	string	Fields to update Example: To change description: {"description":"another description"}

Sample Response

 {
  "attributes": [],
  "callFlowId": 2,
  "description": "New did group for testing",
  "id": 840,
  "name": "Another name",
  "state": -1,
  "subscriberSid": "a2Jy91nOnvfAYY32q-dtzRSbt-X3ykOf"
}

Response Parameters

Attribute	Data Type	Description
attributes	array	DID group attributes inherited from callflow; override attribute values defined for callflow; may be overwritten by DID attributes
callFlowId	string	ID of the call flow this DID group belongs to (*); all DIDs from the group belong to the same call flow
description	string	Description of the DID group
dids	integer	DIDs that belong to this group
id	string	Unique DID group identifier assigned by the server
subscriberID	string	ID of the subscriber the DID group belongs to
name	string	The name of DID group
state	integer	Specifies a possible owner of attribute: 0 bit - CallFlow, 1 bit - Did, 2 bit - MeetingRoom

DidGroup Attributes Properties

Attribute	Data Type	Description
name	string	Attribute name
description	string	Attribute description
type	integer	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 – reference 7 – upload
enumValues	string	Possible attribute values if type == 5
value	string	0 - string(default) 2 – integer 3 – dtmf 4 – role 5 – choice 6 – db reference 7 – upload

Calls

This data structure represents a single ongoing (active) call on the server.

User can not directly create this object;
It is created by the server when the user calls on the bridge;
When the call is over, server automatically deletes this

Normally, this data structure is used to get information about call attributes like calling/called number etc. If something needs to be done with the call (mute/hang/hold), the call should be referenced by its identifier.

Get List of Calls

Returns the list of all started calls which match the filter provided according to the specified order; offset and limit parameters help to implement paging on the web application. If this method is called from non admin Subscribers it will return only the Calls visible for this account;

METHOD	URL
GET	/Calls

Sample URL


curl -X GET --header "Accept: application/json;qs=1" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/calls?offset=0&limit=20"

Request Parameters

Parameter	Data Type	Description
offset	integer	Amount of items to be skipped in the response
limit	integer	Number of items to be shown
filter	string	Specify filter for the items in the response. Example: name like 'PL%' Supported operations are (eq, ne, gt, ge, lt, le, and, like, ilike) Several filters can be combined together. Example: gainLevel ge 10 and state gt 2
includeFields	string	Comma seperated fields that should be included in the response
excludeFields	string	Comma separated fields that should be excluded from the response

Response Parameters

Attribute	Data Type	Description
accessCode	string	Access code entered by caller
addressFrom	string	Full address FROM, i.e. full qualified caller’s address
addressTo	string	Full address TO, i.e. full qualified сallee’s address
bridgeName	string	Hosted bridge name
callee	string	Information about callee as it is provided in TO field
caller	string	Information about caller as it is provided in FROM field (normally the phone number)
codec	string	The active audio codec of the call, i.e. the technical name of the codec, that is used by the call, for example PCMU for uLaw, SIREN7 for 722.1, SIREN14 for 722.2, ILBC, etc
connectionStatus	integer	Bit-mask that indicates the optional call attributes, for example call direction: 0 – inbound call, 1 – outbound call
created	string	Date and time when the call was created
customName	string	Custom user name either set from the web or IVR (login)
duration	integer	Number of seconds elapsed since the call started
gainLevel	integer	The microphone volume level of the call, i.e. gain control option; it could be from -10 till 10 or 255; -10 is the quietest (lowest) sound level, 10 is the loudest (highest) sound level, 255 denotes that the microphone level is being automatically adjusted by the backend
holdMode	integer	Hold mode flag that determines whether the call is put on hold (by administrator, owner, client, etc.) or the call is online (is not on hold): 0 value of this flag determines that the call is online, 1 value of this flag determines that the call is on hold
id	integer	Unique ID assigned by the server
jobCode	string	Active billing (business) code
joined	string	Time when the call joined the meeting
meetingNumber	integer	Number of the meeting this call belongs to
muteMode	integer	Mute mode bitmask flag consisting of 2 groups (bits) for host muting and self-muting; and each of the group has bit that determines whether this call is muted or not: bit 0 (host) – 0 (02) value of this flag determines that the call is not muted by the host, 1 (12) value of this flag determines that the host muted the call; bit 1 (self) – 0 (02) value of this flag determines that the caller self is not muted the call, 1 (12) value of this flag determines that the caller self-muted the call
nodeName	string	Name of the hosted node
operatorMode	integer	This filed represents the operator’s activity (for instance, empty, waiting for operator, speaking with operator, etc.). Possible values: 0 (or null) – the caller does not need operator assistance; 1 (wait) – the caller is waiting operator assistance, i.e. the caller is in the operator’s queue; 2 (talk) – the caller is talking to the operator
presenterMedia	integer	Specific media of the call chunk; possible values: 1 – audio, 2 – screen sharing 4 – video 8 – controlling
qaMode	integer	This filed represents Q&A mode for current call: 0 - QA_STATUS_IDLE 1 - QA_STATUS_RAISEDHAND 2 - QA_STAUS_ACTIVE
role	integer	Determines the call role. The roles should be the same as in MeetingKey. Role helps to verify whether this call is allowed to do Recording: 0 - MODE_UNDEFINED (0L) 1 - MODE_HOST (1L) – host permissions granted, 2 - MODE_PARTICIPANT – caller controls muting, i.e. the call owner can mute/unmute himself, 3 - MODE_LISTENER – the call owner can only listen and cannot talk, 4 - MODE_RECORDING – the recording call, 8 - MODE_DC_LINK – distributed meeting (DC) link, i.e. the control call between two bridges in distributed conferencing
state	integer	Determines whether the current call state: 1 - STATUS_IVR - call is owned by frontend; 2 - STATUS_MEETING - call is owned by backend; 3 - STATUS_CLOSED - call is closed; 4 - STATUS_DIALING - call is dealing
subconference	string	If non-empty, denotes current sub-meeting of the call (caller)
subscriberPin	string	Contains subscriber PIN if it was entered by the user from his DTMF keypad when he joins to the meeting to receive host permissions in the meeting; check call flow attributes Validate subscriber pin (dnis_validatesubscriberpin) and Subscriber PIN (subscriber_pin) for details

Create New Call

This request will create a new call

METHOD	URL
POST	/calls

Sample URL


curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"caller":"10", "callee":"2694", "accessCode":"2471"}' -u <your_user_name>:<your_password> 'https://api.carrierx.com/conference/v1/calls'

Response Parameters

Parameter	Data Type	Description
body	object	The call object. The mandatory fields are 'caller', 'callee', and the 'accessCode'

Response Parameters

Attribute	Data Type	Description
accessCode	string	Access code entered by caller
addressFrom	string	Full address FROM, i.e. full qualified caller’s address
addressTo	string	Full address TO, i.e. full qualified сallee’s address
bridgeName	string	Hosted bridge name
callee	string	Information about callee as it is provided in TO field
caller	string	Information about caller as it is provided in FROM field (normally the phone number)
codec	string	The active audio codec of the call, i.e. the technical name of the codec, that is used by the call, for example PCMU for uLaw, SIREN7 for 722.1, SIREN14 for 722.2, ILBC, etc
connectionStatus	integer	Bit-mask that indicates the optional call attributes, for example call direction: 0 – inbound call, 1 – outbound call
created	string	Date and time when the call was created
customName	string	Custom user name either set from the web or IVR (login)
duration	integer	Number of seconds elapsed since the call started
gainLevel	integer	The microphone volume level of the call, i.e. gain control option; it could be from -10 till 10 or 255; -10 is the quietest (lowest) sound level, 10 is the loudest (highest) sound level, 255 denotes that the microphone level is being automatically adjusted by the backend
holdMode	integer	Hold mode flag that determines whether the call is put on hold (by administrator, owner, client, etc.) or the call is online (is not on hold): 0 value of this flag determines that the call is online, 1 value of this flag determines that the call is on hold
id	integer	Unique ID assigned by the server
jobCode	string	Active billing (business) code
joined	string	Time when the call joined the meeting
meetingNumber	integer	Number of the meeting this call belongs to
muteMode	integer	Mute mode bitmask flag consisting of 2 groups (bits) for host muting and self-muting; and each of the group has bit that determines whether this call is muted or not: bit 0 (host) – 0 (02) value of this flag determines that the call is not muted by the host, 1 (12) value of this flag determines that the host muted the call; bit 1 (self) – 0 (02) value of this flag determines that the caller self is not muted the call, 1 (12) value of this flag determines that the caller self-muted the call
nodeName	string	Name of the hosted node
operatorMode	integer	This filed represents the operator’s activity (for instance, empty, waiting for operator, speaking with operator, etc.). Possible values: 0 (or null) – the caller does not need operator assistance; 1 (wait) – the caller is waiting operator assistance, i.e. the caller is in the operator’s queue; 2 (talk) – the caller is talking to the operator
presenterMedia	integer	Specific media of the call chunk; possible values: 1 – audio, 2 – screen sharing 4 – video 8 – controlling
qaMode	integer	This filed represents Q&A mode for current call: 0 - QA_STATUS_IDLE 1 - QA_STATUS_RAISEDHAND 2 - QA_STAUS_ACTIVE
role	integer	Determines the call role. The roles should be the same as in MeetingKey. Role helps to verify whether this call is allowed to do Recording: 0 - MODE_UNDEFINED (0L) 1 - MODE_HOST (1L) – host permissions granted, 2 - MODE_PARTICIPANT – caller controls muting, i.e. the call owner can mute/unmute himself, 3 - MODE_LISTENER – the call owner can only listen and cannot talk, 4 - MODE_RECORDING – the recording call, 8 - MODE_DC_LINK – distributed meeting (DC) link, i.e. the control call between two bridges in distributed conferencing
state	integer	Determines whether the current call state: 1 - STATUS_IVR - call is owned by frontend; 2 - STATUS_MEETING - call is owned by backend; 3 - STATUS_CLOSED - call is closed; 4 - STATUS_DIALING - call is dealing
subconference	string	If non-empty, denotes current sub-meeting of the call (caller)
subscriberPin	string	Contains subscriber PIN if it was entered by the user from his DTMF keypad when he joins to the meeting to receive host permissions in the meeting; check call flow attributes Validate subscriber pin (dnis_validatesubscriberpin) and Subscriber PIN (subscriber_pin) for details

Remove a Call

This request disconnects (hangs up) the call reference by the {ID} provided.

METHOD	URL
DELETE	/calls/{ID}

Sample URL


curl -X DELETE --header "Accept: application/json" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/calls/174"

Response Parameters

Parameter	Data Type	Description
id	integer	Call ID

Get a Single Call by ID

Returns the full details about the call referenced by the call identifier {ID}

METHOD	URL
GET	/calls/{id}

Sample URL


curl -X GET --header "Accept: application/json;qs=1" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/calls/187

Response Parameters

Parameter	Data Type	Description
id	integer	Call ID
includeFields	string	Comma separated list fields that should be included in response.
excludeFields	string	Comma separated list fields that should be excluded from response.

Response Parameters

Attribute	Data Type	Description
accessCode	string	Access code entered by caller
addressFrom	string	Full address FROM, i.e. full qualified caller’s address
addressTo	string	Full address TO, i.e. full qualified сallee’s address
bridgeName	string	Hosted bridge name
callee	string	Information about callee as it is provided in TO field
caller	string	Information about caller as it is provided in FROM field (normally the phone number)
codec	string	The active audio codec of the call, i.e. the technical name of the codec, that is used by the call, for example PCMU for uLaw, SIREN7 for 722.1, SIREN14 for 722.2, ILBC, etc
connectionStatus	integer	Bit-mask that indicates the optional call attributes, for example call direction: 0 – inbound call, 1 – outbound call
created	string	Date and time when the call was created
customName	string	Custom user name either set from the web or IVR (login)
duration	integer	Number of seconds elapsed since the call started
gainLevel	integer	The microphone volume level of the call, i.e. gain control option; it could be from -10 till 10 or 255; -10 is the quietest (lowest) sound level, 10 is the loudest (highest) sound level, 255 denotes that the microphone level is being automatically adjusted by the backend
holdMode	integer	Hold mode flag that determines whether the call is put on hold (by administrator, owner, client, etc.) or the call is online (is not on hold): 0 value of this flag determines that the call is online, 1 value of this flag determines that the call is on hold
id	integer	Unique ID assigned by the server
jobCode	string	Active billing (business) code
joined	string	Time when the call joined the meeting
meetingNumber	integer	Number of the meeting this call belongs to
muteMode	integer	Mute mode bitmask flag consisting of 2 groups (bits) for host muting and self-muting; and each of the group has bit that determines whether this call is muted or not: bit 0 (host) – 0 (02) value of this flag determines that the call is not muted by the host, 1 (12) value of this flag determines that the host muted the call; bit 1 (self) – 0 (02) value of this flag determines that the caller self is not muted the call, 1 (12) value of this flag determines that the caller self-muted the call
nodeName	string	Name of the hosted node
operatorMode	integer	This filed represents the operator’s activity (for instance, empty, waiting for operator, speaking with operator, etc.). Possible values: 0 (or null) – the caller does not need operator assistance; 1 (wait) – the caller is waiting operator assistance, i.e. the caller is in the operator’s queue; 2 (talk) – the caller is talking to the operator
presenterMedia	integer	Specific media of the call chunk; possible values: 1 – audio, 2 – screen sharing 4 – video 8 – controlling
qaMode	integer	This filed represents Q&A mode for current call: 0 - QA_STATUS_IDLE 1 - QA_STATUS_RAISEDHAND 2 - QA_STAUS_ACTIVE
role	integer	Determines the call role. The roles should be the same as in MeetingKey. Role helps to verify whether this call is allowed to do Recording: 0 - MODE_UNDEFINED (0L) 1 - MODE_HOST (1L) – host permissions granted, 2 - MODE_PARTICIPANT – caller controls muting, i.e. the call owner can mute/unmute himself, 3 - MODE_LISTENER – the call owner can only listen and cannot talk, 4 - MODE_RECORDING – the recording call, 8 - MODE_DC_LINK – distributed meeting (DC) link, i.e. the control call between two bridges in distributed conferencing
state	integer	Determines whether the current call state: 1 - STATUS_IVR - call is owned by frontend; 2 - STATUS_MEETING - call is owned by backend; 3 - STATUS_CLOSED - call is closed; 4 - STATUS_DIALING - call is dealing
subconference	string	If non-empty, denotes current sub-meeting of the call (caller)
subscriberPin	string	Contains subscriber PIN if it was entered by the user from his DTMF keypad when he joins to the meeting to receive host permissions in the meeting; check call flow attributes Validate subscriber pin (dnis_validatesubscriberpin) and Subscriber PIN (subscriber_pin) for details

Update the Single Call

The request changes the call state of the specific call referenced by its identifier {ID} with the new parameters posted in the data input. Thus this method performs the following actions:

Places the call on hold; hold mode is flag that determines whether the call is put on hold (by administrator, owner, client, etc.) or the call is online (is not on hold): 0 value of this flag determines that the call is online, 1 value of this flag determines that the call is on hold – see details for holdMode property in Table 13:
- data: holdMode = 1
Places the call off hold (online):
- data: holdMode = 0
Mutes the specific call; mute mode bitmask flag consisting of 2 groups (bits) for host muting and self muting; 0 value of this flag determines that the call is not muted ( host or self) 1 value of this flag determines that the call is muted ( host or self) Table13 for muteMode property:
- data: muteMode = 1 (to mute the call by host)
Un-mutes the call:
- data: muteMode = 0
Sets the custom name of the caller:
- data: customName = "{new custom name to be set}"
Attaches (moves) the caller to the sub-meeting or detaches it from the sub- meeting; if the subconference property value is not empty, the call is being attached to sub-meeting (if it is not currently connected to any of the sub- meetings) or moved to sub-meeting (if it is currently connected to another sub- meeting); non-empty parameter represents the name of the sub-meeting up to 16 characters length (only letters and digits are allowed as the name of the sub- meeting); if the parameter is empty string the call is being detached from the sub-meeting:
- data: subconference = {sub-meeting to move the call}
Sets the specified job code for the specific call:
- data: jobCode = {new active job code to be set}
Changes the role of the call in the meeting (note: no additional CDR record is being created for the call); the role (mode) that will be granted to the call in the meeting could be MODE_HOST = 1L, MODE_PARTICIPANT = 2L, MODE_LISTENER = 3L
- data: role = {new role}

METHOD	URL
PUT	/calls/{id}

Sample URL


curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json" -u <your_user_name>:<your_password> -d "{"customName": "name"}" "https://api.carrierx.com/conference/v1/calls/144"

Response Parameters

Parameter	Data Type	Description
id	integer	Call ID
body	string	The Call object properties; see above to determine what call properties should be changed and what properties’ values should be set to change the call state

Response Parameters

Attribute	Data Type	Description
accessCode	string	Access code entered by caller
addressFrom	string	Full address FROM, i.e. full qualified caller’s address
addressTo	string	Full address TO, i.e. full qualified сallee’s address
bridgeName	string	Hosted bridge name
callee	string	Information about callee as it is provided in TO field
caller	string	Information about caller as it is provided in FROM field (normally the phone number)
codec	string	The active audio codec of the call, i.e. the technical name of the codec, that is used by the call, for example PCMU for uLaw, SIREN7 for 722.1, SIREN14 for 722.2, ILBC, etc
connectionStatus	integer	Bit-mask that indicates the optional call attributes, for example call direction: 0 – inbound call, 1 – outbound call
created	string	Date and time when the call was created
customName	string	Custom user name either set from the web or IVR (login)
duration	integer	Number of seconds elapsed since the call started
gainLevel	integer	The microphone volume level of the call, i.e. gain control option; it could be from -10 till 10 or 255; -10 is the quietest (lowest) sound level, 10 is the loudest (highest) sound level, 255 denotes that the microphone level is being automatically adjusted by the backend
holdMode	integer	Hold mode flag that determines whether the call is put on hold (by administrator, owner, client, etc.) or the call is online (is not on hold): 0 value of this flag determines that the call is online, 1 value of this flag determines that the call is on hold
id	integer	Unique ID assigned by the server
jobCode	string	Active billing (business) code
joined	string	Time when the call joined the meeting
meetingNumber	integer	Number of the meeting this call belongs to
muteMode	integer	Mute mode bitmask flag consisting of 2 groups (bits) for host muting and self-muting; and each of the group has bit that determines whether this call is muted or not: bit 0 (host) – 0 (02) value of this flag determines that the call is not muted by the host, 1 (12) value of this flag determines that the host muted the call; bit 1 (self) – 0 (02) value of this flag determines that the caller self is not muted the call, 1 (12) value of this flag determines that the caller self-muted the call
nodeName	string	Name of the hosted node
operatorMode	integer	This filed represents the operator’s activity (for instance, empty, waiting for operator, speaking with operator, etc.). Possible values: 0 (or null) – the caller does not need operator assistance; 1 (wait) – the caller is waiting operator assistance, i.e. the caller is in the operator’s queue; 2 (talk) – the caller is talking to the operator
presenterMedia	integer	Specific media of the call chunk; possible values: 1 – audio, 2 – screen sharing 4 – video 8 – controlling
qaMode	integer	This filed represents Q&A mode for current call: 0 – QA_STATUS_IDLE 1 – QA_STATUS_RAISEDHAND 2 – QA_STAUS_ACTIVE
role	integer	Determines the call role. The roles should be the same as in MeetingKey. Role helps to verify whether this call is allowed to do Recording: 0 – MODE_UNDEFINED (0L) 1 – MODE_HOST (1L) – host permissions granted, 2 – MODE_PARTICIPANT – caller controls muting, i.e. the call owner can mute/unmute himself, 3 – MODE_LISTENER – the call owner can only listen and cannot talk, 4 – MODE_RECORDING – the recording call, 8 – MODE_DC_LINK – distributed meeting (DC) link, i.e. the control call between two bridges in distributed conferencing
state	integer	Determines whether the current call state: 1 - STATUS_IVR - call is owned by frontend; 2 - STATUS_MEETING - call is owned by backend; 3 - STATUS_CLOSED - call is closed; 4 - STATUS_DIALING - call is dealing
subconference	string	If non-empty, denotes current sub-meeting of the call (caller)
subscriberPin	string	Contains subscriber PIN if it was entered by the user from his DTMF keypad when he joins to the meeting to receive host permissions in the meeting; check call flow attributes Validate subscriber pin (dnis_validatesubscriberpin) and Subscriber PIN (subscriber_pin) for details

Meetings

This data structure is used to describe ongoing (active) meeting on the bridge.

Meetings are created by the server;
User may fetch meetings by calling appropriate function;
When the meeting is over, object is deleted by the

NOTE: The meeting object is identified by its number.

The meeting number is the property of meeting room info; the meeting keys are assigned to the meeting room with the specific meeting number, and all these items determine one single meeting.

Get List of Meetings

The call returns the list of all started meetings which are registered for the subscriber on which behalf this call is executed according to specified filter and order; offset and limit parameters help to implement paging on the web application; includeFields and excludeFields parameters define what fields should be included or excluded from the output. Note: field attributes in the meeting will be populated with the list of call flow attributes for this meeting; if the meeting is operator-meeting, the operatorStatus field represents the operator’s activity.

METHOD	URL
GET	/meetings

Sample URL


curl -X GET --header "Accept: application/json;qs=1" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/meetings?offset=0&limit=20&filter=state%20gt%200&order=created%20desc&excludeFields=attributes"

Request Parameters

Parameter	Data Type	Description
offset	integer	Amount of items to be skipped in the response
limit	integer	Number of items to be shown
filter	string	Specify filter for the items in the response. Example: type eq 2 Supported operations are (eq, ne, gt, ge, lt, le, and, like, ilike) Several filters can be combined together. Example: duration ge 10 and state eq 2
includeFields	string	Comma seperated fields that should be included in the response
excludeFields	string	Comma separated fields that should be excluded from the response

Response Parameters

Attribute	Data Type	Description
attributes	array	Meeting attributes; the set (template) of available attributes defined for the callflow of the meeting, the attributes values may be overridden on DID and/or MeetingRoom level
broadcastingMode	string	Contains URL of the media file (audio or video) that currently is being broadcasted in the meeting, otherwise null or empty string.
created	string	Date and time when this meeting was created – the first caller arrived
duration	integer	Number of seconds which have elapsed since the meeting was created
holdMode	integer	Hold mode bitmask flag consisting of 3 groups for hosts, participants, listeners and each of the group has bits that determine whether the group is on hold or online (not on hold): bits 0,1 (host) – 0 (002) value of this flag determines that the hosts are online (not on hold), 1 (012) value of this flag determines that the hosts are self-placed on hold, 2 (102) value of this flag determines that the hosts are placed on hold by the meeting host; bits 2,3 (participant) – 0 (002) value of this flag determines that the participants are online (not on hold), 1 (012) value of this flag determines that the participants are self-placed on hold, 2 (102) value of this flag determines that the participants are placed on hold by host; bits 4,5 (listener) – 0 (002) value of this flag determines that the listeners are online (not on hold), 1 (012) value of this flag determines that the listeners are self-placed on hold, 2 (102) value of this flag determines that the listeners are placed on hold by host. For example: value 32 means that the listeners are muted and cannot un-mute themselves, participants and hosts are not muted; value 36 means that the listeners are muted and cannot un-mute themselves, participants are muted and can un-mute themselves, and hosts are not muted (mute mode – relaxed); value 40 means that the listeners and participants are muted and cannot un-mute themselves, hosts are not muted (mute mode – strict).
OperatorStatus	string	This fields represents the operator’s activity, i.e. it contains the data structure that describes the operator’s meeting.
callback	object	Callback object
participantCount	integer	Number of active participants in the meeting>
pollingMode	string	This field determines whether the polling call is started; empty string value means that the polling is not started; if the polling is started the field contains available polling options – digits 1, 2, ..., 9, 0
qaMode	integer	This field determines whether the Q&A call is started and used to manage Q&A mode; 0 - Q&A call is not started, 1 - Q&A call is started (in progress), 2 - talk to the next caller in Q&A queue, 4 - clear Q&A queue
state	integer	The status of the meeting: 0 – the meeting completed or is not started, 1 – the meeting is on hold (for instance, due the moderator is not arrived yet when it is required by the meeting configuration, see How conference begins (conference_start_how) call flow attribute value), 2 – the meeting is active. Note: there is no transition from state 2 (active) to state 1 (on hold)
subscriberName	string	Name of the first subscriber in the meeting
type	integer	This field determines whether the meeting is participating in the distributed meetings (DC, the value 1) or not (the value 0)

Operator Status

This data structure is designed to show the status of the operator’s meeting.

Attribute	Data Type	Description
engagedConferenceNumber	string	Meeting number of the connected meeting
isConnected	boolean	This field determines whether the operator’s meeting is currently connected to the other one (in this case this property is set to true)
isMonitoring	boolean	For the operator meeting this field determines whether the operator meeting is in scanning mode (i.e. surveillance call, usually started when the operator presses *1 on his phone keypad)
status	integer	This field determines operators meeting mode: MEETING_REGULAR (0), MEETING_OPERATOR (1), MEETING_LISTEN (2), MEETING_AUTOLISTEN (3), MEETING_AUTOLISTEN_SLEEP (4), MEETING_TALK (5)

Polling Mode

This data structure shows additional information on the polling call.

Attribute	Data Type	Description
status	integer	Status of the polling call
description	string	Polling call description
choices	array	Polling choices. Possible values: dtmf, value, votes
callBackUrl	string	Callback URL

Callback

Attribute

Data Type

Description

integer

Callback ID

url

string

External URL to be called when an event associated to this subscription is fired; contains URL to send push-notifications when the subscriber’s meetings started.

Example:

https://bin.conference.com/logger

When the event occurs, the server makes http-post to the specified URL and transfers there the event information in json-format containing:

date/time when the event occurred;
meeting number that has the event;
source of the event;
details about the meeting event (e.g. the meeting was started or ended, the call was started or ended, the recording was started or stopped, etc.)

urlToNotify

string

External URL to be called when an event associated to this subscription is fired, and the push-notification failed to reach the url.

Meeting Attribute

name	string	Attribute name
description	string	Attribute description
type	integer	Attribute type: 0 - string (default), 2 - integer, 3 - dtmf, 4 - role, 5 - choice, 6 - db reference, 7 - upload
enumValues	string	Possible attribute values if type == 5
value	string	Current value of the attribute
group	integer	Specifies a possible owner of attribute: 0 bit - CallFlow, 1 bit - Did, 2 bit - MeetingRoom

Get Meeting by ID

This request returns the full details about the Meeting referenced by the meeting number {meetingNumber} provided.

METHOD	URL
GET	/meetings/{meetingNumber}

Sample URL



curl -X GET --header "Accept: application/json;qs=1" -u : "https:///meetings/15162?excludeFields=attributes"

Request Parameters

Parameter	Data Type	Description
meetingNumber	integer	Meeting number
includeFields	string	Comma separated list fields that should be included in the response (e.g. meetingNumber,created)
excludeFields	string	Comma separated list fields that should be excluded from the response (e.g. operatorStatus, broadcastingMode or attributes)

Response Parameters

Attribute	Data Type	Description
attributes	array	Meeting attributes; the set (template) of available attributes defined for the callflow of the meeting, the attributes values may be overridden on DID and/or MeetingRoom level
broadcastingMode	string	Contains URL of the media file (audio or video) that currently is being broadcasted in the meeting, otherwise null or empty string.
created	string	Date and time when this meeting was created – the first caller arrived
duration	integer	Number of seconds which have elapsed since the meeting was created
holdMode	integer	Hold mode bitmask flag consisting of 3 groups for hosts, participants, listeners and each of the group has bits that determine whether the group is on hold or online (not on hold): bits 0,1 (host) – 0 (002) value of this flag determines that the hosts are online (not on hold), 1 (012) value of this flag determines that the hosts are self-placed on hold, 2 (102) value of this flag determines that the hosts are placed on hold by the meeting host; bits 2,3 (participant) – 0 (002) value of this flag determines that the participants are online (not on hold), 1 (012) value of this flag determines that the participants are self-placed on hold, 2 (102) value of this flag determines that the participants are placed on hold by host; bits 4,5 (listener) – 0 (002) value of this flag determines that the listeners are online (not on hold), 1 (012) value of this flag determines that the listeners are self-placed on hold, 2 (102) value of this flag determines that the listeners are placed on hold by host. For example: value 32 means that the listeners are muted and cannot un-mute themselves, participants and hosts are not muted; value 36 means that the listeners are muted and cannot un-mute themselves, participants are muted and can un-mute themselves, and hosts are not muted (mute mode – relaxed); value 40 means that the listeners and participants are muted and cannot un-mute themselves, hosts are not muted (mute mode – strict).
OperatorStatus	string	This fields represents the operator’s activity, i.e. it contains the data structure that describes the operator’s meeting.
callback	object	Callback object
participantCount	integer	Number of active participants in the meeting>
pollingMode	string	This field determines whether the polling call is started; empty string value means that the polling is not started; if the polling is started the field contains available polling options – digits 1, 2, ..., 9, 0
qaMode	integer	This field determines whether the Q&A call is started and used to manage Q&A mode; 0 - Q&A call is not started, 1 - Q&A call is started (in progress), 2 - talk to the next caller in Q&A queue, 4 - clear Q&A queue
state	integer	The status of the meeting: 0 – the meeting completed or is not started, 1 – the meeting is on hold (for instance, due the moderator is not arrived yet when it is required by the meeting configuration, see How conference begins (conference_start_how) call flow attribute value), 2 – the meeting is active. Note: there is no transition from state 2 (active) to state 1 (on hold)
subscriberName	string	Name of the first subscriber in the meeting
type	integer	This field determines whether the meeting is participating in the distributed meetings (DC, the value 1) or not (the value 0)

Operator Status

This data structure is designed to show the status of the operator’s meeting.

Attribute	Data Type	Description
engagedConferenceNumber	string	Meeting number of the connected meeting
isConnected	boolean	This field determines whether the operator’s meeting is currently connected to the other one (in this case this property is set to true)
isMonitoring	boolean	For the operator meeting this field determines whether the operator meeting is in scanning mode (i.e. surveillance call, usually started when the operator presses *1 on his phone keypad)
status	integer	This field determines operators meeting mode: MEETING_REGULAR (0), MEETING_OPERATOR (1), MEETING_LISTEN (2), MEETING_AUTOLISTEN (3), MEETING_AUTOLISTEN_SLEEP (4), MEETING_TALK (5)

Polling Mode

This data structure shows additional information on the polling call.

Attribute	Data Type	Description
status	integer	Status of the polling call
description	string	Polling call description
choices	array	Polling choices. Possible values: dtmf, value, votes
callBackUrl	string	Callback URL

Callback

Attribute

Data Type

Description

integer

Callback ID

url

string

External URL to be called when an event associated to this subscription is fired; contains URL to send push-notifications when the subscriber’s meetings started.

Example:

https://bin.conference.com/logger

When the event occurs, the server makes http-post to the specified URL and transfers there the event information in json-format containing:

date/time when the event occurred;
meeting number that has the event;
source of the event;
details about the meeting event (e.g. the meeting was started or ended, the call was started or ended, the recording was started or stopped, etc.)

urlToNotify

string

External URL to be called when an event associated to this subscription is fired, and the push-notification failed to reach the url.

Meeting Attribute

name	string	Attribute name
description	string	Attribute description
type	integer	Attribute type: 0 - string (default), 2 - integer, 3 - dtmf, 4 - role, 5 - choice, 6 - db reference, 7 - upload
enumValues	string	Possible attribute values if type == 5
value	string	Current value of the attribute
group	integer	Specifies a possible owner of attribute: 0 bit - CallFlow, 1 bit - Did, 2 bit - MeetingRoom

Hang up the Meeting

The request causes all calls to be dropped from the meeting and the meeting to be terminated (hanged up); the meeting is referenced by the meeting number {meetingNumber} provided.

METHOD	URL
DELETE	/calls/{meetingNumber}

Sample URL


curl -X DELETE --header "Accept: application/json" -u : "https:///meetings/111"

Response Parameters

Parameter	Data Type	Description
meetingNumber	integer	meeting number of the meeting that should be hanged up

Update (Change State) of Active Meeting

The request changes the meeting state of the specific meeting referenced by the meeting number {meetingNumber} with the new parameters posted in the data input. Thus this method performs the following actions

METHOD	URL
PUT	/meetings/{meetingNumber}

Sample URL


curl -X PUT --header "Accept: application/json" -u <your_user_name>:<your_password> -d "{"pollingMode": {"status": 2}}" "https://api.carrierx.com/conference/v1/meetings/14561"

Request Parameters

Parameter	Data Type	Description
meetingNumber	integer	Meeting number of the meeting that should be updated, i.e. the meeting which state should be amended
data	string	Meeting object properties; see above to determine what meeting properties should be changed and what properties’ values should be set to change the meeting state

Response Parameters

Attribute	Data Type	Description
attributes	array	Meeting attributes; the set (template) of available attributes defined for the callflow of the meeting, the attributes values may be overridden on DID and/or MeetingRoom level
broadcastingMode	string	Contains URL of the media file (audio or video) that currently is being broadcasted in the meeting, otherwise null or empty string.
created	string	Date and time when this meeting was created – the first caller arrived
duration	integer	Number of seconds which have elapsed since the meeting was created
holdMode	integer	Hold mode bitmask flag consisting of 3 groups for hosts, participants, listeners and each of the group has bits that determine whether the group is on hold or online (not on hold): bits 0,1 (host) – 0 (002) value of this flag determines that the hosts are online (not on hold), 1 (012) value of this flag determines that the hosts are self-placed on hold, 2 (102) value of this flag determines that the hosts are placed on hold by the meeting host; bits 2,3 (participant) – 0 (002) value of this flag determines that the participants are online (not on hold), 1 (012) value of this flag determines that the participants are self-placed on hold, 2 (102) value of this flag determines that the participants are placed on hold by host; bits 4,5 (listener) – 0 (002) value of this flag determines that the listeners are online (not on hold), 1 (012) value of this flag determines that the listeners are self-placed on hold, 2 (102) value of this flag determines that the listeners are placed on hold by host. For example: value 32 means that the listeners are muted and cannot un-mute themselves, participants and hosts are not muted; value 36 means that the listeners are muted and cannot un-mute themselves, participants are muted and can un-mute themselves, and hosts are not muted (mute mode – relaxed); value 40 means that the listeners and participants are muted and cannot un-mute themselves, hosts are not muted (mute mode – strict).
OperatorStatus	string	This fields represents the operator’s activity, i.e. it contains the data structure that describes the operator’s meeting.
callback	object	Callback object
participantCount	integer	Number of active participants in the meeting>
pollingMode	string	This field determines whether the polling call is started; empty string value means that the polling is not started; if the polling is started the field contains available polling options – digits 1, 2, ..., 9, 0
qaMode	integer	This field determines whether the Q&A call is started and used to manage Q&A mode; 0 - Q&A call is not started, 1 - Q&A call is started (in progress), 2 - talk to the next caller in Q&A queue, 4 - clear Q&A queue
state	integer	The status of the meeting: 0 – the meeting completed or is not started, 1 – the meeting is on hold (for instance, due the moderator is not arrived yet when it is required by the meeting configuration, see How conference begins (conference_start_how) call flow attribute value), 2 – the meeting is active. Note: there is no transition from state 2 (active) to state 1 (on hold)
subscriberName	string	Name of the first subscriber in the meeting
type	integer	This field determines whether the meeting is participating in the distributed meetings (DC, the value 1) or not (the value 0)

Operator Status

This data structure is designed to show the status of the operator’s meeting.

Attribute	Data Type	Description
engagedConferenceNumber	string	Meeting number of the connected meeting
isConnected	boolean	This field determines whether the operator’s meeting is currently connected to the other one (in this case this property is set to true)
isMonitoring	boolean	For the operator meeting this field determines whether the operator meeting is in scanning mode (i.e. surveillance call, usually started when the operator presses *1 on his phone keypad)
status	integer	This field determines operators meeting mode: MEETING_REGULAR (0), MEETING_OPERATOR (1), MEETING_LISTEN (2), MEETING_AUTOLISTEN (3), MEETING_AUTOLISTEN_SLEEP (4), MEETING_TALK (5)

Polling Mode

This data structure shows additional information on the polling call.

Attribute	Data Type	Description
status	integer	Status of the polling call
description	string	Polling call description
choices	array	Polling choices. Possible values: dtmf, value, votes
callBackUrl	string	Callback URL

Callback

Attribute

Data Type

Description

integer

Callback ID

url

string

External URL to be called when an event associated to this subscription is fired; contains URL to send push-notifications when the subscriber’s meetings started.

Example:

https://bin.conference.com/logger

When the event occurs, the server makes http-post to the specified URL and transfers there the event information in json-format containing:

date/time when the event occurred;
meeting number that has the event;
source of the event;
details about the meeting event (e.g. the meeting was started or ended, the call was started or ended, the recording was started or stopped, etc.)

urlToNotify

string

External URL to be called when an event associated to this subscription is fired, and the push-notification failed to reach the url.

Meeting Attribute

name	string	Attribute name
description	string	Attribute description
type	integer	Attribute type: 0 - string (default), 2 - integer, 3 - dtmf, 4 - role, 5 - choice, 6 - db reference, 7 - upload
enumValues	string	Possible attribute values if type == 5
value	string	Current value of the attribute
group	integer	Specifies a possible owner of attribute: 0 bit - CallFlow, 1 bit - Did, 2 bit - MeetingRoom

Get List of Meeting Attributes

The request returns the list of the call flow attributes for the started meeting referenced by the meeting number {meetingNumber} which match the filter; the list is provided according to the specified order; offset and limit parameters help to implement paging on the web application. The meeting attributes are e

METHOD	URL
GET	/meetings/{meetingNumber}/attributes

Sample URL


curl -X GET --header "Accept: application/json;qs=1" -u <your_user_name>:<your_password> "https://api.carrierx.com/conference/v1/meetings/111/attributes?offset=0&limit=20"

Request Parameters

Parameter	Data Type	Description
meetingNumber	integer	The meeting number of the meeting which attributes should be returned
limit	integer	Max number of items to return
filter	string	String criteria to use to filter the rows. The criteria should be a simple conditional statement started with one or more callflow’s attribute field names. Empty string or null or no filter parameter specified means no filter.
order	string	Specifying any single subscriber field name and sort direction. Empty string or null or no order parameter specified means no order. The default direction is ascending and asc can be omitted, for descending order use desc.

Response Parameters

name	string	Attribute name
description	string	Attribute description
type	integer	Attribute type: 0 - string (default), 2 - integer, 3 - dtmf, 4 - role, 5 - choice, 6 - db reference, 7 - upload
enumValues	string	Possible attribute values if type == 5
value	string	Current value of the attribute
group	integer	Specifies a possible owner of attribute: 0 bit - CallFlow, 1 bit - Did, 2 bit - MeetingRoom