Set up SMS 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 five main events:

In this quick start guide we will see how to set up the system behavior to send callbacks when the rented phone number sends or receives text messages.

I. Navigate to Callbacks Tab

You can set SMS 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.

Select Global Settings

Then select the Callbacks tab.

Select Callbacks

Click Edit.

Click Edit

Click Add Callback.

Click Add Callback

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

Add Callback

II. Create Callbacks for SMS

In this section, we will set up a callback for text messages through the portal.

Select the sms callback event type from the list.

Select SMS

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

Enter URL

Click Update to save the results.

Click Update

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

View Callback

III. Receive and Parse Message Object

Now if you send a text message (either SMS or MMS) from the rented phone number, your service located at the URL you entered will receive the callback like this:

{
    "date_created": "2021-11-01T08:01:12.404Z",
    "date_status_changed": "2021-11-01T08:01:14.116Z",
    "direction": "outbound",
    "from_did": "15162065919",
    "mcc": 310,
    "message": "This is a test message",
    "message_segments": 1,
    "message_sid": "f6ac6e90-4c38-4ba1-a8ce-25a911a422db",
    "mnc": 260,
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "price": 0.01,
    "status": "sent",
    "to_did": "15162065515"
}

When you receive a text message (either SMS or MMS) to the rented phone number, your service located at the URL you entered will also receive the callback similar to the one above. The main difference will be that the direction will be set to inbound, and the only status value available will be received:

{
    "date_created": "2021-11-01T08:01:14.517Z",
    "date_status_changed": "2021-11-01T08:01:14.517Z",
    "direction": "inbound",
    "from_did": "15162065515",
    "mcc": 310,
    "message": "This is a test message",
    "message_segments": 1,
    "message_sid": "87a1ee29-1954-4a22-a243-be21711f28dd",
    "mnc": 260,
    "partner_sid": "cee93bf3-5746-43fe-a1a2-822c05fef687",
    "price": 0,
    "status": "received",
    "to_did": "15162065919"
}

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

Message Object Fields

The object in the callback has the following fields.

Attribute Data Type Description
date_created string The date and time when the system created the message object.
date_status_changed string The date and time when the system changed the message status. Refer to the Message Status and Stages section below for more information about the possible stages which a message can pass.
direction string The message direction. Mostly, two main values are used with the rented DIDs: inbound when the rented phone receives a message, and outbound when the rented phone number sends a message.
from_did string The phone number which was used to send the message. It can be either a rented DID (which is used to send a message in this case) or a common phone (in this case, the rented DID will be used to receive the message).
mcc integer The mobile country code that was used by the operator when sending the message. It is used in the combination with the mnc parameter (mobile network code). Refer to our Glossary section for more information about the mobile country code and its possible values.
message string The message text. It can be empty when sending multimedia messages (MMS) or contain some text which was sent to the receiving party.
message_segments integer The number of segments which the message contains. Normally, multimedia messages consist of a single segment only, while the system splits text messages (SMS) longer than 160 characters into several segments. These segments are later combined into a single long message on the receiving device. The text messages up to 160 characters consist of a single segment and are sent and delivered as is.
message_sid string The secure ID of the message which the system uses to identify the message among other messages.
mnc integer The mobile network code that was used by the operator when sending the message. It is used in the combination with the mcc parameter (mobile country code). Refer to our Glossary section for more information about the mobile network code.
partner_sid string The secure ID of the partner associated with the message, i.e. the partner that either sent of received the message.
price number The message price. It is calculated as (the rate for the message) × (the number of the message segments).
status string The status of the message at the moment when the system sent the callback. Refer to the Message Status and Stages section below for more information about the possible statuses which a message can have.
to_did string The phone number which was used to receive the message. It can be either a rented DID (which is used to receive the message in this case) or a common phone (in this case, the rented DID will be used to send the message).

Message Status and Stages

Receiving Messages

When you use the rented DID to receive text or multimedia messages, the messages normally have only one status, that is received.

Message Stages Received

Sending Messages

But when when you send a message from the rented DID, it goes through several stages and has several statuses before the destination phone number receives it.

The status flow of a message sent from the rented DID looks like this:

Message Stages Sent

As you can see, the messages go through three stages where they receive different statuses depending on the flow:

  1. Acceptance
  2. Sending
  3. Delivery
Stage #1: Acceptance

At Stage #1 the system either accepts the message or drops it.

Stage #2: Sending

At Stage #2 the system tries to send the message to the receiving phone number.

Stage #3: Delivery

At Stage #3 the system reports the result of the message delivery to the recipient.

IV. Next Steps

You successfully created callbacks for SMS associated with your partner account.

Now you can try and send or receive a text or a multimedia message and your web services will receive the callbacks triggered by these events.