FlexML Quick Start Guide

A detailed guide to using the FlexML endpoint through the CarrierX Portal and programmatically.

Overview


The FlexML endpoint is used to create simple or complex call flows. A request is made to a URL containing FlexML instructions, which are a series of verbs that perform specific actions sequentially, such as Say and Record .



Initial Setup


In this section, we will go over creating a FlexML endpoint through the portal. Then we will associate a phone number with that endpoint.

1. To set up a FlexML endpoint, log into your CarrierX account. On the left-side menu, locate and click on the Configure menu. Click Endpoints .



2. Click Add New Endpoint .



3. Enter a name for the new endpoint. This is a friendly name that is used for internal reference.



4. Check Provision Trunk Group to create a trunk group alongside the endpoint. A trunk group determines where a call should be routed. Trunks route calls to the appropriate endpoint by identifying the DID, or phone number, dialed and matching it to the trunk group that the DID is assigned to.

This guide includes instructions on assigning a DID to a trunk group. For more information about trunk groups and how to manage them programmatically, please refer to the Core API Reference Guide .



5. Choose FlexML from the Select Endpoint Type dropdown menu.



6. Click Create Endpoint .



7. To assign a phone number to the new trunk group created alongside the FlexML endpoint, navigate back to the Configure menu and click Phone Numbers . This phone number will be associated with this endpoint only, but multiple phone numbers can be associated with the same endpoint.



8. Click a phone number that you would like to associate with the endpoint trunk group. In this example, we are selecting a phone number with no trunk group assigned to it already. You can select a phone number with an assigned trunk group and reassign it.



9. Once an available phone number is selected, scroll down and click Edit .



10. Select the endpoint you want to associate the phone number with from the dropdown list.



11. Click Save .



Now that we have configured a FlexML endpoint and associated a phone number, we can move on to creating a simple voice application.



Build a Simple Voice Application


In this section, we will build a simple voice application with Python, Flask , and ngrok , which we will use for inbound and outbound calls. An application can be built using any language and tools you are familiar with.

1. Start with a hello.py file inside your project directory. Install Flask. Create the following POST route, which returns FlexML:

from flask import Flask
app = Flask(__name__)

@app.route('/hello', methods=['POST'])
def hello():
  return '<Response><Say>Hello, thank you for calling.</Say></Response>'


2. In your terminal, start your Flask server.

FLASK_APP=hello.py flask run


3. We are using a free tool called ngrok to expose our localhost application to the internet. The service needs to be reachable on the public internet so that your endpoint can access and load the FlexML instructions.

Install ngrok and then run the command with the port number that your local server is running on. In this example, our server is running on port 5000 .

./ngrok http 5000


When ngrok is run successfully, the following data will show in the terminal window. The URL in the red box is now accessible publicly on the internet.



Configure Inbound Calls


In this section, we will add the handler URL to the DID associated with the FlexML endpoint trunk group. When inbound calls are made to the DID, a request to the URL will be triggered. In our example, when individuals call the DID, they will hear the message nested inside the Say verb.

1. Under the Configure menu, click Phone Numbers .



2. Click the phone number associated with the FlexML endpoint trunk group.



3. Scroll down and click the Application: FlexML tab. Then click Edit .



4. Enter the ngrok link into the URL textbox.



5. Click Save .



Make Outbound Calls


In this section, we will make an outbound call from our terminal.

1. Before making a request, we need to find our credentials for the FlexML endpoint we would like to create the outbound call from. Navigate to Endpoints under the Configure menu to locate API credentials that can be used to programmatically communicate with the API. Select the endpoint you would like to work with and scroll down to see the API Base URL , API Login , and API Password .

Note that there is a unique login and password for each endpoint.



2. Form a POST request with at least calling_did and called_did passed in the request body. We are also passing a value containing the URL for the simple FlexML voice application we created. If we do not pass a url field and value, the url will default to the one set on the DID. This is useful if you do not want to set the url each time in the FlexML instructions. Refer to the DIDs section in the FlexML Reference Guide for information on how to set the url on the DID object.

When called_did answers, a request will be made to the FlexML URL. In this example, the called party will hear the message that we configured in the Build a Simple Voice Application section.

Since no delay field or value is set, the call is placed immediately.

curl -X POST \
'https://api.carrierx.com/flexml/v1/calls' \
-H 'Content-Type: application/json' \
--data-binary '{"calling_did":"19093189029", "called_did":"15162065575", "url":"https://fdc4165a.ngrok.io/hello"}' \
-u '[your_username]:[your_password]'


A successful response will return a 200 status code and a JSON object that looks like the following. Note that the request can be successful, yet the call can still fail to go through. For example, this can happen because your account is not configured to allow outbound calls or because the system doesn't recognize the called_did as valid.

{
    "account_sid": "99844092-3fe2-4d94-b9b4-318fdf4255ce",
    "attributes": {},
    "call_sid": "52aa2963-be4d-4186-b344-7afa68969c3c",
    "called_did": "15162065575",
    "calling_did": "19093189029",
    "date_created": "2019-02-15T20:24:15.736Z",
    "delay": 0,
    "method": "POST",
    "status_callback_method": "POST",
    "status_callback_url": null,
    "url": "https://fdc4165a.ngrok.io/hello"
}