FlexML API Reference

The CarrierX service offers a hosted FlexML Application Endpoint type that enables creating voice work-flows by passing XML instructions. Using a variety of verbs, the endpoint interprets instructions and uses them to play recordings, route calls via DTMF inputs, and implement call flow logic.

Using the REST API

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, filtering, and callbacks.

Using Postman

This documentation contains cURL commands that you will run in your terminal. Rather than use these commands, you can explore the API using Postman, a stand-alone client with a user-friendly interface. Postman is widely used for API development and allows you to test requests.

You will need to download the Postman client to your computer. To do so, visit the Postman website and click Download. Click Run in Postman to import this collection to the Postman app.

Main Conventions

The following conventions are used in the sections, which contain the tables with objects attributes, their types, and descriptions:

Authentication

The following curl command will return a list of all of the endpoints of the CarrierX account associated with the login credentials. Use your Core API token in the query below. The endpoint login and password values are listed in the returned JSON object.

curl -X GET \
'https://api.carrierx.com/core/v2/endpoints' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The credentials of a specific endpoint are found in the properties attribute of the nested object. Locate the login and password values.

{
  "count": 1,
  "has_more": false,
  "items": [
      {
          "addresses": [],
          "attributes": {},
          "capacity": 0,
          "endpoint_sid": "844346ef-93e9-4fa8-a4ab-e3015af94573",
          "name": "flexml",
          "out_sip_password": null,
          "out_sip_username": null,
          "partner_sid": "ed437757-002d-4ecc-aa5a-efdf5e50dba0",
          "properties": {
              "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
              "api_url": "https://api.carrierx.com/flexml/v1",
              "container_sid": "null",
              "login": "sample_login",
              "password": "sample_password"
          },
          "transformations": [],
          "type": "flexml",
          "voip_token": null
      }
  ],
  "limit": 1000,
  "offset": 0,
  "pagination": {},
  "total": 1
}

All CarrierX API requests require authentication. The first step to using CarrierX API is obtaining a CarrierX account and gaining credentials. To do so, please submit a request through our Contact Us page.

Currently, CarrierX API requests use two types of authentication:

• Bearer token, used by the requests to the Core API.
• Basic HTTP authentication with login and password, used by the requests to the endpoint APIs (Conference, FlexML, and Mediator).

Prior to making requests, you need to create a FlexML application endpoint. Refer to the FlexML Endpoint quick start guide for step-by-step instructions on creating a FlexML endpoint.

Requests

Sample request to create Conference endpoint

curl -X POST \
'https://api.carrierx.com/core/v2/endpoints' \
-H 'Content-Type: application/json' \
--data-binary '{"name":"my_conf", "type":"conference"}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The requests in CarrierX API are made using the standard REST notation, typical for web services.

A simplest request will have the following structure:

• The request URL to which the request will be sent. The URL will be different for the Core API methods and for the main endpoint-related requests (conference, FlexML, mediator).
• The request method or the verb used for the REST over HTTP request.
• One or several headers or user/password authentication.
  • At least one header—-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'—is required to access the Core API.
  • For the requests to the conference, FlexML, or mediator endpoints, CarrierX uses the basic HTTP authentication with login and password (cURL -u option).

  Refer to the Authentication section for more details on this.

All the above elements are required for all CarrierX API requests.

Other request may have additional structure elements which include:

• Path arguments are required with some methods to access specific objects (GET the object by secure ID, PATCH/PUT, and DELETE objects).
• Body payload is required with POST and PATCH/PUT. Even if the object method does not require any body arguments (e.g., POST for some objects), the payload must still include an empty object (--data-binary '{}').
  
• Query arguments may be either optional or required for some requests. Refer to the objects sections below to see which object methods require the presence of the query arguments. The optional query arguments available with some GET requests include pagination, result filtering, and field filtering.
• Form data is required with some POST methods, e.g., uploading a file to the container using multipart/form-data content type.

Request URL

The usual path to the API objects includes the base URL to the API used with the object (Core API base URL for the objects used throughout the CarrierX products, or specific API base URLs used for FlexML, Mediator, or Conference), and the path to the object collections and the object items.

If the action targets the specific object, the path to it will include the object secure ID (SID), which allows to distinguish the targeted object from the other ones in the same collection.

The system only accepts HTTPS requests, and not HTTP requests.

Request Methods

CarrierX API uses five main verbs (methods) of REST over HTTP for the requests: POST, GET, PUT, PATCH, and DELETE. These methods are used to create the objects, get the information about the objects, modify the objects, and delete them.

CarrierX partners need to have special permissions (or scopes) to use API methods on various objects. Refer to the available_scopes table for the complete list of the scopes that define the partner’s permissions on objects and collections.

POST

Sample POST request that creates a trunk

curl -X POST \
'https://api.carrierx.com/core/v2/trunk_groups/138ed522-6633-405b-b58d-55eb0d262e32/trunks' \
-H 'Content-Type: application/json' \
--data-binary '{}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The POST method is used to create new objects. When you create a new object, you usually need to specify at least some of the attributes for the object to be created in the request payload.

The successful POST request will return a 200 response with the serialized JSON copy of the created object.

GET

Sample GET request that returns the currently logged-in partner

curl -X GET \
'https://api.carrierx.com/core/v2/oauth/whoami' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The GET method is used to view the information about the existing objects and their collections.

Generic GET requests return the list of all the objects (or collections) available for the request sent. Most of such GET requests can be used together with Pagination, Result Filtering, and Field Filtering.

GET requests aimed at a specific object require to use the object secure ID to be included as a part of the request path, and return the information about the specified object only. Most of such GET requests can be used together with Field Filtering.

The successful GET request will return a 200 response with the serialized JSON copy of the requested objects (or specific object).

PATCH/PUT

Sample PATCH request that modifies or adds a new name record of the nested attributes object

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name":"New Partner Name"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response The serialized JSON copy of the created object together with the nested object

{
    "attributes": {
        "name": "New Partner Name"
    },
    ...,
    "partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0"
}

Sample PATCH request that adds a new name2 record of the nested attributes object of the same Partner object

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name2":"New Partner Name 2"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response The serialized JSON copy of the created object together with the modified nested object

{
    "attributes": {
        "name": "New Partner Name"
        "name2": "New Partner Name 2"
    },
    ...,
    "partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0"
}

Sample PATCH request that modifies the entire nested attributes object of the same Partner object

curl -X PATCH \
'https://api.carrierx.com/core/v2/partners/aeda835c-6627-4f4c-ac73-9edcae95640b?nested_objects=replace' \
-H 'Content-Type: application/json' \
--data-binary '{"attributes":{"name3":"New Partner Name 3"}}' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

Response The serialized JSON copy of the created object together with the nested object

{
    "attributes": {
        "name3": "New Partner Name 3"
    },
    ...,
    "partner_sid": "ed437757-001d-4ecc-aa5a-efdf5e50dba0"
}

The PATCH/PUT methods are both used to modify the existing objects and their attributes. The difference between them is explained below.

PATCH is used to modify only some of the object attributes and does not require to send the entire object in the request payload. Only the attributes and their values that need to be modified can be sent in the request body.

Objects can have a complex structure and can contain other objects as part of them, i.e., nested inside them. When you use PATCH and want to modify the nested objects, PATCH follows the below rules to define what must be updated and how:

1. If the existing nested object contains the same record (by key), the existing record will be replaced with the new value, provided in the PATCH request. The other nested object records will remain unmodified.

2. If the existing nested object does not contain the same record, a new record will be added to the object. The other nested object records will remain unmodified.

3. If the existing nested object contains the same record and the value of the incoming record is null, then the existing record will be removed. The other nested object records will remain unmodified.

4. If the PATCH request contains nested_objects=replace as a query attribute, the whole nested object will be replaced with a new one (i.e., all the old records and their values will be removed and only the new ones will be added).

PUT is used to modify the complete object and require to send the entire object (together with the nested objects, if there are any) in the request payload.

Both PATCH and PUT requests are aimed at a specific object and require the object secure ID as a part of the request path.

The successful PATCH/PUT request will return a 200 response with the serialized JSON copy of the modified object.

DELETE

Sample DELETE request that deletes an endpoint

curl -X DELETE \
'https://api.carrierx.com/core/v2/endpoints/1a34c5e9-3a09-4de5-b553-5f6a9ef202ac' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The DELETE method is used to delete the object targeted by its secure ID.

The successful DELETE request will return a 204 response code with an empty body.

Rate Limiting

Currently, CarrierX applies no rate limiting to the partners requests to CarrierX API.

Responses

All responses return conventional HTTP status codes. Most of the responses (GET, POST, PATCH/PUT) also return objects in the JSON format.

CarrierX API allows cross-origin (CORS) requests and data transfers.

HTTP Status Codes

Typical 200 status code in the response

HTTP/2 200
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Access-Control-Allow-Origin,Access-Control-Allow-Methods,Access-Control-Allow-Credentials,Content-Disposition,Access-Control-Allow-Headers
Content-Length: 1333
Content-Type: application/json
Date: Wed, 22 Sep 2021 08:23:06 GMT
Server: nginx
Strict-Transport-Security: max-age=31536000; includeSubDomains
Vary: accept-encoding

The FlexML API uses the following HTTP status codes:

Sample 400 status code when the JSON sent in the request body has errors in its syntax:

{
    "body": {
        "message": "cannot parse json. Check json for validity",
        "errors": null
    },
    "status": 400
}

Sample 401 status code when trying to send a request without authentication:

{
  "message": "authentication required",
  "errors": [
    {
      "field": "cause",
      "message": "authentication required",
      "reference_sid": null
    }
  ]
}

Sample 403 status code when trying to access resources you do not have enough permission for:

{
    "message": "permission denied",
    "errors": [
        {
            "field": "cause",
            "message": "permission denied",
            "reference_sid": null
        }
    ]
}

Sample 404 status code when trying to access a non-existent object (e.g., a token with an incorrect SID):

{
    "message": "no item error",
    "errors": [
        {
            "field": null,
            "message": "cannot find token",
            "reference_sid": null
        }
    ]
}

Response Objects

Typical formatted JSON object in the response

{
    "callback_url": null,
    "did_group_sid": "41e21049-e5eb-433c-a93d-d57417b1863c",
    "name": "N/A",
    "partner_sid": "e00430c3-a7d0-4666-ab5c-f7202448382f"
}

Successful requests return objects in the JSON format with application/json set as Content-Type. The object keys and values depend on the request and the object returned, and are described in the corresponding object sections.

Normally, the system returns the object fields unordered and unformatted. To view the object fields ordered alphabetically and “pretty-formatted” in the response to the command-line requests (e.g., cURL), use the jq command-line JSON processor or similar tools.

With jq, the request will look like this:

curl -X GET 'https://api.carrierx.com/core/v2/oauth/whoami' -H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda' | jq -S

Pagination

This request returns Country objects sorting them descending by the common_name attritute, starting with the second record available, and returns a maximum of two records.

curl -X GET \
'https://api.carrierx.com/core/v2/countries?offset=2&limit=2&order=common_name+desc' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

To view records not included in the response, make a request to the URL value of the previous or the next key.

{
  "count": 2,
  "has_more": true,
  "items": [
    {
      "capital": "Sana'a",
      "common_name": "Yemen",
      "dialing_prefix": "967",
      "domain": "ye",
      "iso_3166_alpha_2": "YE",
      "iso_3166_alpha_3": "YEM",
      "iso_3166_numeric": 887,
      "mcc": "421",
      "official_name": "Republic of Yemen",
      "region": "Asia",
      "subregion": "Western Asia"
    },
    {
      "capital": "El Aaiún",
      "common_name": "Western Sahara",
      "dialing_prefix": null,
      "domain": "eh",
      "iso_3166_alpha_2": "EH",
      "iso_3166_alpha_3": "ESH",
      "iso_3166_numeric": 732,
      "mcc": null,
      "official_name": "Sahrawi Arab Democratic Republic",
      "region": "Africa",
      "subregion": "Northern Africa"
    }
  ],
  "limit": 2,
  "offset": 2,
  "pagination": {
    "next": "https://api.carrierx.com/core/v2/countries?limit=2&order=common_name+desc&offset=4",
    "previous": "https://api.carrierx.com/core/v2/countries?limit=2&order=common_name+desc&offset=0"
  },
  "total": 251
}

You can use the pagination to limit the number of the objects returned in the response and sort them by the object attributes.

The pagination is available for the GET requests which return the lists of the objects without targeting them by secure IDs.

The pagination parameters include:

limit

An integer parameter that determines how many items are returned in the response. The entered value cannot exceed 1000.

The default value is 10, meaning that a maximum of ten items will be returned.

order

A string parameter that allows to sort the returned objects. Three values are accepted for this parameter:

• attribute name + asc to sort the items in the response in the ascending or alphabetical order (default order).
• attribute name + desc to sort the items in the response in the descending or reverse-alphabetical order.
• shuffle to randomize the order of the items in the response.

offset

An integer parameter that determines the amount of items that are skipped in the response.

The default value is 0, meaning that the first existing item will appear first.

after/ before

This request returns a maximum of one record of SMS Detail Record objects following the object with the b6d574ea-b11f-41fd-a25f-602e7b28807f secure ID.

curl -X GET \
'https://api.carrierx.com/core/v2/sms/message_drs?after=b6d574ea-b11f-41fd-a25f-602e7b28807f&limit=1' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

To view records not included in the response, make a request to the URL value of the previous key.

{
    "count": 1,
    "has_more": true,
    "items": [
        {
            "date_insert": "2020-07-24T10:25:11.000Z",
            "date_sent": "2020-07-24T10:25:11.014Z",
            "date_start": "2020-07-24T10:25:11.014Z",
            "date_stop": "2020-07-24T10:25:12.014Z",
            "delay_sent": 0,
            "direction": "outbound",
            "dr_sid": "92cd9154-2f53-4e62-8b4e-8ff6e4849d16",
            "mcc": 310,
            "media_urls": [],
            "message": "This is a test message.",
            "message_segments": 1,
            "mnc": 999,
            "number_billing": "15162065870",
            "number_dst": "12078152557",
            "number_external": "12078152557",
            "number_src": "15162065870",
            "partner_sid": "8d180104-0b34-4e55-907f-4a72409484c9",
            "price": "0.005",
            "provider": "tsg",
            "rate": "0.005",
            "status": "sent",
            "type": "sms",
            "user_data": "test_message",
            "version": null
        }
    ],
    "limit": 1,
    "offset": 0,
    "pagination": {
        "previous": "https://api.carrierx.com/core/v2/sms/message_drs?before=92cd9154-2f53-4e62-8b4e-8ff6e4849d16&limit=1&offset=0"
    },
    "total": null
}

For some objects (e.g., Call Detail Record or SMS Detail Record objects), the system will not return their total number. This can happen as the number dynamically changes in large quantities and can become not relevant by the time of the next request.

In this case, instead of using the standard pagination offset (which is rather difficult to calculate as the system does not return the total number of objects), you can use the after or before query arguments. With these arguments, the system will return the objects which precede or follow the entered object secure ID. This might be useful if you want to receive an exact range of the objects and know the secure IDs of the records which start and end this range.

Currently, CarrierX supports the pagination that uses the after and before arguments for the following objects and methods:

Request Parameters Combinations

You can use the following combinations of the pagination parameters:

• limit, offset, order: https://api.carrierx.com/core/v2/countries?limit=2&offset=2&order=common_name+desc

• after, limit, order: https://api.carrierx.com/core/v2/calls/call_drs?after=bb2aacd2-23d3-418e-9ec0-2fc45c5f9d76&limit=1&order=date_stop+asc

• before, limit, order: https://api.carrierx.com/core/v2/calls/call_drs?before=56fb6b94-811e-4952-b242-4e06f4e95b7e&limit=1&order=date_stop+desc

• after, before, limit, order: https://api.carrierx.com/core/v2/sms/message_drs?after=012e1d6a-75ac-43ec-bacc-68f1ef1c60a3&before=b6d574ea-b11f-41fd-a25f-602e7b28807f&limit=100&order=date_insert+desc

If you omit any of the parameters from the response, their default values will be used (if there are any).

Pagination Response

The JSON response for a successful query using the pagination parameters will include the following attributes:

Result Filtering

This GET request returns Endpoint objects that meet the filter criteria. In this case, we are narrowing the results to the conference endpoint type.

curl -X GET \
'https://api.carrierx.com/core/v2/endpoints?filter=type+eq+conference' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The following response includes all of the endpoints that fit the filter criteria.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "addresses": [],
            "attributes": {},
            "capacity": 0,
            "endpoint_sid": "613325f8-bbb8-4599-b477-1b4fef3d017c",
            "name": "my_example_conference",
            "partner_sid": "6nelo9p3-3eef-4f75-8f48-fb98e99908be",
            "properties": {
                "account_sid": "bdrU77AFb-Y1sDwqqxkeb.M3LP7hSKYg",
                "api_url": "https://api.carrierx.com/conference/v1",
                "container_sid": "null",
                "login": "username",
                "password": "password"
            },
            "transformations": [],
            "type": "conference",
            "voip_token": null
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 1
}

The filter parameter is added to the query URL to restrict or customize the results of a JSON response by certain parameters (e.g., name, capabilities, state, country_code, etc.). The common rule is that, with some exceptions, you can filter those results by any top-level field(s) that are returned in the response. Moreover, in some cases you can use the nested subfields for result filtering. In this case you need to use a dot in the filter name to separate the parent field and the nested subfield, e.g. trunks.allow_transfer eq false or properties.login eq username.

The structure of result filtering is as follows: filter=object_attribute filter_operator value. You can also use the and operator to combine several filters for more specific searches. For example, for a DID object we could apply the following filter: filter=state eq "NY" and phonenumber like "%555%".

Filter values can also be put inside single or double quotes. This is not necessary when the filter value is just a single word like USA. However, if your filter value consists of more than one word, the quotes are required. For example, name eq "filter value name".

Result Filtering Quick Reference

Field Filtering

In the following, we request Endpoint objects without the properties field.

curl -X GET \
'https://api.carrierx.com/core/v2/endpoints?exclude_fields=properties' \
-H 'Authorization: Bearer 5ebc03d6-8b2b-44ad-bf65-72d4f1491dda'

The following response excludes the properties field from returned Endpoint objects.

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "addresses": [],
            "attributes": {},
            "capacity": 0,
            "endpoint_sid": "613325f8-bbb8-4599-b477-1b4fef3d017c",
            "name": "my_example_conference",
            "out_sip_password": null,
            "out_sip_username": null,
            "partner_sid": "6nelo9p3-3eef-4f75-8f48-fb98e99908be",
            "transformations": [],
            "type": "conference",
            "voip_token": null
        }
    ],
    "limit": 1000,
    "offset": 0,
    "pagination": {},
    "total": 1
}

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

Field Filtering Quick Reference

FlexML Call Flow

FlexML instructions are used to create custom call flows for both inbound and outbound calls. This section goes over requests, responses, and status callbacks.

FlexML Requests

For inbound calls, the url and method from the DID object will be used. If the url value in the DID object is not set, then the url and method values from the Account object will be used instead.

For outbound calls, these values are set in the Call object. CarrierX will make a request to the URL provided, and expects to receive FlexML instructions in the response. These instructions contain a set of ordered commands that will be used to handle the call. The method value is the type of request that will be made to the url, either POST or GET.

Request Data

Successful requests return a JSON response that looks like the following:

{
    "AccountSid":"",
    "ApiVersion":"2.0",
    "CallerName":"",
    "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
    "CallStatus":"completed",
    "Direction":"inbound",
    "From":"15162065338",
    "OriginalFrom":"+15162065338",
    "OriginalTo":"15162065337",
    "RequestUrl":"https://sampleurl.com/example",
    "To":"15162065337"
}

Data about the call will be passed in the request body in the JSON format if the method is POST. Data will be passed as query parameters if the method is GET.

CallStatus Values

The following are values that appear in the CallStatus field.

In addition to the Request Data described in the table above, data can also include the URL holding the recording audio and the duration of the recording in seconds. Callback data depends on the type of FlexML instructions being executed.

Please refer to the individual verb sections for additional data returned when using those verbs.

FlexML Responses

The response to the CarrierX request should include FlexML instructions. Each set of FlexML instructions is wrapped within Response wrapper start and end tags. Tags nested inside of Response tags are called verbs, and attributes that modify these verbs are simply referred to as supported attributes. The verbs are executed from top to bottom. However, some instructions will break the flow, and the remainder of the verbs will not be executed.

Sample FlexML

<Response>
  <Gather action="http://www.example.com/path/to/handler" timeout="5">
    <Say>Please enter the extension of the party you would like to reach. </Say>
  </Gather>
  <Say>You did not enter an extension. </Say>
  <Hangup />
</Response>

In this example, once the call has been connected, the called party will be prompted by the Say message to enter the extension of the party they are trying to reach. The called party has five seconds to enter the extension because timeout is set to 5. If digits are entered, the action URL will be requested, and the FlexML instructions at that URL will be executed. The rest of the FlexML instructions in the current instructions will be ignored.

If the called party does not enter digits after the 5 seconds has elapsed, the instructions will proceed to the Say verb below Gather. Then the Hangup verb will be executed.

Status Callbacks

Data about completed calls can be received by setting status_callback_url and status_callback_method in the Call object or the DID object. The response to this request is not used. If a status_callback_url is set on both the Call object and DID object, the URL set on the Call object will be used.

The status_callback_url and status_callback_method can also be overridden using the Override verb in a FlexML response. Please refer to the Override section for more information.

Request Data

Successful requests return a JSON response that looks like the following:

{
    "AccountSid":"",
    "ApiVersion":"2.0",
    "CallDuration":8,
    "CallerName":"",
    "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
    "CallStatus":"completed",
    "Direction":"inbound",
    "From":"15162065338",
    "OriginalFrom":"+15162065338",
    "OriginalTo":"15162065337",
    "PlaybackUrl":"https://storage.carrierx.com/f/5fac56c8-c9fa-4d0e-bf88-f114e0d0cfab.mp3",
    "PlayOffset":37,
    "RequestMethod":"GET",
    "RequestUrl":"https://sampleurl.com/example",
    "To":"15162065337"
}

These status callback fields are in addition to the fields listed in the Requests section.

FlexML Syntax

FlexML, the CarrierX markup language, is used to create instructions for call logic.

The language is much like XML. It consists of special words included into opening and closing tags. Some of the tags are self-closing, i.e., they do not require a closing tag. Some of the tags can contain additional attributes in the start-tag. And some of the tags can nest values and even other tags between opening and closing tags.

The basic components of the markup language are verbs and nouns.

• FlexML verbs specify what type of action will be performed. Since the instructions are executed from top to bottom, the verbs should be ordered as such. Verbs are modified using supported attributes.

• FlexML nouns are not used by themselves. They extend FlexML verbs. They are nested inside the verbs (e.g., Dial, Play) and allow the users to specify additional parameters.

Amd (experimental)

In this example, the Amd verb will attempt to detect whether or not the other party is human or machine. If no greeting has been made before 5 seconds, the other party is determined to be machine. If the greeting exceeds 2 seconds, then the other party is determined to be machine. Additionally, the other party is determined to be human if the post-greeting silence exceeds 0.5 seconds.

When a determination has been made, or the totalAnalysisTime of 10 seconds has elapsed, a callback will be sent to the action URL via POST method.

<Response>
  <Amd action="http://www.example.com/path/to/handler"
  method="POST"
  initialSilence="5000"
  greeting="2000"
  afterGreetingSilence="500"
  totalAnalysisTime="10000" />
</Response>

AMD stands for ‘Answering Machine Detection’. The experimental Amd verb attempts to determine whether the other party is human or machine. The determination of the other party’s status will be returned in a callback and possible returned values will be as follows.

AMD Callback Attributes

Successful requests return a JSON response that looks like the following:

{
  "AccountSid": "",
  "AMDCause": "HUMAN-500-500",
  "AMDStatus": "HUMAN",
  "ApiVersion": "2.0",
  "CallerName":"",
  "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
  "Direction":"inbound",
  "From":"15162065338",
  "OriginalFrom":"+15162065338",
  "OriginalTo":"15162065337",
  "RequestUrl":"https://sampleurl.com/example",
  "To":"15162065337"
}

AMDStatus Values

These values can be returned as AMDStatus.

Supported Attributes

These attributes can be used to modify the Amd verb. They are inserted as name-value pairs in the start-tag.

Nesting Rules

• You cannot nest other verbs or nouns within the Amd verb.
• You cannot nest the Amd verb within other FlexML verbs.

Dial

To simply dial the number, include it directly inside the Dial verb without using the Number noun. In this case, FlexML instructions cannot include any additional parameters for the dialed number. In this example, the phone number inside the Dial tags will be dialed. The call total time will be limited to 15 seconds. The called party will be able to hang up by pressing the * key. If an action URL is added to the Dial verb as an attribute, a request will be made to that URL if the phone number cannot be reached, or when the call ends.

<Response>
  <Dial timeLimit="15" hangupOnStar="true">15162065340</Dial>
</Response>

The Dial verb connects the calling party with the dialed party. Once the call is set up, the participants can start talking.

When the call is ended successfully, or the dialed number is not reached, or the call is terminated, CarrierX will make a POST or GET request to the action URL.

If no action URL is set, the call flow will move to the next verbs in the FlexML instructions.

You can also place a phone number inside the Number noun. This is done to allow specifying the additional parameters (e.g., sendDigits) when dialing a phone number. Refer to the this section for more information about the Number noun.

Additionally, you can use the Number noun for the simultaneous ring to several numbers feature.

Supported Attributes

These attributes can be used to modify the Dial verb. They are inserted as name-value pairs in the start-tag.

Number Noun

In this example, once the call is answered, the wait of two seconds will be performed (the total length of four , characters, each equal to 0.5-second delay), after that the 1928 DTMF tones will be played to the dialed number.

<Response>
  <Dial>
    <Number sendDigits=",,,,1928">15162065340</Number>
  </Dial>
</Response>

The Number noun can be nested inside the Dial verb. It contains the DID number to be dialed. It supports the following attributes:

CarrierX allows dialing to several numbers at once using the Number noun. Refer to the Simultaneous Ring to Several Numbers section of the Dial verb for more information about this.

Query Arguments

In this example, two X- headers will be sent when dialing the phone number specified in the Number noun nested inside the Dial verb.

<Response>
  <Dial>
    <Number>15162065340?X-CustomHeader1=ABC&amp;X-CustomHeader2=DEF</Number>
  </Dial>
</Response>

The additional query arguments can be used to send custom headers inside the Number noun. Use the ? character after the phone number to add these headers. Several headers are joined with the XML-encoded & character.

Simultaneous Ring to Several Numbers

In this example, the phone numbers in the Number tags will be dialed all at the same time. The first person to answer is connected to the calling party.

<Response>
  <Dial>
    <Number>12345645585</Number>
    <Number>96846465465</Number>
    <Number>98133217461</Number>
  </Dial>
</Response>

CarrierX supports dialing to several numbers at once. You need to specify the numbers in the Number noun tags inside the Dial verb. The first person to answer will be connected to the calling party. The calls to the other numbers will be hung up.

Nesting Rules

• You can nest the Number noun within the Dial verb.
• You cannot nest the Dial verb within other FlexML verbs.

Dtmf

In these sample FlexML instructions, the phone number in the Dial verb is dialed, and then the characters within the Dtmf tags are entered. Each comma within the Dtmf tag is a 0.5-second delay.

<Response>
  <Dial timeLimit="15" hangupOnStar="true">
    <Number>15162065340</Number>
  </Dial>
  <Dtmf>,,,,12</Dtmf>
</Response>

The Dtmf verb enters the symbols within its tags. This can be useful when dialing a phone number with an extension.

Values accepted for the Dtmf verb are: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, #, *, ,, and the combinations of these characters. Each comma character defines a 0.5-second delay.

Nesting Rules

• You cannot nest other verbs or nouns within the Dtmf verb.
• You cannot nest the Dtmf verb within other FlexML verbs.

Gather

In these sample FlexML instructions, once the party is reached, the called party will be prompted by verbal command to enter some digits. If an action URL is set, the URL will be queried once DMTF input has been gathered according to the specifications. In this case, if the action URL was set, it would be requested once the party has entered two digits because numDigits is set to 2.

<Response>
  <Gather numDigits="2">
    <Say>Please enter the extension of the party you'd like to be connected to. </Say>
  </Gather>
</Response>

Say will read out the text within its tags.

<Response>
  <Gather timeout="10" numDigits="2" method="get" action="http://www.example.com/path/to/handler">
    <Say>Please enter two digits</Say>
  </Gather>
</Response>

Play will play the file within its tags.

<Response>
  <Gather timeout="10" numDigits="2" method="get" action="http://www.example.com/path/to/handler">
    <Play>https://www.example.com/media/my_file.wav</Play>
  </Gather>
</Response>

The Gather verb collects the digits that a calling party enters into the phone keypad. The entered data from the keypad is passed to the action URL. In the case that no input has been entered, the call will move to the next verb in the FlexML instructions.

The Say and Play verbs can be nested in the Gather verb.

Supported Attributes

In this example, the startDigits attribute is used. In this case any other keys outside the list of key(s) specified in that attribute are ignored completely until any of the start digits is entered. As soon as the start digit is entered, the intro.mp3 prompt is terminated, and the system continues accepting numeric digits until one of the following occurs:

- User enters 4 more digits, bringing the total digits count to 5, the start digit + 4 more digits.
- User enters # without entering the 4 digits.
- 10 seconds pass without input.

The /pin action is taken in any of these cases.

<Response>
  <Gather startDigits="*" validDigits="0123456789" numDigits="5" finishOnKey="#" timeout="10" action="/pin">
    <Play>intro.mp3</Play>
  </Gather>
  <Redirect>/start</Redirect>
</Response>

These attributes can be used to modify the Gather verb. They are inserted as name-value pairs in the start-tag.

Request Data

Successful requests return a JSON response that looks like the following:

{
    "AccountSid":"",
    "ApiVersion":"2.0",
    "CallerName":"",
    "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
    "CallStatus":"completed",
    "Digits": "",
    "Direction":"inbound",
    "From":"15162065338",
    "OriginalFrom":"+15162065338",
    "OriginalTo":"15162065337",
    "RequestUrl":"https://sampleurl.com/example",
    "To":"15162065337"
}

The following is an additional parameter and value that will be included in action requests.

Nesting Rules

• You can nest Play and Say verbs within the Gather verb.
• You cannot nest the Gather verb within other FlexML verbs.

Hangup

The following will hang up on the calling party. Instructions after the Hangup verb will not run.

<Response>
  <Hangup/>
</Response>

Hangup will answer the call and then immediately hang up. To reject the call without answering, use Reject instead.

Nesting Rules

• You cannot nest other verbs or nouns within the Hangup verb.
• You cannot nest the Hangup verb within other FlexML verbs.

Override

<Response>
  <Override statusCallbackUrl="http://www.example.com/path/to/handler" statusCallbackMethod="GET" />
  <Play streaming="true" timeLimit="30">
    http://www.example.com/path/to/media.mp3
  </Play>
</Response>

Supported Attributes

These attributes can be used to modify the Override verb. They are inserted as name-value pairs in the start-tag.

Nesting Rules

• You cannot nest other verbs or nouns within the Override verb.
• You cannot nest the Override verb within other FlexML verbs.

Pause

In this example, the called party will hear a welcome message, followed by a 15-second pause. Then the thank you message will play.

<Response>
  <Say>Welcome</Say>
  <Pause length="15"/>
  <Say>Thank you for your time.</Say>
</Response>

Pause stops the next verb in the FlexML instructions from executing before the number of seconds has elapsed. The Pause verb is the same as the Wait verb.

Supported Attributes

These attributes can be used to modify the Pause verb. They are inserted as name-value pairs in the start-tag.

In this example, the calling party will hear a welcome message and will be asked to say something. After that the wait for the audio input from the calling party (with a maximum delay of 15 seconds before giving up) will start.

<Response>
  <Say>Welcome</Say>
  <Say>Please announce yourself</Say>
  <Pause noise="true" minNoise="2000" silence="true" minSilence="2500" length="15" />
</Response>

Let’s say, the calling party starts talking five seconds after the call started and speaks for four seconds. This means that waiting for the audio took nine seconds totally (five of initial silence + four of audio), the remaining time will be spent on waiting for silence, and is equal to six seconds maximum. If 2.5-seconds silence follows, the whole pause will be 11.5 seconds. After that FlexML switches to the next instructions.

Nesting Rules

• You cannot nest other verbs or nouns within the Pause verb.
• You can nest the Pause verb within the PreAnswer FlexML verb.

Parameter

A sample of the parameter noun usage:

<Response>
  <Start>
    <Stream name="myStream" url="wss://example.com">
      <Parameter name="FirstName" value="John"/>
      <Parameter name="LastName" value="Cleese"/>
    </Stream>
  </Start>
</Response>

When the WebSocket server receives a Start Event, the message will include the Parameter data in start.customParameters.

{
  "event": "start",
  "sequenceNumber": 1,
  "start": {
    "callId": "7a9a4e28-1631-11ef-a79b-d4ce64f0cdf9",
    "tracks": [
      "inbound",
      "outbound"
    ],
    "mediaFormat": {
      "encoding": "audio/x-mulaw",
      "sampleRate": 8000
    },
    "customParameters": {
      "RemoteParty": "Bob",
      "FirstName": "Jane",
      "LastName":"Doe"
    }
  }
}

The Parameter noun is used to pass custom key/value pairs to a WebSocket server when streaming a call.

Supported Attributes

Nesting Rules

• You cannot nest other verbs or nouns within Parameter.
• You can nest Parameter within Stream.

Play

These FlexML instructions will play the file for the maximum duration of 30 seconds.

<Response>
  <Play timeLimit="30">
    http://www.example.com/path/to/media.mp3
  </Play>
</Response>

The same result can be achieved if file_sid is used together with the File noun instead of the direct link.

<Response>
  <Play timeLimit="30">
    <File>d620ec24-acd8-4193-9249-b89f46ee3654</File>
  </Play>
</Response>

Play will play a file to the calling party. There are two ways to specify the file to be played:

• pass the file URL between the Play tags;
• nest the File noun inside the Play verb and use the file_sid attribute of the File object which can be obtained using the Get Files request.

Once the file stops playing, CarrierX will make a POST or GET request to the action URL.

If no action URL is set, the call flow will move to the next verbs in the FlexML instructions.

If the Play file fails to play, a POST or GET request will be sent to the errorAction URL.

Supported Attributes

These attributes can be used to modify the Play verb. They are inserted as name-value pairs in the start-tag.

Request Data

Successful requests return a JSON response that looks like the following:

{
    "AccountSid":"",
    "ApiVersion":"2.0",
    "CallerName":"",
    "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
    "CallStatus":"completed",
    "Digits":"",
    "Direction":"inbound",
    "From":"15162065338",
    "OriginalFrom":"+15162065338",
    "OriginalTo":"15162065337",
    "PlaybackUrl":"https://storage.carrierx.com/f/5fac56c8-c9fa-4d0e-bf88-f114e0d0cfab.mp3",
    "PlayOffset":37,
    "RequestUrl":"https://sampleurl.com/example",
    "To":"15162065337"
}

Supported File Formats

These are the format types that will be able to play: aac, al/alaw, flac, g722, m3u8, mp3, mp4/mp4a, ogg, ul/ulaw, and wav

Supported Protocols

The audio streaming protocols are hls, http, https, and rtmp.

• http and https are supported when streaming is set to true or false.
• Use hls or rtmp to play streaming files only.

File Noun

Sample Play verb that uses the File noun together with the file_sid parameter to specify the playback file

<Response>
  <Play>
    <File>d620ec24-acd8-4193-9249-b89f46ee3654</File>
  </Play>
</Response>

The File noun can be nested inside the Play verb. It uses the file_sid attribute of the File object. This attribute specifies the secure ID of the file, which will be played to the calling party. It can be obtained using the Get Files request.

Using the secure ID instead of the link allows the partners to store the files with CarrierX storage and link these files to their FlexML application without the need to set the complete path to the file.

Nesting Rules

• You can nest the File noun within the Play verb.
• You can nest the Play verb within the Gather and PreAnswer FlexML verbs.

PreAnswer

In this example an automatic ‘Sorry, we cannot answer your call right now. Please try again later.’ message will be played to the calling party and then, after a 4-second pause, a pre-recorded message will be repeated three times. Then the call will be rejected.

<Response>
  <PreAnswer>
    <Say>Sorry, we cannot answer your call right now. Please try again later.</Say>
    <Pause length="4"></Pause>
    <Play loop="3">https://storage.carrierx.com/f/5fac56c8-c9fa-4d0e-bf88-f114e0d0cfab.mp3</Play>
  </PreAnswer>
  <Reject reason="busy"></Reject>
</Response>

The PreAnswer verb responds to the incoming call before it is answered. This is a so called early media mode: the media is sent to the calling party before the called party answers the call. This is especially useful when you want to play some custom message (e.g., to warn the calling party about some additional costs) so that they could hang up before the conversation actually starts.

You can also use the PreAnswer to set custom ringtones or to speak specified text dynamically while the call is still in an unanswered state.

Nesting Rules

• You can nest the Pause, Play, Say, and Wait verbs within the PreAnswer verb.
• You cannot nest the PreAnswer verb within other FlexML verbs.

Record

In this example, a background recording begins because recordSession is set to true. The recording is saved in the specified containerSid. Note that by default, the container used to store the recording will be the one specified in the Endpoint object. However, the container can be overridden by assigning a containerSid, as is shown here. The system will automatically generate a file inside the container, unless a fileSid is specified. The recording will fail if the container or file does not exist or is full.

<Response>
  <Record containerSid="ea55039a-3ee4-48cd-a1ff-dfb7751f1cec" recordSession="true"></Record>
  <Say>Thank you for calling. </Say>
</Response>

The Record verb records the conversation and stores it as an audio file in the specified container. Once the recording has ended, CarrierX will make a POST or GET request to the action URL.

If no action URL is set, the call flow will move to the next verbs in the FlexML instructions. If the recording fails, a POST or GET will be sent to the errorAction URL.

Supported Attributes

These attributes can be used to modify the Record verb. They are inserted as name-value pairs in the start-tag.

Supported External Storage

The following external storage services are supported to store the recording data:

• Amazon Simple Storage Service (AWS S3)
• Google Cloud Platform (GCP)
• Microsoft Azure Blob storage

You will need to provide the credentials and specify the storage location for each of the external storage used. Only one external storage can be used at a time. Refer to the tables below to learn what parameters you need to specify for each storage type.

Amazon Simple Storage Service

In this example, the background recording is saved to the specified awsBucketName of Amazon S3.

<Response>
  <Record recordSession="true" awsAccessKey="_AWS_ACCESS_KEY_" awsBucketName="_AWS_BUCKET_NAME_" awsSecretKey="_AWS_SECRET_ACCESS_KEY_"></Record>
  <Say>Thank you for calling. </Say>
</Response>

Google Cloud Platform

In this example, the background recording is saved to the specified gcpBucketName Google Cloud Platform.

<Response>
  <Record recordSession="true" gcpAccessToken="_GCP_ACCESS_TOKEN_" gcpBucketName="_GCP_BUCKET_NAME_" gcpProject="_GCP_PROJECT_"></Record>
  <Say>Thank you for calling. </Say>
</Response>

Microsoft Azure Blob Storage

In this example, the background recording is saved to the specified azureContainerName of Microsoft Azure Blob Storage.

<Response>
  <Record recordSession="true" azureAccountKey="_AZURE_ACCOUNT_KEY_" azureAccountName="_AZURE_ACCOUNT_NAME_" azureContainerName="_AZURE_CONTAINER_NAME_"></Record>
  <Say>Thank you for calling. </Say>
</Response>

Callback Returned Data

Successful requests return a JSON response that looks like the following:

{
    "AccountSid":"",
    "ApiVersion":"2.0",
    "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
    "CallStatus":"completed",
    "Direction":"inbound",
    "From":"15162065338",
    "OriginalFrom":"+15162065338",
    "OriginalTo":"15162065337",
    "RecordingDuration": 60,
    "RecordingSid": "ea662226-9f71-44fe-858f-f8b624034974",
    "RecordingStatus": "completed",
    "RecordingUrl": "https://storage.carrierx.com/f/ea662226-9f71-44fe-858f-f8b624034974",
    "To":"15162065337",
    "TranscriptionSid": "cac8582f-db8a-4c4d-82e5-3e8026435a54",
    "TranscriptionStatus": "completed",
    "TranscriptionText": "This is a transcribed recorded call text",
    "TranscriptionUrl": ""
}

The following are additional parameters and values that will be returned in action requests.

Nesting Rules

• You cannot nest other verbs or nouns within the Record verb.
• You cannot nest the Record verb within other FlexML verbs.

Redirect

In this example, the flow of the call will be redirected to the URL specified in the Redirect tags. This URL is requested using the GET method. The Say instruction after Redirect is ignored.

<Response>
  <Redirect method="GET">http://www.example.com/path/to/handler</Redirect>
  <Say>Thank you</Say>
</Response>

The Redirect verb turns over the control of the call flow to another set of FlexML instructions located at a different URL.

Nesting Rules

• You cannot nest other verbs or nouns within the Redirect verb.
• You cannot nest the Redirect verb within other FlexML verbs.

Reject

In this example, the call will be immediately rejected and the reject message to the carrier will be busy.

<Response>
  <Reject reason="busy"></Reject>
</Response>

The Reject verb does not answer a call, but instead rejects it. To ensure the incoming call is unanswered, put Reject as the first verb in Response.

Supported Attributes

These attributes can be used to modify the Reject verb. They are inserted as name-value pairs in the start-tag.

Reject Reasons

intermediary-rejected Reject Reason

In this example, the call will be rejected and the reject message to the carrier will be intermediary-rejected. My reason for rejecting the call will be returned as the additional message to the calling party as a part of the Call-Info SIP header.

<Response>
  <Reject reason="intermediary-rejected">My reason for rejecting the call</Reject>
</Response>

Sample Call-Info SIP header returned from the above Reject verb with the intermediary-rejected reject reason

Call-Info: "My reason for rejecting the call"

With the intermediary-rejected reject reason, you can additionally return the message to the calling party that will not only state the reject code, but will also explain the reason of the reject. To do this, insert the message text between the start and end Reject tags.

FlexML will return the message text as a part of the Call-Info SIP header.

Nesting Rules

• You cannot nest other verbs or nouns within the Reject verb.
• You cannot nest the Reject verb within other FlexML verbs.

Say

In this example, a thank you message will be read twice to the calling party because loop is set to 2. Between loops one and two, there will be a five second pause because loopPause is set to 5.

<Response>
  <Say voice="woman" loop="2" loopPause="5">Thank you for calling customer service</Say>
</Response>

Say converts written text to voice. This is a verbal message that the calling party will hear. Supported attributes can be added to customize the type of voice and the number of repetitions of the message.

Integers added into the Say verb will be read according to how they are entered. “123” will be read as “one hundred twenty-three” and “1 2 3” will be read as “one two three”. To add a pause in the message, close out the Say tag, insert a Pause tag, and then open a new Say tag with the rest of the text.

Supported Attributes

These attributes can be used to modify the Say verb. They are inserted as name-value pairs in the start-tag.

Nesting Rules

• You cannot nest other verbs or nouns within the Say verb.
• You can nest the Say verb within the Gather and PreAnswer FlexML verbs.

Sms

In this example, an SMS message is sent to the phone number value of to. The message body is added between the Sms tags. If no to and from attributes are added to the Sms tag, the sending party will default to the calling party, and the receiving party will default to the called party.

<Response>
  <Sms to="15162065317">Have a great day!</Sms>
</Response>

The Sms verb sends an SMS message to a phone number during a phone call. Use the attributes to define the receiving and sending parties. If an action attribute is added to the Sms verb, all verbs remaining in the current FlexML instructions are ignored. If no action is provided, the call flow will move to the next verb in the current FlexML instructions.

Supported Attributes

These attributes can be used to modify the Sms verb. They are inserted as name-value pairs in the start-tag.

Nesting Rules

• You cannot nest other verbs or nouns within the Sms verb.
• You cannot nest the Sms verb within other FlexML verbs.

Start

A sample of the Start verb usage:

<Response>
  <Start>
    <Stream name="myStream" url="wss://example.com"/>
  </Start>
</Response>

The Start verb is used to start a unidirectional media Stream. A unidirectional stream is when CarrierX sends the call audio stream to your application, but your application cannot send an audio stream to the call.

Use Stop to stop a Stream.

Start has no attributes.

Nesting Rules

• You can nest Stream within the Start verb.
• You cannot nest the Start verb within other FlexML verbs.

Stop

A sample of the Stop verb usage:

<Response>
  <Start>
    <Stream name="myStream" url="wss://example.com"/>
  </Start>
  ...
  <Stop>
    <Stream name="myStream"/>
  </Stop>
</Response>

The Stop verb is used to stop a unidirectional media Stream. The name of the Stream is used when starting and stopping the Stream.

Stop has no attributes.

Nesting Rules

• You can nest Stream within the Stop verb.
• You cannot nest the Stop verb within other FlexML verbs.

Store

In this example, the additional data identified by the key1 and key2 names will be added to the callback returned data. The data will be passed to the URL specified in the Redirect verb together with the other call data.

<Response>
  <Store name="key1">some_data</Store>
  <Store name="key2">some more data</Store>
  <Redirect>http://www.example.com/path/to/handler</Redirect>
</Response>

The Store verb allows the users to store additional data between the requests within the same call without having to pass it using either query string or some other workaround.

Supported Attributes

These attributes can be used to modify the Store verb. They are inserted as name-value pairs in the start-tag.

Callback Returned Data

Successful requests return a JSON response that looks like the following:

{
    "AccountSid":"",
    "ApiVersion":"2.0",
    "CallerName":"",
    "CallSid":"4695bc4a0932bcd2e99492e523db9ee2",
    "CallStatus":"completed",
    "Direction":"inbound",
    "From":"15162065338",
    "OriginalFrom":"+15162065338",
    "OriginalTo":"15162065337",
    "RequestUrl":"https://sampleurl.com/example",
    "Storage_key1": "some_data",
    "Storage_key2": "some more data",
    "To":"15162065337"
}

The following is an additional parameter and value that will be included in action requests.

Nesting Rules

• You cannot nest other verbs or nouns within the Store verb.
• You cannot nest the Store verb within other FlexML verbs.

Stream

To start and stop the Stream you should wrap Stream in Start tags when opening a stream and in Stop tags to stop the stream, using the name attribute to identify the stream. If you do not stop the Stream, it will continue until the end of the call.

...
<Start>
  <Stream url="wss://example.com" name="myStream">
</Start>
...
<Stop>
  <Stream name="myStream">
</Stop>
...

To pass custom key/value pairs to the WebSocket server, use Parameter.

<Stream>
  <Parameter name="First Name" value="John"/>
  <Parameter name="Last Name" value="Cleese"/>
</Stream>

Stream forks the audio streams of a call to your application in near real-time via websocket. The audio is sent as Web Socket Messages.

Stream is a background activity, meaning FlexML continues executing subsequent instructions after starting the stream.

Supported Attributes

These attributes can be used to modify Stream. They are inserted as name-value pairs in the opening tag.

Nesting Rules

• You can nest Parameter within Stream
• You can nest Stream within Start, and Stop verbs.

WebSocket Messages

Connected Event

A sample Connected Event:

{
  "event": "connected",
  "protocol": "Call",
  "version": "0.2.0"
}

CarrierX sends the connected event once a WebSocket connection is established, and is the first message your WebSocket server receives.

Connected Event Object

Start Event

A sample Start Event:

{
  "event": "start",
  "sequenceNumber": 1,
  "start": {
    "callId": "7a9a4e28-1631-11ef-a79b-d4ce64f0cdf9",
    "tracks": [
      "inbound",
      "outbound"
    ],
    "mediaFormat": {
      "encoding": "audio/x-mulaw",
      "sampleRate": 8000
    },
    "customParameters": {
      "RemoteParty": "Bob",
      "FirstName": "Jane",
      "LastName":"Doe"
    }
  }
}

The start message contains metadata about the stream and any custom Parameters. The start event is sent once immediately after the Connected Event.

Start Event Object

Start Message Object

A sample object defined by the Parameter tags included in the Stream:

<Stream>
  <Parameter name="First" value="John"/>
  <Parameter name="Last" value="Cleese"/>
</Stream>

would result in a customParameters object of:

{
  "First": "John",
  "Last": "Cleese"
}

Media Format Object

Media Event

The media message contains the actual stream content.

Media Event Object

A sample Media Event Object:

{
  "event":"media",
  "sequenceNumber":1495,
  "media":{
    "callId":"80e6178c-1701-11ef-927b-e6b664f0cdf9",
    "track":"outbound",
    "timestamp":14712,
    "chunk":736,
    "payload":"sUhORChD6K6nr6aqpq3CP0yxra/ePPDeNmj7fL65qq/vNSxaVi0nSaqurdnHuG++uFhCy7GyWzQtw7dOO2atu9s7N0s4M0U7O8m8trziatqsyDtQQj8sMUZZt2hassFtSdP2PTw5TE85MkvE1UDbv9jOLzT2OTAtP1W0sb2qrtpYu2Q6LzpOOzswWb+/607Gy7t1Oc05JzBHUTE+urHOuQ=="
  }
}

Media Message Object

Stop Event

The stop event is sent once per call, is the last message sent, and represents the end of all streamed tracks.

Stop Event Object

A sample Stop Event Object:

{
  "event":"stop",
  "sequenceNumber":433,
  "callId":"f68c10b6-1708-11ef-9daa-27d264f0cdf9"
}

Wait

Wait stops the next verb in the FlexML instructions from executing before the number of seconds has elapsed. The Wait verb is the same as the Pause verb. Please refer to the Pause section for more information.

Nesting Rules

• You cannot nest other verbs or nouns within the Wait verb.
• You can nest the Wait verb within the PreAnswer FlexML verb.

API Reference

The FlexML API has the following sections: Accounts, Calls, and DIDs.

• Use the Account object to modify call settings.
• Target the Call object to create, modify, and delete phone calls.
• The DID object holds modifiable data about phone numbers rented through CarrierX.

Accounts

Each FlexML Application Endpoint has its own Account object. The Account object holds the settings for that specific FlexML Application Endpoint. Changes made to the Account object will affect all of the calls associated with that particular account.

Account Object

This section outlines the Account object. The fields listed in the table below will be returned in a JSON object when a successful request has been made.

Sample Account object

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "date_created": "2023-09-20T21:56:49.000Z",
    "error_handler": "basic",
    "login": "flexml_user_123",
    "method": "POST",
    "name": "John Smith",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": null
}

Get Accounts

GET /accounts
Returns accounts matching the criteria in the request URL

curl -X GET \
'https://api.carrierx.com/flexml/v1/accounts' \
-u 'flexml_user_123:qwerty123'

Response 200 status code with a list of Account objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
            "date_created": "2023-09-20T21:56:49.000Z",
            "error_handler": "basic",
            "login": "flexml_user_123",
            "method": "POST",
            "name": "John Smith",
            "status_callback_method": "POST",
            "status_callback_url": null,
            "url": null
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request shows accounts data for the currently logged-in partner.

This request is enabled for Pagination, Result Filtering, and Field Filtering.

Get Account by SID

GET /accounts/{account_sid}
Returns an account, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/flexml/v1/accounts/1d4adc32-45d1-4789-9780-928049e2bce1' \
-u 'flexml_user_123:qwerty123'

Response 200 status code with a serialized copy of the Account object

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "date_created": "2023-09-20T21:56:49.000Z",
    "error_handler": "basic",
    "login": "flexml_user_123",
    "method": "POST",
    "name": "John Smith",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": null
}

This request will return data for an account, targeted by secure ID.

This request is enabled for Field Filtering.

Path Arguments

Update Account

PATCH /accounts/{account_sid}
Updates the Account object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/flexml/v1/accounts/1d4adc32-45d1-4789-9780-928049e2bce1' \
-H 'Content-Type: application/json' \
--data-binary '{"method":"POST", "error_handler": "none"}' \
-u 'flexml_user_123:qwerty123'

Response 200 status code with a serialized copy of the updated Account object

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "date_created": "2023-09-20T21:56:49.000Z",
    "error_handler": "none",
    "login": "flexml_user_123",
    "method": "POST",
    "name": "John Smith",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": null
}

This request updates an account, targeted by secure ID.

An Account object can be updated using either a PATCH or PUT request.

• A PATCH request can be used to update one or more attribute values. When using a PATCH request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The account secure ID is passed in the query URL, and the values to be modified are passed in the request body.

• A PUT request can be used to update an entire Account object. The account secure ID is passed in the query URL, and the entire Account object is passed in the request body.

Path Arguments

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

• error_handler
• method
• name
• url

Refer to this table to view all fields that appear in the Account object.

Calls

Calls occur when the CarrierX system dials out to a phone number. FlexML instructions are added to the call flow by setting the url parameter.

Call Object

This section goes over the parts of the Call object. These fields and values make up the JSON response that gets returned when a request is successful. In this section, there is also information about the optional fields that can be added to further customize calls. These fields can be added when initially creating the binding, or they can be added later using PATCH or PUT requests.

Sample Call object

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "attributes": {},
    "call_sid": "2f367eb5-adc6-4413-b603-533e2a8f0804",
    "called_did": "15162065318",
    "calling_did": "15162065319",
    "date_created": "2018-10-16T20:59:18.094Z",
    "delay": 0,
    "method": "POST",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": null
}

Attribute Object

The following are attributes that can be added to the Call object.

Create Call

POST /calls
Creates a call

curl -X POST \
'https://api.carrierx.com/flexml/v1/calls' \
-H 'Content-Type: application/json' \
--data-binary '{"calling_did":"15162065319", "called_did":"15162065318"}' \
-u 'flexml_user_123:qwerty123'

Response 200 status code with a serialized copy of the Call object

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "attributes": {},
    "call_sid": "2f367eb5-adc6-4413-b603-533e2a8f0804",
    "called_did": "15162065318",
    "calling_did": "15162065319",
    "date_created": "2018-10-16T20:59:18.094Z",
    "delay": 0,
    "method": "POST",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": null
}

This request creates a call.

Body Arguments

JSON representation of the fields and values of the Call object to be created.

Required fields to create a call are:

• called_did
• calling_did

The calling_did should be one of the DIDs assigned to the FlexML endpoint.

To schedule a call to happen in the future, set the delay parameter to the amount of seconds to wait before the call is executed.

Refer to this table to view all fields that appear in the Call object.

Get Calls

GET /calls
Returns calls matching the criteria in the request URL

curl -X GET \
"https://api.carrierx.com/flexml/v1/calls" \
-u 'flexml_user_123:qwerty123'

Response 200 status code with a list of Call objects

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
            "attributes": {},
            "call_sid": "9dc690bb-a627-4af6-95be-0e259250d8df",
            "called_did": "15162065317",
            "calling_did": "15162065319",
            "date_created": "2018-10-16T21:56:49.000Z",
            "delay": 9993,
            "method": "POST",
            "status_callback_method": "POST",
            "status_callback_url": null,
            "url": null
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request will return a list of Call objects scheduled for some time in the future.

All Call objects that are returned will have a delay parameter of more than 0. By default, the delay parameter is set to 0, so calls will be executed immediately after they are created.

This request is enabled for Pagination, Result Filtering, and Field Filtering.

Get Call by SID

GET /calls/{call_sid}
Returns a call, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/flexml/v1/calls/9dc690bb-a627-4af6-95be-0e259250d8df' \
-u 'flexml_user_123:qwerty123'

Response 200 status code with a serialized copy of the Call object

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "attributes": {},
    "call_sid": "9dc690bb-a627-4af6-95be-0e259250d8df",
    "called_did": "15162065317",
    "calling_did": "15162065319",
    "date_created": "2018-10-16T21:56:49.000Z",
    "delay": 9916,
    "method": "POST",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": null
}

This request returns data for a call, targeted by secure ID.

The call_sid must be passed in the path arguments.

This request is enabled for Field Filtering.

Path Arguments

Update Call

PATCH /calls/{call_sid}
Updates the Call object, targeted by secure ID, with the values in the request body

curl -X PATCH \
'https://api.carrierx.com/flexml/v1/calls/9dc690bb-a627-4af6-95be-0e259250d8df' \
-H 'Content-Type: application/json' \
--data-binary '{"delay": 1000}' \
-u 'flexml_user_123:qwerty123'

Response 200 status code with a serialized copy of the updated Call object

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "attributes": {},
    "call_sid": "9dc690bb-a627-4af6-95be-0e259250d8df",
    "called_did": "15162065317",
    "calling_did": "15162065319",
    "date_created": "2018-10-16T21:56:49.000Z",
    "delay": 1000,
    "method": "POST",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": null
}

This request updates a call, targeted by secure ID.

A Call object can be updated using either a PATCH or PUT request.

• A PATCH request can be used to update one or more attribute values. When using a PATCH request, only the attributes specified in the request payload will be updated, all other attributes and values will remain the same. The call secure ID is passed in the query URL, and the values to be modified are passed in the request body.

• A PUT request can be used to update an entire Call object. The call secure ID is passed in the query URL, and the entire Call object is passed in the request body.

Path Arguments

Body Arguments

JSON representation of the fields and values to be updated.

Fields that can be modified are:

• attributes
• called_did
• calling_did
• delay
• method
• status_callback_method
• status_callback_url
• url

Refer to this table to view all fields that appear in the Call object.

Delete Call

DELETE /calls/{call_sid}
Deletes a call, targeted by secure ID

curl -X DELETE \
'https://api.carrierx.com/flexml/v1/calls/9dc690bb-a627-4af6-95be-0e259250d8df' \
-u 'flexml_user_123:qwerty123'

Response 204 status code with an empty body

This request deletes a call, targeted by secure ID.

Path Arguments

DIDs

DIDs are phone numbers rented through CarrierX. They serve as calling_did values.

DID Object

This section describes the fields of the DID object. These fields and values are returned as the JSON object that gets returned with successful requests.

Sample DID object

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "country_code": "USA",
    "did_sid": "d72c0ec3-c21d-4db1-8877-690cb9644fbc",
    "in_country_format": "(516) 206-5319",
    "international_format": "+1 516-206-5319",
    "method": "POST",
    "phonenumber": "15162065319",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": null
}

Get DIDs

GET /dids
Returns DIDs matching the criteria in the request URL

curl -X GET \
'https://api.carrierx.com/flexml/v1/dids' \
-u 'flexml_user_123:qwerty123'

Response 200 status code with a list of DID objects associated with the endpoint

{
    "count": 1,
    "has_more": false,
    "items": [
        {
            "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
            "country_code": "USA",
            "did_sid": "d72c0ec3-c21d-4db1-8877-690cb9644fbc",
            "in_country_format": "(516) 206-5319",
            "international_format": "+1 516-206-5319",
            "method": "POST",
            "phonenumber": "15162065319",
            "status_callback_method": "POST",
            "status_callback_url": null,
            "url": null
        }
    ],
    "limit": 10,
    "offset": 0,
    "pagination": {},
    "total": 1
}

This request returns a list of DIDs associated with a FlexML Application Endpoint.

This request is enabled for Pagination, Result Filtering, and Field Filtering.

Get DID by SID

GET /dids/{did_sid}
Returns a DID object, targeted by secure ID

curl -X GET \
'https://api.carrierx.com/flexml/v1/dids/d72c0ec3-c21d-4db1-8877-690cb9644fbc' \
-u 'flexml_user_123:qwerty123'

Response 200 status code with a serialized copy of the DID object

{
    "account_sid": "1d4adc32-45d1-4789-9780-928049e2bce1",
    "country_code": "USA",
    "did_sid": "d72c0ec3-c21d-4db1-8877-690cb9644fbc",
    "in_country_format": "(516) 206-5319",
    "international_format": "+1 516-206-5319",
    "method": "POST",
    "phonenumber": "15162065319",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": null
}