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:

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

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

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

Click Update to save the results.

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

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.

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.

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:

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.

• If the system encounters some issues with the message (you either try to send it to an invalid phone number, or it violates access control rules set for the DID or the account, etc.), it drops the message and does not create the message object. No callback will be sent in this case.

• Otherwise, if everything seems okay, the system accepts the message, and it receives the queued status and goes to Stage #2.

Stage #2: Sending

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

• If the system succeeds, the message gets the sent status and proceeds to Stage #3.

• If the message stucks at the queued status for a certain timeout, it receives the sending_timed_out status and then goes to Stage #3 where it gets the sending_failed status right away. The system sets this timeout on a partner level. If you need to increase it for your partner account, please contact our support at support@carrierx.com.

• If the message encounters any type of internal system errors while being sent to the recipient, it receives the internal_error status and then also goes to Stage #3 where it gets the sending_failed status right away.

Stage #3: Delivery

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

• If the system successfully delivers the message to the recipient device or software, it receives the delivered status.

• If the message passes through the sent status, but could not be delivered to the recipient for some reason (e.g., the destination number is unreachable, etc.) it receives the undelivered status.

• If the system sends the message but then it stucks at the sent status for a certain timeout, it gets the timed_out status. The system sets this timeout on a partner level. If you need to increase it for your partner account, please contact our support at support@carrierx.com.

• The messages which receive either the sending_timed_out or internal_error status at Stage #2 while sending get the sending_failed status at Stage #3.

• The rest of the messages that fail for some other reason receive the final failed status.

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.