Sending Outbound SMS

When you send an SMS to a phone number belonging to an end user's device, you send an Outbound SMS. This is referred to as a Mobile Terminated (MT) SMS, though nowadays an SMS is not always sent to a mobile device. In an Outbound SMS, you can set the 'from' field with the sender configured in your account. It can be a Long Code, Short Code, alphanumeric shortcode, or virtual route.

📘

NOTE

In this API, we use the term MT because we will only send an SMS message to customers. If you desire to receive SMS messages (MO), go to the Receive SMS section.

This API helps you to quickly create and configure sending SMS messages to your customers globally in real-time.

Before sending your first SMS message, you must set up the short code or long code from which the message will be sent.

A Short Code is a special telephone number designed for high-throughput, two-way messaging. Short codes are used to send and receive SMS messages to and from mobile phones. That is, an SMS shortcode is a 5 digit number to which an SMS text message can be sent. Shortcodes are often used by businesses to allow customers to opt-in to their SMS campaigns, alert services, or to enter SMS competitions.

A Long Code is a standard phone number used to send and receive voice calls and SMS messages. Phone numbers are typically called “long codes” (10-digit numbers in many countries) when comparing them with SMS short codes (5-6 digit numbers). With a long code, you can only send one message per second. Therefore, long code text marketing does not work if you want to message groups of more than 200 people.

You are able to send a new SMS message through the Notification method.

📘

NOTE

The total number of API Calls (requests) that the user can make to the POST /notification endpoint in a certain time has been limited. That is, in case the user exceeds the limit of requests (messages sent) that can be made in a specific time, he/she will not be able to send another request until the established time is up. Once the time has elapsed, the request counter is reset and the request can be sent to the endpoint again.

In this example, the user can send 2 requests in 300 seconds (5 minutes). When a third request is sent within the 5 minute range, the HTTP Status Code “429” will be generated and the following parameter will be displayed from the Response body: "errors": { "reason": Too Many Requests" }. This code tells you that the user has sent too many requests in a given amount of time. Once the required time has elapsed, the request counter is reset to 2, so the user will be able to send two requests again in 5 minutes.

To find out if the user exceeds the limit of required requests and the time he/she needs to wait to send the next request, we recommend consulting the Response Header (additional information about the body of the resource). The parameters presented in the response header are the following:

ratelimit-limit: 2
ratelimit-policy: 2;w= 300
ratelimit-remaining: 1
ratelimit-reset: 5m0s

• RateLimit-Limit: return the number of requests left for the client in the time window
• RateLimit-Remaining: return the remaining quota in the current window
• RateLimit-Reset: return the time remaining in the current window, specified in seconds
• RateLimit-Policy: return the quota policy. The quota policy expression can be found in paragraph 2.1 of the IETF draft. The format is, for example, for 2 requests in 300 seconds.

📘

NOTE

The destination address ("to") of the message must be specified in E.164 format → (‘+’ and a country code). The plus sign prefix of the format is optional.

E.164 format: An ITU recommendation for the International Public Telecommunications Numbering Plan, used in the world's Public Switched Telephone Network (PSTN). It defines a common format for international phone numbers prefixed with a ( + ) sign followed by a sequence of up to 15 digits, made up of a Country Code (1 to 3 digits) and a Subscriber Number that includes the area code (maximum 12 digits).

When you send an SMS message, the request body contains the following data:

HTTP Request : POST /notification

{
  "channel": "SMS",
  "request": {
    "from": "12345",
    "to": "+580000000005",
    "message": "New offer 2x1"
  },
  "callbacks": [
    "http://www.mycallback.com?id=123"
  ]
}

The parameters presented in the request body example when sending the SMS message are the following:

Once the SMS notification message has been sent, the response body contains the following data:

{
  "meta": {
    "timestamp": 1642531254980,
    "transactionId": "077da1d0-e089-487e-aed0-59534ba2d9f5",
    "explain": "Send Notification"
  }
}

The parameters presented in the response body example when sending the SMS notification message are the following:

The Messaging API publishes the Outbound SMS in the Send SMS API queue; for this reason, the response generates the “meta” segment.