Callback URL (MT)

In this section, we help you to provide indications of how the callback URL service should be built to receive the status of the MT messages of your campaign.

If you want to receive the status of the SMS message you've sent to your subscribers, we can have them delivered to you in real-time. Specify your endpoint and we will send the status of the outbound messages to you as soon as they are delivered to us by a mobile network operator. Your endpoint must have a POST access method and receive a JSON body.

You must provide us with the following URL structure:

POST https://Your_Domain/Your_Path

📘

NOTE

Send SMS API will make a POST request to your URL.

The URL is the external callback where the events of the SMS message will be registered and published. That is, the following example parameters sent to your callback URL will be the events to be recorded in the callback once the message has been sent to the recipients:

Parameter Description
date

Date when the API receives the MT message status.

The date is represented with date in UTC Zulu format: (yyyy-mm-dd-Thh:mm:ss.ssZ).

externalId Alphanumeric identifier used to identify your MT messages uniquely for reporting purposes.
callback Webhook URL to notify about the events of the MT message.
from Shortcode (from 1 to 6 digits), Longcode (from 7 digits on), an alphanumeric shortcode (ex. COMPANY) or a virtual number used to originate and send the SMS message. Any of these codes will appear in the handset as the source of the text message. Virtual numbers will translate to a local shortcode depending on the destination carrier.
id Unique identifier of the SMS message.
to Destination address of the message.
message Content of the SMS message that was sent to the end user.
username Owner or creator of the SMS message.
timestamp Call’s time mark.
status When the SMS message is sent, the mobile operator assigns one of the following possible status to an SMS message:

  • DELIVRD: SMS message was successfully delivered.

  • EXPIRED: Mobile operator was unable to deliver the message in the specified amount of time. A sample case is that the mobile device was turned off.

  • DELETED: SMS message has been deleted.

  • UNDELIV: Unable to send the SMS message.

  • ACCEPTD: SMS message is in the accepted status.

  • UNKNOWN: SMS message is in invalid status. Unknown error occurred with the mobile operator. This is very unlikely.

  • REJECTD: SMS message was rejected.

    The mobile operator could have blocked the message.

  • INVALID_ROUTING: Phone number is not valid.

  • CODE_NOT_ALLOWED: User does not have the short or long code assigned where the message is sent.

  • BLACKLISTED: Recipient is blacklisted.

  • QUEUE: SMS message is queued. Acknowledged by internal delivery process but not yet sent.

  • DEQUEUED: The SMS message has been removed from the queue and is ready to be published on the mobile operator.

  • SENT: SMS message was sent.

  • ERROR: An error occurred in the API logic and the message could not be delivered.

  • ENROUTE: The SMS message is enroute.

  • SEGMENTS_EXCEEDED: This status indicates that the number of permissible segments has been surpassed. This occurs when the message exceeds the 160-character limit per segment, therefore the the message cannot be sent.

    To resolve this issue, ensure that your SMS messages do not exceed 1600 characters to avoid reaching the segment limit.

This parameters will be sent to your URL in JSON format:

{
  "date": "2020-10-22T20:29:57.453673Z",
  "externalId": "8",
  "owner": "[email protected]",
  "callback": "http://www.mycallback.com",
  "from": "4141",
  "id": "djd77dheh45kk77",
  "to": "+580000000005",
  "message": "Welcome to Messangi",
  "username": "Company",
  "timestamp": 1660246072543,
  "status": "DELIVRD"
}