The CarrierX service offers a hosted Conference Application Endpoint that enables two or more parties to speak to one another. Parties call into a meeting room, which stores the meeting configurations, call flow attributes, and meeting key information. Call flows determine how the call is handled.
This section describes how to obtain credentials to use the API, what types of requests the system recognizes, and the format of the responses. It also holds reference information about Pagination and Filtering.
API requests require authentication. To obtain a free CarrierX account and gain credentials, provide an email address on the homepage . The credentials used to log in to the CarrierX website are the same credentials used to access the Core API.
Prior to creating a meeting room and establishing call flows, a Conference Application Endpoint needs to be created. See the Configuring Application Endpoints Quick Start Guide for step-by-step instructions on creating an endpoint. In the JSON response for a newly created Conference Application Endpoint, there will be a login and password. These are the credentials to use when working with that particular endpoint. Note that each endpoint has its own set of credentials.
Entering the Core API credentials instead of the endpoint-specific credentials when working with the Conference API will return the error
unauthorized
.
The following curl command will return a list of all of the endpoints associated with a CarrierX account. Use the Core API and CarrierX website login credentials in this query. The conference endpoint
login
and
password
will be listed in the returned JSON object.
curl -X GET \
'https://api.carrierx.com/core/v2/endpoints' \
-u '[your_user_name]:[your_password]'
{
"count": 2,
"has_more": false,
"items": [
{
"addresses": [
{
"direction": "any",
"ip": "10.1.10.69",
"port": 5060,
"transport": "udp"
}
],
"attributes": {},
"capacity": 0,
"endpoint_sid": "7fc3e7ea-a0df-4de1-836f-50318ed66466",
"name": "System Gateway",
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"properties": {},
"transformations": [],
"type": "system_gateway",
"voip_token": null
},
{
"addresses": [],
"attributes": {},
"capacity": 0,
"endpoint_sid": "d4f87d69-4199-4de4-ab60-22348e2bf52a",
"name": "conference",
"partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
"properties": {
"account_sid": "lkHm962PjvduiUK9LFGvYG.rr0LIhqNH",
"api_url": "https://api.carrierx.com/conference/v1",
"container_sid": "ea55039a-3ee4-48cd-a1ff-dfb7751f1cec",
"login": "sample_conference_123",
"password": "Kgp7L45erAfz"
},
"transformations": [],
"type": "conference",
"voip_token": null
}
],
"limit": 1000,
"offset": 0,
"pagination": {},
"total": 2
}
API requests require authentication. Refer to the section above for more information about obtaining login credentials. Endpoint credentials are passed using HTTP basic authentication. Pagination and Filtering parameters are passed as part of the query URL. Object fields and values are added to the request body.
The conference API has the following base URL:
https://api.carrierx.com/conference/v1
Note that the system only accepts HTTPS requests, and not HTTP requests.
All responses are returned in JSON format with a status code. For common errors returned, refer to the HTTP Status Codes section.
For a comprehensive list of returned attributes refer to the Subscriber Object Reference , Meeting Room Object Reference , Call Flow Object Reference , DID Object Reference , DID Group Object Reference , Call Object Reference , and Meeting Object Reference .
The four optional parameters for pagination are:
offset
,
limit
,
order
, and
filter
.
GET
requests use these three parameters to dictate how many items should be skipped in the response, the amount of records to return, and in what order the results should appear.
offset
determines the amount of items that are skipped in the response. If there are five records and the
offset
value is
2
, the response will not include the first two records. Instead, it will return records for items three through five. The default value for
offset
is
0
, meaning that the first existing item will appear first.
The parameter
limit
determines how many items are returned in the response. The default limit is
10
, meaning that a maximum of ten items will be returned. If the number of items that exist exceeds the
limit
value, the
has_more
value in the response will be set to
true
. Responses also have a
total
field, which is the total amount of results that match the search criteria. Note that the field total will be
null
on objects that are uncountable.
The last parameter of Pagination is
order
. There are two values accepted for this parameter,
asc
and
desc
.
asc
is short for ascending and is the default order. Enter the field name to be ordered followed by either
asc
or
desc
. For example,
name desc
will return names sorted in reverse-alphabetical order. Since the default is
asc
, entering just
name
will sort the results by name in alphabetical order.
The JSON response for a successful query using the Pagination parameters
offset
,
limit
, and
order
will include a
pagination
parameter. The value of
pagination
will be empty if there are no more records existing outside of the queried parameters. If there are existing records outside of the query, the Pagination value will include
next
or
previous
URLs. These URLs can be used to obtain the remainder of the records available without modifying the original query. Simply construct another
GET
request with the URL provided in this field.
curl -X GET \
'https://api.carrierx.com/conference/v1/dids?offset=2&limit=4' \
-u '[your_user_name]:[your_password]'
{
"count": 0,
"has_more": false,
"items": [],
"limit": 4,
"offset": 2,
"pagination": {
"previous": "https://api.carrierx.com/conference/v1/dids?limit=4&offset=0"
},
"total": 0
}
Parameter | Data Type | Description |
---|---|---|
filter
optional
|
string |
Use the
filter
operators to find records according to specific criteria. Please reference the Relational Operator Quick Reference table above in this section for specific definitions and examples.
|
offset
optional
|
integer |
The amount of items skipped in the response.
0
is the default value. This parameter and value are added to the query URL.
|
limit
optional
|
integer |
The number of items to be shown in the response. The value entered should not exceed
1000
.
10
is the default value. This parameter and value are added to the query URL.
|
order
optional
|
string |
The name of the field to be ordered followed by the order of the response data, either
asc
or
desc
. The field to be ordered is listed first, followed by the order value.
For example:
binding_sid desc
.
asc
is the default order. This parameter and values are added to the query URL.
|
The parameter
filter
is used to restrict or customize the JSON response. Operators can be combined for more specific searches, and are added to the query URL.
Operator | Definition | Example |
---|---|---|
eq |
equal to. This search looks for exactly the value entered. In the example, results will have the exact value
"my_mediator"
for the
name
field.
|
name eq "my_mediator"
|
ne |
not equal to. This search returns records that do not include the value
"my_mediator"
for the
name
field.
|
name ne "my_mediator"
|
gt |
greater than. This search returns records where the value is exceeded for the field listed. For example, records are returned where the value of
maximum_ttl
is greater than
40000
.
|
maximum_ttl gt 40000
|
ge |
greater than or equal to. This search returns records where the value is greater than or equal to the field listed. For example, records are returned where the value of
wait_origination_did_ttl
is greater than or equal to
70000
.
|
wait_origination_did_ttl ge 70000
|
lt |
less than. This search returns records where the value is less than the field listed. For example, records are returned where
maximum_ttl
is less than
10000
.
|
maximum_ttl lt 10000
|
le |
less than or equal to. This search returns records where the value is less than or equal to the field listed. For example, records are returned where
wait_origination_did_ttl
is less than or equal to
90000
.
|
wait_origination_did_ttl le 90000
|
like |
contains the value indicated in the string passed.
%
can be added anywhere as part of the string to indicate that there can exist text before or after the string parts. In the example, the command looks for a name starting with "Account". This form of search is case sensitive. Note that this method of search will also work:
name like "A%t"
, and this search will yield records with
name
values beginning with
A
and ending in
t
.
|
name like "Account%"
|
ilike |
same functionality as
like
but case insensitive.
|
name like "AccOUnt%"
|
in |
the current value of the specified field must be contained within the specified list. The following example will return records that have a
status
value of either
"active"
or
"suspended"
.
|
status in ("active", "suspended")
|
There are two parameters associated with field filtering:
include_fields
, and
exclude_fields
. By default, the fields included in JSON responses are specific to the request made. These returned fields are explained in the Object Reference section for that object.
Refer to the specific object to determine which fields can be included and excluded from the JSON responses.
include_fields
and
exclude_fields
accept comma-separated strings as values.
Parameters and values for field filtering are added to the query URL.
curl -X GET \
'https://api.carrierx.com/mediator/v1/bindings?exclude_fields="name"' \
-u '[your_user_name]:[your_password]'
Parameter | Data Type | Description |
---|---|---|
include_fields
optional
|
string | The comma separated list of fields to be included in the response. The fields depend on the object. See the Object Reference section for that object to see which fields return. |
exclude_fields
optional
|
string | The comma separated list of fields to be excluded from the response. The fields depend on the object. See the Object Reference section for that object to see which fields return. |
The Conference API is used to host audio conferencing for up to 1,000 attendees. Meeting rooms are configurable objects that hold the settings for meetings. End-users dial a phone number and enter an access code, which the system uses to determine which meeting room they will be connected to.
Access codes correspond with the three access levels: host, participant, and listener. Each access level has settings which determine how the party is treated during a meeting. For example, settings on the Meeting Room object can determine that all listeners will be muted upon entering the meeting.
A Meeting Room object holds other configurations called Meeting Attributes , which dictate how the call is handled. A Meeting object is created in real time once a meeting starts. The start of a meeting is determined by meeting room settings. For example, a meeting can begin once a host calls in, or a meeting can start once any party calls in.
A Call object is also created in real time when a call begins. Meeting and Call objects are real-time elements that only exist as long as a meeting is happening and as long as there are callers in the meeting.
Once a meeting is finished, the Meeting object is deleted, along with all of the Call objects associated with the meeting.
Call flows define the way that calls are handled. There are two call flows that can be chosen from when creating a meeting room. The call flows are
CONF
and
SPECTEL
. The
CONF
call flow enables callers to enter a conference room with an access code associated with the meeting room. Alternatively, the
CONF
call flow also enables creating a meeting on the fly by entering a random access code.
The
SPECTEL
call flow only accepts access codes associated with the meeting room.
Call flows are set at the creation of a new Meeting Room object. The
attributeTemplates
values of the Call Flow object serve as default settings. These settings can be overridden in various places once the Meeting Room object has been created.
This section outlines the Call Flow object. The attributes listed in the table below will be returned in a JSON object when a successful request has been made.
Attribute | Data Type | Description |
---|---|---|
attributeTemplates | array | The attributes belonging to the call flow. Refer to the table below for a comprehensive list of the format of attributes. For a list of the attributes themselves, refer to the Meeting Attributes section. |
id | integer | The call flow ID. Note that this ID may differ for each user. |
name | string | The call flow name. |
path | string | This field is for internal use only. |
Attribute | Data Type | Description |
---|---|---|
description | string | The description of the attribute. |
enumValues | string |
If the
type
is
Enum
, this attribute will be automatically populated with possible values.
|
group | integer |
Defines the levels at which the call flow attribute value can be overridden. Integer values denote the call flow attribute can be overridden at the following object levels:
|
name | string | The attribute name. |
type | integer |
The attribute type. Possible values for this field are:
|
value | string | The attribute value. |
This request returns a list of call flows that match the optional filters provided. This request is enabled for Pagination and Field Filtering. Refer to the
Using the REST API
section for more information. Note that a request with no filtering will return
attributeTemplates
for the call flow.
Method | URL |
---|---|
GET | /callFlows |
curl -X GET \
'https://api.carrierx.com/conference/v1/callFlows?excludeFields=attributeTemplates' \
-u '[your_use_name]:[your_password]'
{
"callFlows": [
{
"id": 1,
"name": "SPECTEL",
"path": "/usr/local/DNCA/callflows/SPECTEL"
},
{
"id": 3,
"name": "CONF",
"path": "/usr/local/DNCA/callflows/CONF"
}
],
"last": 0,
"offset": 0,
"total": 2
}
A successful response will return a
200
status code. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
This request returns call flow details. This request is enabled for Field Filtering .
Method | URL |
---|---|
GET | /callFlows/{ID} |
Parameter | Data Type | Description |
---|---|---|
id
required
|
integer | The ID of the call flow. |
curl -X GET \
'https://api.carrierx.com/conference/v1/callFlows/1?excludeFields=attributeTemplates' \
-u '[your_user_name]:[your_password]'
{
"id": 1,
"name": "SPECTEL",
"path": "/usr/local/DNCA/callflows/SPECTEL"
}
A successful response will return a
200
status code. Below is a common error that arises when getting a call flow by ID. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
Response Code | Message | Description |
---|---|---|
404 | Not found | The object does not exist. Ensure that the correct call flow ID was entered correctly into the URL. |
Calls are created by the server automatically when a user dials a phone number associated with a meeting room. This object is used to access information about a current call. When the call is over, the Call object is deleted.
Note that a meeting room can have multiple calls. Each participant calling into a meeting room will be represented with a Call object.
This section outlines the Call object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.
Field | Data Type | Description |
---|---|---|
accessCode | string | The access code entered by the caller. This field is required when creating a new call. |
addressFrom | string | The phone number and SIP data of the calling party. |
addressTo | string | The phone number and SIP data of the called. |
bridgeName | string | The hosted bridge name. |
callee | string | The DID being dialed. This field is required when creating a new call. |
caller | string | The phone number of the calling party. This field is required when creating a new call. |
codec | string | The audio codec of the call. |
connectionStatus | integer |
This field indicates the call direction. Accepted values for this field are as follows:
|
created | string | The date and time when the call was created. |
customName | string | The custom name of the call. |
duration | integer | The number of seconds since the call was started. |
gainLevel | integer | The microphone level for the call. |
holdMode | integer |
Determines whether or not the call is currently on hold. Accepted values in this field are:
|
id | integer | The unique ID of the call. |
joined | string | The time that the caller joined the meeting. |
meetingNumber | string | The meeting number. |
muteMode | integer |
There are four mute states. Note that muting can be set by the host, or participants can mute themselves. The following are the values:
|
nodeName | string | The name of the hosted node. |
operatorMode | integer |
Represents operator activity. Possible values for this field are:
|
presenterMedia | integer |
The media for the call chunk. Valid values for this field are:
|
qaMode | integer |
The mode for the current call when in Q&A mode. Valid values for this field are:
|
role | integer |
Determines the call role. The roles should be the same as in
MeetingKey
. The
MeetingKey
is an object containing an access code and role.
Use the value
0
for recordings or undefined.
|
state | integer |
Defines the call state. Valid values for this field are:
|
This request returns a list of calls. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.
Method | URL |
---|---|
GET | /calls |
curl -X GET \
'https://api.carrierx.com/conference/v1/calls' \
-u '[your_user_name]:[your_password]'
{
"calls": [
{
"accessCode": "111",
"addressFrom": "\"+15162065319\" ",
"bridgeName": "MIA-QA-FCC4D",
"callee": "15162065318",
"caller": "+15162065319",
"codec": "PCMU",
"connectionStatus": 0,
"created": 1544643810000,
"customName": "",
"duration": 171,
"gainLevel": 0,
"holdMode": 0,
"id": 6889184,
"joined": 1544643810000,
"meetingNumber": 106131,
"muteMode": 0,
"nodeName": "10.2.114.15",
"presenterMedia": 0,
"qaMode": 0,
"role": 1,
"state": 2
}
],
"last": 0,
"offset": 0,
"total": 1
}
A successful response will return a
200
status code. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
This request returns details for a specific call.
Method | URL |
---|---|
GET | /calls/{id} |
Parameter | Data Type | Description |
---|---|---|
id
required
|
integer | The ID of the call. |
curl -X GET \
'https://api.carrierx.com/conference/v1/calls/6889184' \
-u '[your_user_name]:[your_password]'
{
"accessCode": "111",
"addressFrom": "\"+15162065319\" ",
"bridgeName": "MIA-QA-FCC4D",
"callee": "15162065318",
"caller": "+15162065319",
"codec": "PCMU",
"connectionStatus": 0,
"created": 1544643810000,
"customName": "",
"duration": 238,
"gainLevel": 0,
"holdMode": 0,
"id": 6889184,
"joined": 1544643810000,
"meetingNumber": 106131,
"muteMode": 0,
"nodeName": "10.2.114.15",
"presenterMedia": 0,
"qaMode": 0,
"role": 1,
"state": 2
}
A successful response will return a
200
status code. Below is a common error that arises when getting a call by ID. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
Response Code | Message | Description |
---|---|---|
404 | Not found | The call does not exist. Ensure that the correct call ID was entered correctly into the URL. |
This request changes the call state.
Method | URL |
---|---|
PUT | /calls/{id} |
Parameter | Data Type | Description |
---|---|---|
id
required
|
integer | The call ID. |
Data Type | Description |
---|---|
object |
The Call object properties to be updated. Refer to the
Call Object Reference
for more information about the parameters in the Call object. Fields that can be changed are:
|
curl -X PUT \
'https://api.carrierx.com/conference/v1/calls/144' \
-H 'Content-Type: application/json' \
--data-binary '{"customName": "name"}' \
-u '[your_user_name]:[your_password]'
A successful response will return a
200
status code. Below is a common error that arises when updating the Call object using a PUT request. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
Response Code | Message | Description |
---|---|---|
400 | Invalid field specific | Ensure that the parameter is spelled correctly and has been properly added. |
This request hangs up the call.
Method | URL |
---|---|
DELETE | /calls/{ID} |
Parameter | Data Type | Description |
---|---|---|
id
required
|
integer | The ID of the call to be deleted. |
curl -X DELETE \
'https://api.carrierx.com/conference/v1/calls/174' \
-u '[your_user_name]:[your_password]'
A successful response will return a
204
status code.
DIDs are phone numbers rented through CarrierX.
This section outlines the DID object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.
Field | Data Type | Description |
---|---|---|
attributes | array | Additional attributes that can be set to modify a DID. Refer to the table below for a list of preset attributes. |
countryCode | string | The region of the DID. The format for this field is ISO 3166-1 alpha 2. |
description | string | The code of the country in ISO 3166-1 alpha-2 format. |
didGroupId | string | The ID of the DID group to which the DID belongs. |
id | string | The unique ID of a specific DID. |
phoneNumber | string | The phone number in E.164 format. |
Field | Data Type | Description |
---|---|---|
name | string | The attribute name. |
description | string | The attribute description. |
type | integer |
The attribute type. Accepted values for this field are as follows:
|
enumValues | string |
The possible attribute values if the attribute type is
5
.
|
value | string |
The value of the DID attribute. Accepted values for this field are as follows:
|
This request will return a list of DIDs associated with the specific endpoint. This request is enabled for Pagination and Field Filtering. Refer to the
Using the REST API
section for more information.
Method | URL |
---|---|
GET | /dids |
curl -X GET \
'https://api.carrierx.com/conference/v1/dids' \
-u '[your_user_name]:[your_password]'
{
"dids": [
{
"attributes": [],
"countryCode": "US",
"didGroupId": 219,
"id": 220,
"phoneNumber": "15162065319",
"state": -1
},
{
"attributes": [],
"countryCode": "US",
"didGroupId": 219,
"id": 221,
"phoneNumber": "15162065318",
"state": -1
}
],
"last": 1,
"offset": 0,
"total": 2
}
A successful response will return a
200
status code. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
This request returns the data associated with the specified DID. This request is enabled for Field Filtering .
Method | URL |
---|---|
GET | /dids/{id} |
Parameter | Data Type | Description |
---|---|---|
id
required
|
integer | The ID of the specific DID. |
curl -X GET \
'https://api.carrierx.com/conference/v1/dids/220' \
-u '[your_user_name]:[your_password]'
{
"attributes": [],
"countryCode": "US",
"didGroupId": 219,
"id": 220,
"phoneNumber": "15162065319",
"state": -1
}
A successful response will return a
200
status code. Below is a common error that arises when getting a DID by ID. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
Response Code | Message | Description |
---|---|---|
404 | Not found | The DID does not exist. Ensure that the correct DID ID was entered into the URL. |
A DID Group is a set of phone numbers rented through CarrierX and associated with a specific conference. The system will automatically assign phone numbers into a DID group when they are routed to a Conference endpoint.
This section outlines the DID Group object. The attributes listed in the table below will be returned in a JSON object when a successful request has been made.
Parameter | Data Type | Description |
---|---|---|
attributes | array | Refer to the Meeting Attributes section for a comprehensive list of attributes. |
callFlowId | string | The ID of the call flow. |
description | string | The description of the DID group. |
dids | array |
An array of the DIDs belonging to the DID group. Each object in the array contains
attributes
,
countryCode
,
didGroupId
,
id
,
phoneNumber
, and
state
. Refer to the table below for a description of these attributes.
|
id | string | The ID of the DID group. |
name | string | The name of the DID group. |
state | integer | The state of the DID group. |
subscriberSid | string | The secure ID of the subscriber associated with the DID group. |
Parameter | Data Type | Description |
---|---|---|
attributes | array | The DID attributes. |
countryCode | integer | The country code of the DID. |
didGroupId | integer | The DID Group ID. |
id | integer | The DID ID. |
phoneNumber | string | The phone number. |
state | string | The state of the DID. |
This request returns a list of DIDs associated with the specific conference. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.
Method | URL |
---|---|
GET | /didGroups |
curl -X GET \
'https://api.carrierx.com/conference/v1/didGroups' \
-u '[your_user_name]:[your_password]'
{
"didGroups": [
{
"attributes": [],
"callFlowId": 3,
"description": "",
"dids": [
{
"attributes": [],
"countryCode": "US",
"didGroupId": 219,
"id": 221,
"phoneNumber": "15162065319",
"state": -1
},
{
"attributes": [],
"countryCode": "US",
"didGroupId": 219,
"id": 220,
"phoneNumber": "15162065318",
"state": -1
}
],
"id": 219,
"name": "sample_conference_008_didGroup",
"state": -1,
"subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}
],
"last": 0,
"offset": 0,
"total": 1
}
A successful response will return a
200
status code. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
This request returns a DID group targeted by the DID group secure ID.
Method | URL |
---|---|
GET | /dids/{id} |
Parameter | Data Type | Description |
---|---|---|
id
required
|
integer | The ID of the DID group. |
curl -X GET \
'https://api.carrierx.com/conference/v1/didGroups/219' \
-u '[your_user_name]:[your_password]'
{
"attributes": [],
"callFlowId": 3,
"description": "",
"dids": [
{
"attributes": [],
"countryCode": "US",
"didGroupId": 219,
"id": 221,
"phoneNumber": "15162065319",
"state": -1
},
{
"attributes": [],
"countryCode": "US",
"didGroupId": 219,
"id": 220,
"phoneNumber": "15162065318",
"state": -1
}
],
"id": 219,
"name": "sample_conference_008_didGroup",
"state": -1,
"subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}
A successful response will return a
200
status code. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
A Meeting object is generated once a meeting begins. The object only exists as long as the meeting is occuring.
This section outlines the Meeting object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.
Attribute | Data Type | Description |
---|---|---|
attributes | array | The meeting attributes. These attributes define the call flow of the meeting. They can be overridden in the DID and Meeting Room objects. Refer to the attributes table below for a description of the object structure. Refer to the Meeting Attributes section for a comprehensive list of the attributes. |
created | string | The date and time when the meeting was created. |
duration | integer | The number of seconds that have elapsed since the meeting was created. |
holdMode | integer |
Whether meeting participants and listeners are on hold. Values that will appear in this field are either
0
or
40
.
0
means that no parties are on hold.
40
means that participants and listeners have been placed on hold by the meeting host. When callers are on hold, they will hear music while the hosts have a private discussion.
Note that this value does not change. It is reflective of the initial hold state when the meeting starts.
|
id | integer |
The meeting ID. Note that when using
GET
,
PUT
, and
DELETE
requests, the
meetingNumber
should be used instead of this value.
|
isRecording | boolean | Determines whether or not recording is currently on. |
isSecured | boolean | Determines whether or not the meeting is secured. |
meetingNumber | integer |
The meeting number. Note that this is the value used to target a specific meeting in
GET
,
PUT
, and
DELETE
requests.
|
muteMode | integer |
There are three mute states. The following values reflect which access level parties have been muted:
|
participantCount | integer | The number of participants in the meeting. |
qaMode | integer |
The state of a Q&A meeting. Possible values in this field are:
|
state | integer |
The state of the meeting. Possible values in this field are:
|
subscriberName | string | The name of the first subscriber in the meeting. |
type | integer |
Defines whether or not the meeting is participating in distributed meetings. If yes, the field value will be
1
and if no,
the field value will be
0
.
|
Refer to the
Meeting Attributes
section for a comprehensive list of the attributes. This section describes the structure of the
attribute
objects.
Attribute | Data Type | Description |
---|---|---|
description | string | The attribute description. |
type | integer |
The attribute type. Valid values for this field are:
|
enumValues | string |
The possible attribute values if the type is
5
.
|
value | string | The value of the attribute. |
group | integer |
Defines the owner of the attribute. Valid values for this field are:
|
This request returns a list of active meetings. This request is enabled for Pagination and Field Filtering. Refer to the Using the REST API section for more information.
Method | URL |
---|---|
GET | /meetings |
curl -X GET \
'https://api.carrierx.com/conference/v1/meetings' \
-u '[your_user_name]:[your_password]'
{
"last": 0,
"meetings": [
{
"attributes": [],
"created": 1544729701000,
"duration": 48,
"holdMode": 0,
"id": 196938,
"isRecording": false,
"isSecured": false,
"meetingNumber": 106131,
"muteMode": 32,
"participantCount": 1,
"qaMode": 0,
"state": 2,
"subscriberName": "John Smith",
"type": 1
}
],
"offset": 0,
"total": 1
}
A successful response will return a
200
status code. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
This request returns a Meeting object, targeted by the
meetingNumber
. The
meetingNumber
is passed in the query URL. Note that the
id
should not be used to target the meeting. This request is enabled for
Field Filtering.
Method | URL |
---|---|
GET | /meetings/{meetingNumber} |
Parameter | Data Type | Description |
---|---|---|
meetingNumber
required
|
integer | The meeting number. |
curl -X GET \
'https://api.carrierx.com/conference/v1/meetings/106131' \
-u '[your_user_name]:[your_password]'
{
"attributes": [],
"created": 1544742875000,
"duration": 504,
"holdMode": 0,
"id": 196939,
"isRecording": false,
"isSecured": false,
"meetingNumber": 106131,
"muteMode": 32,
"participantCount": 1,
"qaMode": 0,
"state": 2,
"subscriberName": "John Smith",
"type": 1
}
A successful response will return a
200
status code. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
This request returns a list of call flow attributes associated with the specified meeting. Pass the
meetingNumber
in the query URL. This request is enabled for Pagination and Field Filtering. Please refer to the
Using the REST API
section for more information.
Method | URL |
---|---|
GET | /meetings/{meetingNumber}/attributes |
Parameter | Data Type | Description |
---|---|---|
meetingNumber
required
|
integer | The meeting number. |
curl -X GET \
'https://api.carrierx.com/conference/v1/meetings/111/attributes?limit=5' \
-u '[your_user_name]:[your_password]'
[
{
"name": "conference_exittones",
"value": "on"
},
{
"name": "conference_qa_policy",
"value": "p"
},
{
"name": "conf_participants_count",
"value": "0"
},
{
"name": "conf_hosts_count",
"value": "1"
},
{
"name": "conf_listeners_count",
"value": "0"
},
{
"name": "participant_list",
"value": "5626245432:15162065310:'2756'"
}
]
A successful response will return a
200
status code. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
This request is used to change the state of a meeting. The
meetingNumber
is passed in the query URL and the
body
parameter is sent in the request body. Note that the
meetingNumber
and not the
id
is passed.
Method | URL |
---|---|
PUT | /meetings/{meetingNumber} |
Parameter | Data Type | Description |
---|---|---|
meetingNumber
required
|
integer | The meeting number. |
Data Type | Description |
---|---|
object |
The meeting properties to be updated. Refer to the
Meeting Object Reference
for more information about the parameters in the Meeting object. Fields that can be changed are:
|
curl -X PUT \
'https://api.carrierx.com/conference/v1/meetings/106131' \
-H 'Content-Type: application/json' \
--data-binary '{"pollingMode": {"status": 2}}' \
-u '[your_user_name]:[your_password]'
{
"attributes": [],
"created": 1544742875000,
"duration": 23,
"holdMode": 0,
"id": 196939,
"isRecording": false,
"isSecured": false,
"meetingNumber": 106131,
"muteMode": 32,
"participantCount": 1,
"qaMode": 0,
"state": 2,
"subscriberName": "John Smith",
"type": 1
}
A successful response will return a
200
status code. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
This request drops all calls from a meeting and deletes the meeting instance. The
meetingNumber
is passed in the query URL. Not that the
id
is not used to target the meeting.
Method | URL |
---|---|
DELETE | /calls/{meetingNumber} |
Parameter | Data Type | Description |
---|---|---|
meetingNumber
required
|
integer | The meeting number. |
curl -X DELETE \
'https://api.carrierx.com/conference/v1/meetings/106131' \
-u '[your_user_name]:[your_password]'
A successful response will return a
204
status code. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
Meetings rooms hold meeting configurations, overridden call flow values, and contain role information. Access codes are also set at the Meeting Room object level. These are DTMF sequences entered by callers, and determine the role of the caller. The three roles are: host, participant, and listener. For example, a caller may enter an access code for a host role and gain the ability to mute participants and listeners.
This section outlines the Meeting Room object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.
Field | Data Type | Description |
---|---|---|
attributes | array | Preset attributes that can be modified. Please refer to the Meeting Attributes section for a comprehensive list of attributes. |
didGroupReferences | array |
Data about the DID Group associated with the meeting room. This information includes the
didGroupId
and
state
. Refer to the table below for more information.
|
keychain | array |
Contains the access codes and matching roles. Please refer to the table below for more information. The keychain array can be modified through a
PUT
request. When creating a
PUT
request, include
accessCode
and
role
.
|
meetingNumber | integer |
The meeting number. This number is used in
GET
,
PUT
, and
DELETE
requests.
|
primaryDidGroupId | integer | The DID Group associated with the meeting. |
subscriberSid | string | The secure ID of the subscriber. |
The didGroupReference array contains the
didGroupId
and
state
. The
didGroupId
references the DID group containing the phone numbers that can be dialed to access a Meeting Room.
Field | Data Type | Description |
---|---|---|
didGroupId | integer | The DID Group ID. |
state | integer |
The state of the DID Group. Accepted values in this field are:
|
The keychain array holds the meeting access codes. The three access levels are host, participant, and listener. Note that there can be multiple access codes for each access level.
Field | Data Type | Description |
---|---|---|
accessCode | string | The DTMF sequence that callers enter to access a meeting. This sequence is customizable. |
id | integer | The ID of the access code and role association. |
role | integer |
The role associated with the access code. Accepted values in this field are:
|
This request creates a new meeting room using the data passed in the query body. To create a meeting room,
primaryDidGroupId
and
callFlowId
are required. This information can be found by sending a
GET
request to the
didGroups
URL. Refer to the
Get DID Group
section for more information. The response will contain an
id
, which will be passed in the
body
parameter as
primaryDidGroupId
. The returned
callFlowId
will also need to be passed in the body when creating a new Meeting Room.
Note that the
meetingNumber
is not the meeting access code. The access codes for each access level are stored in the
keychain
array.
Method | URL |
---|---|
POST | /meetingRooms |
Data Type | Description |
---|---|
object |
The parameters and values of the Meeting Room object to be created. Required fields to create a Meeting Room object are
primaryDidGroupId
and
callFlowId
. Refer to the
Meeting Room Object Reference
for a list of all fields that appear in the Meeting Room object.
|
curl -X POST \
'https://api.carrierx.com/conference/v1/meetingRooms' \
-H 'Content-Type: application/json' \
--data-binary '{"primaryDidGroupId": 219, "callFlowId": 3}' \
-u '[your_user_name]:[your_password]'
{
"attributes": [],
"created": 1544482680000,
"didGroupReferences": [
{
"didGroupId": 219,
"state": 0
}
],
"keychain": [],
"meetingNumber": 273751,
"primaryDidGroupId": 219,
"subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}
A successful response will return a
201
status code. Below are some common errors that occurs when creating a meeting room. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
Response Code | Message | Description |
---|---|---|
400 | Wrong value |
Ensure that a
primaryDidGroupId
and
callFlowId
were included in the request body with correct values.
|
400 | Object validation error |
Ensure that a
primaryDidGroupId
and
callFlowId
were included in the request body.
|
This request returns a list of meeting rooms. This request is enabled for Pagination and Field Filtering. Please refer to the Using the REST API section for more information.
Method | URL |
---|---|
GET | /meetingRooms |
curl -X GET \
'https://api.carrierx.com/conference/v1/meetingRooms?excludeFields=attributes' \
-u '[your_user_name]:[your_password]'
{
"last": 0,
"meetingRooms": [
{
"created": 1544482680000,
"didGroupReferences": [
{
"didGroupId": 219,
"state": 0
}
],
"keychain": [],
"meetingNumber": 273751,
"primaryDidGroupId": 219,
"subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}
],
"offset": 0,
"total": 1
}
A successful response will return a
200
status code. Refer to the
HTTP Status Codes
section for a list of common errors.
This request returns information about a meeting room. The meeting room ID is passed in the query URL. Note that the response to this request will return an extensive list of attributes when no filters have been applied. This request is enabled for Field Filtering .
Method | URL |
---|---|
GET | /meetingRooms/{meetingNumber} |
Parameter | Data Type | Description |
---|---|---|
meetingNumber
required
|
integer | The meeting room number. |
curl -X GET \
'https://api.carrierx.com/conference/v1/meetingRooms/273751?excludeFields=attributes' \
-u '[your_user_name]:[your_password]'
{
"attributes": [],
"created": 1544482680000,
"didGroupReferences": [
{
"didGroupId": 219,
"state": 0
}
],
"keychain": [],
"meetingNumber": 273751,
"primaryDidGroupId": 219,
"subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}
A successful response will return a
200
status code. Refer to the
HTTP Status Codes
section for a list of common errors.
This request updates an existing meeting room.
Method | URL |
---|---|
GET | /meetingRooms/{meetingNumber} |
Parameter | Data Type | Description |
---|---|---|
meetingNumber
required
|
string | The meeting number of the meeting to be updated. |
Data Type | Description |
---|---|
object |
The Meeting Room fields to be updated. Please refer to the
Meeting Room Object Reference
for more information. Fields that can be changed are:
|
curl -X PUT \
'https://api.carrierx.com/conference/v1/meetingRooms/273751' \
-H 'Content-Type: application/json' \
--data-binary '{"description":"Another description"}' \
-u '[your_user_name]:[your_password]'
{
"attributes": [],
"created": 1544482680000,
"description": "Another description",
"didGroupReferences": [
{
"didGroupId": 219,
"state": 0
}
],
"keychain": [],
"meetingNumber": 273751,
"primaryDidGroupId": 219,
"subscriberSid": "yIMW9.jKxffi2EyM.afDmeO.gke.9fe0"
}
A successful response will return a
200
status code. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
This request deletes a meeting room.
Method | URL |
---|---|
DELETE | /meetingRooms/{meetingNumber} |
Parameter | Data Type | Description |
---|---|---|
meetingNumber
required
|
string | The meeting number of the meeting room to be deleted. |
curl -X DELETE \
'https://api.carrierx.com/conference/v1/meetingRooms/452650' \
-u '[your_user_name]:[your_password]'
A successful response will return a
204
status code. Refer to the
HTTP Status Codes
section for a comprehensive list of errors.
The following are preset attributes of the Meeting Room object. Some fields accept a string containing the first letter of the access level name. The three access levels are
host
,
participant
, or
listener
. To enable the feature for all three, enter the string
hpl
. To enable the feature for one access level, enter the first letter of the word. For example,
participant
is
p
.
These attributes are set at either the Meeting Room, DID Group, or DID object levels. For each of these levels, the meeting attributes will be passed as a value of
attributes
as an array of objects.
Attribute | Data Type | Description | Where to Set |
---|---|---|---|
call_announceparticipantcount | string | Determines for which access levels the number of participants will be announced upon entering the meeting room. Enter the access levels as a string. | Meeting Room object, DID Group object |
call_associate_dtmf | string | Determines which access levels will be able to associate calls. | Meeting Room object, DID Group object |
call_associate_dtmf_binding | string | The DTTMF sequence to associate audio. | DID Group object |
call_delay | integer | The number of seconds to delay before the call is answered. | DID Group object, DID object |
call_exit_dtmf | string |
Determines which access levels will be able to enter the DTMF sequence to leave a call. The DTMF sequence is set as
call_exit_dtmf_binding
.
|
Meeting Room object, DID Group object |
call_exit_dtmf_binding | string |
Determines the DTMF sequence that will trigger exiting a call when
call_exit_dtmf
is enabled.
|
DID Group object |
call_instructions_dtmf | string |
Determines which access levels will be able to enter the DTMF sequence to access the help playback. Enter the access levels as a string for the field value. The DTMF sequence is set as
call_instructions_dtmf_binding
.
|
Meeting Room object, DID Group object |
call_instructions_dtmf_binding | string |
The DTMF sequence that will trigger the help playback for the access levels designated in
call_instructions_dtmf
.
|
DID Group object |
call_jobcodeonenter | string |
Determines whether or not the caller will be prompted for a job code prior to entering the meeting. Accepted values in this field are
on
and
off
.
|
Meeting Room object, DID Group object |
call_maxduration | integer | The maximum duration of the call. | Meeting Room object, DID Group object |
call_mute_dtmf | string | Determines which access levels can mute themselves. Enter the access levels as a string for the field value. | Meeting Room object, DID Group object |
call_mute_dtmf_binding | string | The DTMF sequence that triggers self muting. | DID Group object |
call_operator_after | integer |
Determines how many times an unsuccessful attempt can be made to enter the access code. Enter
-1
to allow unlimited amounts of unsuccessful atempts.
|
DID Group object |
call_operator_dtmf | string | Determines which access levels can call the operator. Enter the access levels as a string for the field value. | Meeting Room object, DID Group object |
call_operator_dtmf_binding | string | The DTMF sequence that triggers a call to the operator. | DID Group object |
call_participantsnumber_dtmf | string | Determines which access levels can enter the DTMF sequence to hear the number of participants currently in the conference. Enter the access levels as a string for the field value. | Meeting Room object, DID Group object |
call_participantsnumber_dtmf_binding | string | The DTMF sequence that triggers stating the number of participants in the conference. | DID Group object |
conference_appspecific | string | Application-specific data. | Meeting Room object, DID Group object |
conference_callerdb | string |
The callers database. Accepted values in this field are
on
and
off
.
|
Meeting Room object, DID Group object |
conference_country | string | The conference country. | Meeting Room object, DID Group object |
conference_distributed | string |
Determines whether or not distributed conferencing is enabled. Accepted values in this field are
on
and
off
.
|
Meeting Room object, DID Group object |
conference_entryexittones_dtmf | string |
Determines which access levels can change the entry and exit tone by entering a DMTF sequence. Entering the DTMF sequence will alternate through the following combinations:
ON:ON
,
ON:OFF
,
OFF:ON
, and
OFF:OFF
.
|
Meeting Room object, DID Group object |
conference_entryexittones_dtmf_binding | string |
The DTMF sequence that triggers the change between the tone combinations outlined in
conference_entryexittones_dtmf
.
|
DID Group object |
conference_entrytones | string |
Determines whether or not a noise will be played when a new participant joins the conference. Accepted values in this field are
on
and
off
.
|
Meeting Room object, DID Group object |
conference_exittones | string |
Determines whether or not a noise will be played when a new participant exits the conference. Accepted values in this field are
on
and
off
.
|
Meeting Room object, DID Group object |
conference_hold_dtmf | string | Determines which access levels will be able to put a conference on hold. | Meeting Room object, DID Group object |
conference_hold_dtmf_binding | string | The DTMF sequence that will trigger putting a conference on hold. | DID Group object |
conference_hold_policy | string | Determines which access levels will be on hold at the beginning of the conference. Enter the access levels as a string for the field value. | Meeting Room object, DID Group object |
conference_jobcode_dtmf | string |
Allows participants to enter the
*
key during conference followed by a job code. Enter the access levels as a string for the field value.
|
Meeting Room object, DID Group object |
conference_jobcode_dtmf_binding | string | The DTMF sequence to trigger entering a job code. | DID Group object |
conference_language | string |
Determines the language of the meeting. The default value of this field is
EN
. Refer to the table below for all of the currrently supported languages.
|
Meeting Room object, DID Group object |
conference_lock_dtmf | string | Determines which access levels can lock a conference, meaning that no more participants can join. Note that hosts are still able to join even if lock is enabled. Enter the access levels as a string for the field value. | Meeting Room object, DID Group object |
conference_lock_dtmf_binding | string | The DTMF sequence that triggers locking a conference. | DID Group object |
conference_maxcalls | string | The maximum number of calls per conference. | Meeting Room object, DID Group object |
conference_maxcallsperrole | string |
The maximum number of calls per role per conference. The following denotes that there can be an unlimited amount of calls from each role:
-1:-1:-1
.
|
Meeting Room object, DID Group object |
conference_maxduration | integer |
The maximum duration of the conference. To enable the conference to endure indefinitely, assign the value
-1
.
|
Meeting Room object, DID Group object |
conference_mute_dtmf | string | Determines which access levels are able to mute other participants. Enter the access levels as a string for the field value. | Meeting Room object, DID Group object |
conference_mute_dtmf_binding | string | The DTMF sequence to trigger mutting other participants. | DID Group object |
conference_mute_policy | string | Defines which roles will be muted at the beginning of the conference. Enter the access levels as a string for the field value. | Meeting Room object, DID Group object |
conference_qa_dtmf | string | Determines which access levels can start a Q&A session. Enter the access levels as a string for the field value. | Meeting Room object, DID Group object |
conference_qa_dtmf_binding | string | The DTMF sequence to trigger starting a Q&A session. | DID Group object |
conference_qa_policy | string | Determines which access levels will be muted when a Q&A session is started. Enter the access levels as a string for the field value. | Meeting Room object, DID Group object |
conference_realtime | string |
Defines whether or not the conference generates real time notifications, which allows viewing attendee lists and control the conference from a computer. Accepted values in this field are
on
and
off
.
|
Meeting Room object, DID Group object |
conference_recording | string |
Defines whether or not a recording will begin once the meeting starts. Accepted values in this field are
on
,
off
,
and
auto
.
auto
means that the recording will begin as soon as the conference begins.
|
Meeting Room object, DID Group object |
conference_rollcall | string |
Determines whether or not participants will be prompted to record their names upon entering the conference. Accepted values in this field are
on
and
off
.
|
Meeting Room object, DID Group object |
conference_rollcall_onenter | string |
Determines whether or not the recordings of participants saying their names will be played upon entering the conference. Accepted values in this field are
on
and
off
.
|
Meeting Room object, DID Group object |
conference_rollcall_onexit | string |
Determines whether or not recordings of the participants saying their names will be played upon exiting the conference. Accepted values in this field are
on
and
off
.
|
Meeting Room object, DID Group object |
conference_schedule | string | The conference schedule. | Meeting Room object, DID Group object |
conference_schedule_extend | string | The conference schedule extended maximum time in seconds. | DID Group object |
conference_schedule_extend_dtmf | string | Defines the access levels that will be able to extend a conference schedule. | Meeting Room object, DID Group object |
conference_schedule_extend_dtmf_binding | string | The DMTF sequence that will trigger extending the schedule conference. | DID Group object |
conference_schedule_hold | integer | The amount of time in seconds to wait before the scheduled conference begins. | Meeting Room object, DID Group object |
conference_schedule_remind | integer | The amount of time in seconds to wait before the scheduled conference reminder. | Meeting Room object, DID Group object |
conference_scheduled | string |
Defines whether or not a conference is scheduled. Accepted values in this field are
on
and
off
.
|
Meeting Room object, DID Group object |
conference_start_how | string |
Determines when the conference will begin. Accepted string values in this field are
first
,
moderator
,
and
explicit
.
|
Meeting Room object, DID Group object |
conference_start_wait | integer | The number of seconds to wait before starting a meeting when a moderator has not entered the meeting. | Meeting Room object, DID Group object |
conference_stop_how | string |
Determines whether the meeting will end when the moderator exits, or when the last participant exits. Accepted string values in this field are
last
and
moderator
.
|
Meeting Room object, DID Group object |
conference_stop_wait | integer | The number of seconds to wait before stopping the conference after the host disconnects. | Meeting Room object, DID Group object |
conference_video_policy | string | Determines which access levels will have video enabled at the beginning of a conference. Enter the access levels as a string for the field value. | Meeting Room object, DID Group object |
conference_whitelist | string |
Defines whether or not the conference has a whitelist.
Accepted values in this field are
on
and
off
.
|
Meeting Room object, DID Group object |
dnis_welcomeprompt | URL | The URL to a recorded greeting. | DID Group object, DID object |
polling_dtmf | string | Determines which access levels can start a polling vote. | Meeting Room object, DID Group object |
polling_dtmf_binding | string | The DTMF sequence to trigger starting a polling vote. | DID Group object |
recording_addr | string | The recording server address. | DID Group object |
recording_dtmf | string | Determines which access levels are able to start a recording. Enter the access levels as a string for the field value. | Meeting Room object, DID Group object |
recording_dtmf_binding | string | Defines the DTMF sequence that triggers starting a recording of the meeting. | DID Group object |
recording_metadata | string |
Defines the recording metadata passing method. Values accepted in this field are
contact
and
custom
.
|
DID Group object |
recording_method | string |
Determines the recording method. Values accepted in this field are:
remote
,
remote+pin
,
local
, and
local+pin
.
|
DID Group object |
recording_stop_how | string |
Determines the recording method. Values accepted in this field are:
last
and
moderator
.
|
Meeting Room object, DID Group object |
recording_stop_wait | integer | Defines the amount of seconds to wait before stopping recording after the moderator has left the conference. | Meeting Room object, DID Group object |
recording_stop_wait | integer | Defines the amount of seconds to wait before stopping recording after the moderator has left the conference. | Meeting Room object, DID Group object |
recording_stop_wait | integer | Defines the amount of seconds to wait before stopping recording after the moderator has left the conference. | Meeting Room object, DID Group object |
Code | Language |
---|---|
EN | English (default) |
AR | Argentinian |
DE | German |
EL | Greek |
ES | Spanish (Spain) |
ES-LATAM | Spanish (Latin America) |
FR | French |
GB | British English |
HE | Vietnamese |
IT | Italy |
JA | Japanese |
KO | Korean |
NL | Dutch |
PT | Portugese (Portugal) |
PT-BR | Portugese (Brazil) |
RU | Russian |
TR | Turkish |
UA | Ukrainian |
UK | Ukrainian (Ukraine) |
ZH | Chinese |
This section lists the HTTP status codes the API returns with each request. Note that additional error codes and messages are listed in the sections to which they pertain.
Response Code | Message | Description |
200 | OK | The request has succeeded. The information returned with the response depends on the method used in the request. |
201 | Created | The request has succeeded and a resource has been created. |
204 | No Content |
The request has succeeded and the body is empty. This is typically seen when
using a
DELETE
request.
|
Response Code | Message | Description |
400 | Bad request | The request could not be understood by the server due to incorrect syntax. The client should not repeat the request without modifications. |
400 | No JSON object could be decoded | Generally an indicator that there is a syntax error. |
401 | Unauthorized | The request requires correct user authentication. |
401 | Bad credentials | The request requires correct user authentication. |
403 | Forbidden | The server understood the request, but is refusing to fulfill it. Authorization will not help and the request should not be repeated. |
404 | Not found | The requested resource was not found on the server. |
404 | Cannot find object by SID | The SID number does not exist. Verify that the SID has been entered correctly. |
500 | Internal server error | The server encountered an unexpected condition which prevented it from fulfilling the request. |