SMS over API

Learn how to receive SMS API and to send SMS message API requests.

Basic API for sending SMS

If you want to automatize your SMS traffic, and you don’t want to use our SaaS solutions like Flow, you can always use our API. If you don't need a robust solution, use our most basic API request which only requires three parameters to send a message.

Request

POST /sms/2/text/advanced

 
    {
      "messages": [
        {
          "from": "InfoSMS",
          "destinations": [
            {
              "to": "41793026727"
            }
          ],
          "text": "This is a sample message"
        }
      ]
    }
 

For more details, visit our SMS API documentation (opens in a new tab).

Fully Featured API for sending SMS

If you need advanced functionalities like validity period, transliteration, etc., use our fully featured API (opens in a new tab). You can also use the version of our API where parameters can be set directly in the URL.

To receive an SMS message, or to transfer received SMS messages from our platform to yours, you can:

1. PULL messages you received to your number. These messages are stored on our platform and you can pull them when it suits you best. Refer to the Get received messages (opens in a new tab) for more details.
2. PUSH received messages automatically to your dedicated URL.

Both of these of methods require you to set up a number and a type of forwarding actions for it, so that our platform knows what to do.

If you haven't set up forwarding to a specific number, check your inbound logs for any received messages. This is very similar to our PULL action, however, logs only store your data for up to 48 hours.

SMS Preview

To avoid unpleasant surprises, use this method (opens in a new tab) to preview messages before sending them out to your customers. Discover the message length, a number of message parts, language, and transliteration output, etc.

The preview method can provide you with the following information:

• originalText- original message content that was supplied for preview
• textPreview- preview of the message content as it should appear on the recipient's device
• messageCount- number of messages required to deliver textPreview
• charactersRemaining- number of remaining characters before messageCount increase
• configuration- configuration setup that should be included in advanced SMS in order to deliver textPreview message
• languageCode- language code for the correct character set
• transliteration- the transliteration of your sent message from one script to another; used to replace characters which are not recognized as part of your defaulted alphabet.

Message Count and Remaining Characters

Use this method to see how many characters are left ‘unspent’ in the message and if the message fits in one or more messages.

Request

POST /sms/1/preview

 
    {
        "text": "Let's see how many characters will remain unused in this message."
    }
 

Response

 
    {
      "originalText": "Let's see how many characters will remain unused in this message.",
      "previews": [
        {
          "textPreview": "Let's see how many characters will remain unused in this message.",
          "messageCount": 1,
          "charactersRemaining": 95,
          "configuration": {}
        }
      ]
    }
 

The response contains the original text (sent text) and one preview which showcases a message received by the recipient without any configuration. In this case, the text will fit in one message and there will be 95 characters left. No special configuration is needed if your goal is to deliver the message as seen in textPreview.

Notify URL

Use the Notify URL feature to forward Delivery Reports, message status, pricing information or GSM errors (e.g. EC_ABSENT_SUBSCRIBER) to your callback server using a predefined URL. If set up, Notify URL forwards the data as soon as the Infobip platform receives it. Use the "notifyUrl" field to specify the URL.

In addition to the URL, you can also specify the following fields to make the feature more robust:

• notifyContentType- determines which body type to push to the server, JSON or XML.
• messageId- customize your message ID, so that your response contains the same ID and is easier to find; otherwise, Infobip will automatically generate it for you in a response.
• bulkId- customize your bulk ID if sending multiple messages or to multiple recipients, so that your response contains the same ID and is easier to find; otherwise, Infobip will automatically generate it for you in a response.
• callbackData- additional user-defined data that will be sent on to the Notify URL.

Request

POST /sms/2/text/advanced

 
    {
      "bulkId": "june-campaign",
      "messages": [
        {
          "from": "SomeStore",
          "destinations": [
            {
              "to": "41793026727",
              "messageId": "silver-loyalty-program"
            },
            {
              "to": "41793026731",
              "messageId": "golden-loyalty-program"
            }
          ],
          "text": "Check out our newest collection available NOW in your local store.",
          "notifyUrl": "http://www.example.com/sms/campaigns",
          "notifyContentType": "application/json",
          "callbackData": "For example, this field can store tracking ID for analytics"
        }
      ]
    }
 

Push Retry Cycle

If your Notify URL is unavailable for any reason, forward attempts will be made according to formula:
1min + (1min * retryNumber * retryNumber)
Examples for first few retry attempts are shown in the table below. Maximum number of retries is 20, i.e. the last retry will be done 41:30h after the initial one. If your URL is not available for the whole retry period, the data will be lost.

SMS to Multiple Destinations

Imagine you have opened a wine shop and you want to invite your future customers for the grand opening. Do it over SMS—one of the most powerful promotional channels!

You can send the same message to multiple phone numbers. The example below only contains two phone numbers for easier understanding.

Request

POST sms/2/text/advanced

 
    {
      "messages": [
        {
          "from": "WineShop",
          "destinations": [
            {
              "to": "41793026727"
            },
            {
              "to": "41793026727"
            }
          ],
          "text": "Wine shop grand opening at Monday 8pm. Don't forget your wine glass!"
        }
      ]
    }
 

Here's the three parameters you should take a closer look into:

• from- represents the sender of the SMS message - it can be alphanumeric or numeric. Alphanumeric sender ID length should be between 3 and 11 characters (Example: CompanyName). Numeric sender ID length should be between 3 and 16 characters.
• to - an array of message destination addresses. Destination addresses must be in international format (e.g. 41793026727).
• text- content of the message being sent.

This will send an SMS to two addresses with the same content and sender. The response will also contain a "bulkId" field to group your multiple recipients under one response so that you can easily fetch logs or reports. You can pass your custom Bulk ID in the request, otherwise if omitted, the Infobip platform will automatically generate one and assign it to your response.

Response

 
    {
        "bulkId": "2034070510160109025",
        "messages": [
            {
                "to": "41793026727",
                "status": {
                    "groupId": 1,
                    "groupName": "PENDING",
                    "id": 26,
                    "name": "PENDING_ACCEPTED",
                    "description": "Message sent to next instance"
                },
                "messageId": "2034070510160109026"
            },
            {
                "to": "41793026834",
                "status": {
                    "groupId": 1,
                    "groupName": "PENDING",
                    "id": 26,
                    "name": "PENDING_ACCEPTED",
                    "description": "Message sent to next instance"
                },
                "messageId": "2034070510250109027"
            }
        ]
    }
 

Your response will include the following:

• bulkId- used for getting delivery reports (opens in a new tab) for SMS messages sent to multiple destinations.
• to- the recipient of the message
• status- indicates the message status (opens in a new tab)
• smsCount -represents the number of SMS messages sent to one destination
• messageId -uniquely identifies the message sent

Multiple SMS to Multiple Destinations

Imagine you want to target your customers by offering them their favorite product during your next promotion. Every customer is specific, and you shouldn’t send the same message to all of them. Tailor your SMS messages according to customers’ preferences and get their full attention.

You can use our multiple textual messages for that purpose. This option gives you the ability to send multiple messages to multiple destinations by calling one API method only once.

Request

POST /sms/2/text/advanced

 
    {
      "messages": [
        {
          "from": "WineShop",
          "destinations": [
            {
              "to": "41793026727"
            }
          ],
          "text": "Hey Mike, delicious Istrian Malvazija is finally here. Feel free to visit us and try it for free!"
        },
        {
          "from": "WineShop",
          "destinations": [
            {
              "to": "41793026834"
            }
          ],
          "text": "Hi Jenny, we have new French Merlot on our shelves. Drop by our store for a free degustation!"
        }
      ]
    }
 

After you have sent these messages, you will be able to get detailed stats and analyze them. For example, you can measure how many customers received the SMS invitation by getting the delivery reports (opens in a new tab).

Refer to Response Status and Error Codes for further information on your message status.

Send SMS message over query parameters

Send SMS by including all of the required URL parameters in one query string. This is a perfect solution if you have an application with limited integration possibilities and you are not able to fully integrate with our REST API method for sending an SMS.

Request

    curl -L -g -X GET 'https://{baseUrl}/sms/1/text/query?username={username}&password={password}&from=InfoSMS&to=41793026727,41793026834&text=Message%20text&flash=true&transliteration=TURKISH&languageCode=TR&intermediateReport=true&notifyUrl=https://www.example.com&notifyContentType=application/json&callbackData=callbackData&validityPeriod=720&track=URL&trackingType=Custom%20tracking%20type' \
    -H 'Authorization: {authorization}' \
    -H 'Accept: application/json'

This is all you need to send a message. You can even send this message through your web browser address bar, the same way you would type an address to open a web page. This is something that you could put into your application without writing any code.

Response

The response will is identical to a fully-featured SMS response.

 
    {
      "bulkId": "1478260834465349757",
      "messages": [
        {
          "to": "41793026727",
          "status": {
            "groupId": 1,
            "groupName": "PENDING",
            "id": 7,
            "name": "PENDING_ENROUTE",
            "description": "Message sent to next instance"
          },
          "smsCount": 1,
          "messageId": "844acc75-e5c6-4a21-a7e3-444c412c385b"
        }
      ]
    }
 

There is one more catch. You will probably need to replace hard-coded values like phone number and message text with placeholders unless you want to send the same message to the same recipient every time. Placeholder names will be provided by the application system you are using. All you need to understand is where to put them.

Let’s break down our example request in several lines so we can examine it closely:

https://api.infobip.com/sms/1/text/query?
username=myUsername
&password=myPassword
&to=41793026727
&text=Message text

The first line is the API endpoint and this never changes. The question mark at the end represents the beginning of the query string parameters. It’s a system of key /value pairs separated by symbol &. It’s quite clear now what the values are and which values you will need to replace by a value placeholder.

&to=%phoneNumber%
&text=%message%

VALUE PLACEHOLDERS
Placeholder names and format will vary depending on your application. Refer to your application documentation for instructions.

Here is the final result:
https://api.infobip.com/sms/1/text/query?username=myUsername&password=myPassword&to=%phoneNumber%&text=%message

Your application should now dynamically send different messages to different recipients and dynamically replace placeholders with the recipient’s phone number and message.

Track Conversion

SMS conversion tracking allows you to notify the Infobip platform about a successful conversion of specific user actions such as URL clicks, code input, etc. Once the action has taken place, information is sent to the Infobip platform for performance analysis.

Why it is useful to me

Conversion tracking will help Infobip see a better picture of how your traffic is performing and proactively take measures to correct any degradation in quality.

What to use it for

You can only submit conversion information for SMS messages. Its main goal is to keep track of time-sensitive messages, like 2FA passwords, or messages that expect a quick reaction from your end user, like clicking a certain link.

Workflow with code samples

1. Enable tracking by setting up a tracking object within your message body. For more details on how to send an SMS, check out our API Reference (opens in a new tab).

 
    {
        "messages": [
            {
                "from": "InfoSMS",
                "destinations": [
                    {
                        "to": "14155552671"
                    }
                    ],
                "text": "Your code: 6242"
            }
            ],
        "tracking": {
                "track": "SMS"
        }
    }
 

1. The Infobip platform marks the start of the tracking process as soon as the message is sent out.
2. Once the message is delivered and an end user performs an action (clicks a link, inputs a code, etc.), this counts as a successful conversion rate. You can track such actions through webhooks implemented on your side.
3. Notify Infobip about the successful conversion by calling POST /ct/1/log/end/{messageId}.

Once the Infobip platform is notified about the successful conversion, it can monitor the performance and use this data to provide you with a better service.