shell

FlexML Endpoint

In this guide, you will learn how to configure a FlexML endpoint. 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.

I. Create Endpoint

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

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.

Click Endpoint

Click Add New Endpoint.

New Endpoint

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

Friendly Name

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.

Trunk Group

Choose FlexML from the Select Endpoint Type dropdown menu.

Endpoint Type

Click Create Endpoint.

Create Endpoint

II. Assign Phone Number

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. Participants can dial any phone number associated with an endpoint.

Assign Number

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.

Select Number

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

Edit Numnber

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

Select Group

Click Save.

Save Number

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

III. Build a Voice App

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.

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


In your terminal, start your Flask server.

FLASK_APP=hello.py flask run


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.

ngrok Terminal

IV. Inbound Call Handler

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.

Under the Configure menu, click Phone Numbers.

Click Numbers

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

Target Number

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

Edit App

Enter the ngrok link into the URL textbox.

Add Link

Click Save.

Save URL

V. Placing Outbound Calls

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

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.

Credentials

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 Voice App 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"
}

VI. Next Steps

You have configured a FlexML Endpoint! For more information, refer to the FlexML API Reference Guide.

If you would like to review the steps to configuring the FlexML endpoint, refer to the video tutorial.