Set up Mediator Callbacks Using CarrierX Portal

Most of the events associated with your partner account and your rented phone numbers (DIDs) can send callbacks. You can specify URL addresses where you have some service installed which can process these callbacks.

The callbacks contain the detailed data about the event. The data depends on the event that triggers the callback.

You can set callback URLs for four main events:

• When sending or receiving a text message (SMS or MMS),
• When making a call that engages a Mediator endpoint,
• Two events for receiving a call to a Conference endpoint: one for a conference Call object and another for a conference Meeting object,
• And when you are ordering a phone number from an external provider and you wish to be informed when such a phone number has been ordered successfully.

In this quick start guide we will see how to set up the system behavior to send callbacks when the rented phone number associated with the Mediator endpoint sends or receives calls.

I. Navigate to Callbacks Tab

You can set the Mediator callbacks in the Callbacks tab of the Global Settings section of CarrierX portal.

To get there, log in to the portal. On the left-side menu, locate and click the Configure menu. Click Global Settings.

Then select the Callbacks tab.

Click Edit.

Click Add Callback.

Now you can select the event type that will trigger the callback and enter the URLs for your selected callbacks.

II. Create Callbacks for Mediator

In this section, we will set up a callback for the Mediator endpoint through the portal.

Select the app_mediator callback event type from the list.

Then enter the URL to your web service that is going to process the callback, e.g., https://example.com/mediator-callback-url.

Click Update to save the results.

The callback will be available in the list of the created callbacks.

III. Receive and Parse App Mediator Object

As you know, you can use the Mediator endpoint as a binding or a dialout.

• If you use it as a binding, the calling party will dial your rented DID number and it will redirect to the destination number connecting them with each other.
• If you use it as a dialout, the rented DID will dial both the first and the second number and connect them with each other when both answer.

Now if you use the Mediator endpoint, your service located at the URL you entered will receive the callback like this:

{
    "attributes": {
        "hide_origination_did": "true"
    },
    "date_insert": "2021-11-01T08:57:01.222Z",
    "date_start": "2021-11-01T08:53:59.000Z",
    "date_stop": "2021-11-01T08:54:30.000Z",
    "date_talk": "2021-11-01T08:54:11.000Z",
    "direction": "outbound",
    "dr_sid": "c8b57f49-a4a6-471d-8d88-3e2d331a963f",
    "dtmf": null,
    "duration": 31,
    "endpoint_sid": "222ba470-c546-4e53-9059-75c5e9df671f",
    "endpoint_type": "mediator",
    "event_type": "dialout",
    "number_dst": "15186859809",
    "number_redirect": "12092551158",
    "number_src": "15187147330",
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "reference_sid": "de016d1f-9030-4108-a674-d5827949c0b4",
    "type": "mediator",
    "version": 2
}

You can now parse it and use for your own purposes.

App Mediator Object Fields

The object in the callback has the following fields.

Additional Object Attributes

When you create a binding or a dialout, you can provide the following additional preset attributes for the Mediator endpoint:

{
    "attributes": {
        "announce": "https://example.com/url/to/audio-announce.mp3",
        "cnam": "John Smith",
        "fix_anonymous_cid": true,
        "hide_origination_did": true,
        "ringback": "moh",
        "sip_header_*": "X-Custom-Header",
        "use_call_confirmation": "https://example.com/url/to/call-confirmation"
    }
}

• announce is the audio file that plays to the caller (source phone number in bindings or stage one phone number in dialouts) before they are connected to the second party. File types accepted are .wav and .mp3.

• cnam is the CNAM for sending the voice calls. This will be displayed to the destination phone number in bindings and stage two phone number in dialouts. Note that this may not be preserved for calls terminated through the PSTN and the destination software or hardware must support this to display.

• fix_anonymous_cid determines whether or not a blocked, hidden, or unavailable caller ID will be replaced with the redirect_did. The true value means that the system will display the redirect_did phone number instead of the phone numbers with such caller IDs.

• hide_origination_did determines whether or not to hide the phone number of the calling party (source phone number in bindings or stage one phone number in dialouts). Instead, the redirect_did phone number will appear on the caller ID.
  

• ringback customizes what the calling party (or stage one phone number in dialouts) will hear while the second party is being dialed. The following values are available for this field:
  • The false value disables ringing, so the calling party will hear silence until the second party answers the call.
  • The moh value enables music-on-hold for the calling party.
  • With the passthrough value, the second party software or hardware normal response to the call defines what the calling party hears during the wait.

• sip_header_* specifies the values which are sent as extra SIP headers, added to the SIP invite. Currently, CarrierX only supports X- headers, so the header name must start with X-.
  

• use_call_confirmation is used for dialouts only and specifies an audio file which plays when stage one phone number answers (before dialing stage two phone number).

IV. Next Steps

You successfully created callbacks for Mediator endpoint events associated with your partner account.

Now you can try and use your Mediator endpoint, and your web services will receive the callbacks triggered by the endpoint events.