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,



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

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

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

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

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