Mediator Quick Start Guide

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

Overview


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.



Initial Setup


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.

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



6. Click Create Endpoint .



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



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



11. Click Save .



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 .

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



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 Reference Guide 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_username]:[your_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 not 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": "19166561000",
        "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 Dialout section in the Mediator Reference Guide.

curl -X PATCH \
'https://api.carrierx.com/mediator/v1/bindings/b956ad8c-eadb-4e90-969f-f7ef692cc40d' \
-H 'Content-Type: application/json' \
--data-binary '{"destination_did": "15162065587"}' \
-u '[your_username]:[your_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": "15162065587",
        "maximum_ttl": -1,
        "name": "N/A",
        "origination_did": null,
        "redirect_did": "19166561000",
        "wait_origination_did_ttl": -1
    },
    "status": 200
}


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_username]:[your_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": "19166561000",
        "stage_one_destination_did": "15162065339",
        "stage_two_destination_did": "15162065338"
    },
    "status": 200
}


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 for more information.

curl -X GET \
'https://api.carrierx.com/mediator/v1/dids' \
-u '[your_username]:[your_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": null,
                "did_sid": "d4749db0-41fb-4552-a559-ecfa4091b847",
                "in_country_format": null,
                "international_format": null,
                "phonenumber": "19166561000"
            }
        ],
        "limit": 10,
        "offset": 0,
        "pagination": {},
        "total": 1
    },
    "status": 200
}