Mediator

Configure Mediator Endpoint

No time to read?Watch this short video

In this guide, you will learn how to configure a Mediator endpoint. The Mediator endpoint is used to create intermediaries, called bindings and dialouts, between phone numbers. Bindings route incoming calls to a destination phone number. Dialouts make outgoing calls to two different parties, who are then brought into a call together.

I. Create Endpoint

In this section, we will go over setting up a Mediator endpoint through the portal. We will also associate a phone number with the endpoint.

To set up a Mediator 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 Mediator from the Select Endpoint Type dropdown menu.

Click Create Endpoint.

II. Assign Phone Number

The Mediator endpoint needs to be associated with one or more DIDs rented through CarrierX. These DIDs will be used as the redirect_did values to properly route calls. Navigate back to the Configure menu and click Phone Numbers.

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 newly-created endpoint from the dropdown list.

Click Save.

Now that we have configured a Mediator endpoint and associated a phone number, we can move on to further actions with this endpoint.

III. Create Bindings

A binding creates forwarding logic. Credentials used to create bindings can be found by navigating back to Endpoints under the Configure menu. Select the endpoint you would like to create a binding for and scroll down to see the API Base URL, API Login, and API Password.

Form a POST request. destination_did is the only field required to create a binding. This is the phone number that will receive calls. Refer to the Create Binding section in the Mediator API Reference for more information.

curl -X POST \
'https://api.carrierx.com/mediator/v1/bindings' \
-H 'Content-Type: application/json' \
--data-binary '{"destination_did":"15162065586", "maximum_ttl": -1, "wait_origination_did_ttl": -1}' \
-u '[your_mediator_endpoint_username]:[your_mediator_endpoint_password]'

By default, bindings are time limited, and their longevity depends on the values of wait_origination_did_ttl and maximum_ttl. In this example, we set both values to -1, meaning that the binding will never expire. All phone calls made to the redirect_did will be forwarded to the destination_did. The redirect_did is a DID rented from CarrierX that is assigned to the Mediator endpoint trunk group.

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

{
    "body": {
        "account_sid": "0a1ba365-71e0-45af-b49c-a7b08e6650c7",
        "attributes": {},
        "binding_sid": "b956ad8c-eadb-4e90-969f-f7ef692cc40d",
        "date_created": "2019-02-19T17:36:33.174Z",
        "destination_did": "15162065586",
        "dtmf": null,
        "maximum_ttl": -1,
        "name": "N/A",
        "origination_did": null,
        "redirect_did": "15162065515",
        "redirect_did_info": {
            "country_code": "USA",
            "e164_format": "+15162065515",
            "in_country_format": "(516) 206-5515",
            "international_format": "+1 516-206-5515",
            "phonenumber": "15162065515"
        },
        "wait_origination_did_ttl": -1
    },
    "status": 200
}

Now we will move into updating a binding. There are two ways to do this—either through a PATCH or PUT request. In the following example, we use a PATCH request to change the value of destination_did.

For more information about updating bindings, refer to the Update Binding section in the Mediator API Reference.

curl -X PATCH \
'https://api.carrierx.com/mediator/v1/bindings/b956ad8c-eadb-4e90-969f-f7ef692cc40d' \
-H 'Content-Type: application/json' \
--data-binary '{"destination_did": "19166561000"}' \
-u '[your_mediator_endpoint_username]:[your_mediator_endpoint_password]'

In this request, we updated the destination DID. This is the phone number that will ring if the dialout was created properly and the phone number is reachable.

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

{
    "body": {
        "account_sid": "0a1ba365-71e0-45af-b49c-a7b08e6650c7",
        "attributes": {},
        "binding_sid": "b956ad8c-eadb-4e90-969f-f7ef692cc40d",
        "date_created": "2019-02-19T18:07:40.000Z",
        "destination_did": "19166561000",
        "maximum_ttl": -1,
        "name": "N/A",
        "origination_did": null,
        "redirect_did": "15162065515",
        "redirect_did_info": {
            "country_code": "USA",
            "e164_format": "+15162065515",
            "in_country_format": "(516) 206-5515",
            "international_format": "+1 516-206-5515",
            "phonenumber": "15162065515"
        },
        "wait_origination_did_ttl": -1
    },
    "status": 200
}

IV. Perform Dialouts

The Mediator endpoint also provides the capacity to create a dialout, which makes calls to two phone numbers and brings them into a call together. The stage_one_destination_did and stage_two_destination_did fields are required to create a dialout.

The stage_one_destination_did is the first phone number that is dialed out to by the system. The redirect_did is what appears by default on the receiving party’s caller ID.

If the recipient answers the phone call, the stage_two_destination_did is then dialed out to. If this second recipient also answers, both the stage_one_destination_did and stage_two_destination_did call recipients can then speak with one another.

curl -X POST \
'https://api.carrierx.com/mediator/v1/dialouts' \
-H 'Content-Type: application/json' \
--data-binary '{"stage_one_destination_did":"15162065339", "stage_two_destination_did":"15162065338"}' \
-u '[your_mediator_endpoint_username]:[your_mediator_endpoint_password]'

Note that unless a delay value is set, the system will dial the stage_one_destination_did as soon as a successful POST request has been made. In this example, the dialout will be executed immediately.

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

{
    "body": {
        "account_sid": "0a1ba365-71e0-45af-b49c-a7b08e6650c7",
        "attributes": {
            "hide_origination_did": "true"
        },
        "date_created": "2019-02-19T19:56:36.702Z",
        "delay": 0,
        "dialout_sid": "d9ae9fd7-37ff-4e96-910c-8dd2f4959617",
        "redirect_did": "15162065515",
        "stage_one_destination_did": "15162065339",
        "stage_two_destination_did": "15162065338"
    },
    "status": 200
}

V. Look Up DIDs

The Mediator API can also be used to look up DIDs associated with the endpoint. Form a GET request to do so. Filtering and Pagination parameters can be added to this request to narrow the results. Refer to the Using the REST API section of the Mediator API Reference for more information.

curl -X GET \
'https://api.carrierx.com/mediator/v1/dids' \
-u '[your_mediator_endpoint_username]:[your_mediator_endpoint_password]'

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

{
    "body": {
        "count": 1,
        "has_more": false,
        "items": [
            {
                "account_sid": "0a1ba365-71e0-45af-b49c-a7b08e6650c7",
                "country_code": "USA",
                "did_sid": "9943812f-bac0-45b2-a1bb-01674b7183bf",
                "in_country_format": "(516) 206-5515",
                "international_format": "+1 516-206-5515",
                "phonenumber": "15162065515"
            }
        ],
        "limit": 10,
        "offset": 0,
        "pagination": {},
        "total": 1
    },
    "status": 200
}

VI. Next Steps

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

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