Configure FlexML Endpoint

No time to read?Watch this short video

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 the Configure menu. Click Endpoints.

Click Add New Endpoint.

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

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.

Choose FlexML from the Select Endpoint Type dropdown menu.

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

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.

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

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

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.

III. Build 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. Import 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.

IV. Inbound Call Handler

In this section, we will learn how to assign a handler URL. Handler URLs can be assigned to a DID or a FlexML endpoint.

Assign URL to DID

First, we will learn how to 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 the phone number associated with the FlexML endpoint trunk group.

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

Enter the ngrok link into the URL textbox.

Click Save.

Assign URL to Endpoint

Now, we will learn how to assign a handler URL to the FlexML endpoint.

Click Configure, then Endpoints.

Select the FlexML endpoint that you would like to associate your link with.

Scroll down and click the Application: FlexML tab. Click Edit in the Configure Settings section.

Enter your link in the Default URL box and click Save.

Now you can test your application by calling the phone number associated with your endpoint.

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.

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 API Reference 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 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://d4d66ed41d49.ngrok.io/hello"}' \
-u '[your_flexml_endpoint_username]:[your_flexml_endpoint_password]'

A successful response will return a 200 status code and a JSON object that looks like the following.

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

VI. Next Steps

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

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