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.

Navigate to Callbacks Tab

tip

What you need before you start

• Register with CarrierX to access the API and CarrierX portal.
• Rent a phone number from CarrierX.
• Create a Mediator endpoint and associate it with the rented phone number.

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 item. Go to Global Settings.

Select the Callbacks tab and click the Edit button and then the Add Callback button, which becomes enabled.

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

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.

Enter the URL to your web service that is going to process the callback, e.g., https://example.com/mediator-callback-url and, finally, click the Update button to save the results.

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

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": "2024-11-01T08:57:01.222Z",
    "date_start": "2024-11-01T08:53:59.000Z",
    "date_stop": "2024-11-01T08:54:30.000Z",
    "date_talk": "2024-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.

Attribute	Data Type	Description
attributes	object	The additional call attributes specified when creating the binding or the dialout. Refer to the section below for more information about available attributes and their details.
date_insert	string	The date and time when the record about the call was inserted into the database.
date_start	string	The date and time when the call started.
date_stop	string	The date and time when the call ended.
date_talk	string	The date and time when the destination number answered the call.
direction	string	The direction of the call. This is normally set to inbound for the calls that use the Mediator endpoint as a binding to show that the rented DID receives the call from the source number and redirects it to the destination phone number. For the calls that use the Mediator endpoint as a dialout, this field is set to outbound to show that the rented DID sends voice calls to both the numbers before connecting them with each other.
dr_sid	string	The secure ID of the call detail record which the system uses to identify the record among other call detail records.
dtmf	string	The DTMF sequence that was sent to the called party. This field will only have some value if you use the Mediator endpoint as a binding and specify a DTMF sequence for it. With dialouts this field is always set to null.
duration	integer	The call duration. Normally, it is calculated as (date_stop) − (date_start) and measured in seconds.
endpoint_sid	string	The secure ID of the Mediator endpoint used for the call.
endpoint_type	string	The type of the endpoint that triggered the callback. Here, it is always equal to mediator.
event_type	string	The type of the Mediator endpoint used for the call. Is set to binding for the Mediator endpoint used to redirect the call from the source to the destination phone number, and to dialout for the Mediator endpoint used to call the two phone numbers one by one before connecting them with each other.
number_dst	string	The destination phone number (if the Mediator endpoint is used as a binding) or the second called number (if the Mediator endpoint is used as a dialout).
number_redirect	string	The rented DID which the system uses for the Mediator endpoint.
number_src	string	The source phone number (if the Mediator endpoint is used as a binding) or the first called number (if the Mediator endpoint is used as a dialout).
partner_sid	string	The secure ID of the partner with which the Mediator endpoint is associated.
reference_sid	string	The reference secure ID of the binding (binding_sid) or the dialout (dialout_sid) that was used to make the call.
type	string	The type of the endpoint used for the call. Here, it is always equal to mediator.
version	integer	The version of the API used to send the callback.

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.

  note

  This field is set to true by default for dialouts and to false for bindings. If you need to change these values, please contact our support at support@carrierx.com.

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

  note

  Any headers added would still need to be in the legB SIP_RELAY_HEADERS to be sent to the destination endpoint. Refer to the Trunk object section of the Core API documentation for more details on this.

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

info

Please note that you can provide your own custom attributes. You need to set them as key-value pairs in the same manner as built-in attributes. These attributes must be supported by the software or hardware used by the calling parties.

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.