Send an SMS message

This section covers all you need to start SMS communication with your customers over Infobip solutions.

Use Moments to build a customer journey, dependent on customer interaction, Answers to set up chatbots to answer customer queries, Conversations to open up live chats with support agents, and Broadcast to send out a one-time message or notification. You can also use the SMS API (opens in a new tab) to build customer communication and automate your messages.

For more information about getting started with using SMS as a communication channel and the enablement process, see Get started with SMS.

SMS over Broadcast

Use Broadcast to build a one-time communication, sent to your customers.

• Log in (opens in a new tab) to the web interface and go to Moments > CREATE BROADCAST.
• Set your channel to SMS, then populate the To and From fields.
• Add your message in Content and use the data from People to personalize as required.
• Edit the advanced and scheduling options as required.
• Once ready, click Continue to Preview, then Launch to go live.

SMS over Moments

Use Flow in Moments to build the journey of how you communicate with your customers. In this section, you will learn how to send and receive an SMS. This will require two flows.

Set up your first flow with the following steps:

1. Log in (opens in a new tab) to the web interface and go to Moments > CREATE FLOW > Start from Scratch.
2. Define your entry point as Predefined Audience, and populate to whom the message is being delivered in To.
3. Add SMS as the new element.
4. Define sender in From and add your message in Content. Consider keeping SMS messages under 160 characters to avoid sending multiple messages.
5. Use the Advanced and Delivery options as required.
6. Click Validate to save, then Launch when you are ready to go live with your flow.

Remember you can add a failover option to ensure your messages are being delivered.

Set up another flow for inbound messages using the following steps:

1. Define entry point as Trigger > Inbound Message.
2. Select SMS as your channel and add the Evaluate Inbound Message element.
3. Select SMS and define the receiver number in To.
4. Unless specified, the system will wait for the inbound message indefinitely or until stopped manually.
5. Once launched, statistics of messages that are sent can be tracked on a global level or for each specific action in the flow.

SMS over Conversations

Use Conversations to host live one-to-one communication with customers. Provide customers with the support they need over their preferred chat apps.

1. Follow the dedicated Product Setup guide in the Conversations module.
2. Select SMS as your channel when configuring Conversations.

SMS over Answers

Use Answers to build real-time automated communication using AI or keyword-based chatbots for all kinds of customer inquiries.

1. Follow the dedicated Create a chatbot guide in the Answers module.
2. Select SMS as your channel and add in message elements to your chatbots as required.

SMS over API

Use the SMS API (opens in a new tab) to receive SMS over API and to send API requests. If you want to automate your SMS traffic, you should use the SMS API.

Send SMS using basic request

To send an SMS message over API, use our most basic API request, which requires only three parameters to send a message.

POST /sms/2/text/advanced

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

Send SMS using fully featured API

If you need advanced functionalities like validity period, transliteration, and so on, use our fully featured SMS 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 the Infobip platform to yours, you can:

• PULL messages you received to your number. These messages are stored on the Infobip platform and you can pull them when it suits you best. See the Get received messages (opens in a new tab) for more details.
• 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

Use the SMS preview method (opens in a new tab) to preview you SMS messages before sending them to your customers. You'll be able to assess the message length, a number of message parts, language, and transliteration output, and so on.

The preview method provides 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.

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

SMS preview request

POST /sms/1/preview

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

SMS preview 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 (for example, 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.

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 are made according to the following formula:

1min + (1min * retryNumber * retryNumber)

Examples for first few retry attempts are shown in the following table. The maximum number of retries is 20, that is, the last retry will occur 41:30h after the initial one. If your URL is not available for the whole retry period, the data will be lost.

Send SMS to multiple destinations

There may be situations where it is beneficial that you send your SMS to multiple destinations. For example, you can send the same message to multiple phone numbers.

This example contains only two phone numbers for easier understanding.

SMS multiple destinations 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!"
        }
      ]
    }
 

The following three parameters are important for sending SMS to multiple destinatons:

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

SMS multiple destinations 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"
            }
        ]
    }
 

The response includes 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

Send multiple SMS to multiple destinations

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

This option gives you the ability to send multiple messages to multiple destinations by calling one API method once only.

Multiple SMS to multiple destinations 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 are able to get detailed statistics 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).

See the 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 suitable for if you have an application with limited integration possibilities and you are not able to fully integrate with the REST API method for sending an SMS (opens in a new tab).

SMS with query parameters 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.

SMS with query parameters response

The response 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"
        }
      ]
    }
 

You 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 are provided by the application system you are using. All you need to understand is where to put them.

Using the example, this breaks down the request in several lines to examine it more 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. This is a system of key /value pairs separated by symbol &. This enables you to see what the values are and which values you need to replace by a value placeholder. For example:

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

Placeholder names and format will vary depending on your application. See your application documentation for instructions.

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

Send SMS with conversion tracking

Conversion tracking involves monitoring and analyzing marketing campaign performance to understand how well your message resonates with its target audience.

SMS conversion tracking allows you to notify the Infobip platform about a successful conversion of specific user actions. Typical user actions include, clicks on URL clicks, code input, form submissions, purchases, or other desired outcomes after receiving an SMS.

Once an action has taken place, information is sent to the Infobip platform for performance analysis.

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

Providing detailed insights into customer behavior and campaign performance enables businesses to refine their marketing strategies, improve customer engagement, and ultimately drive more sales and revenue. Implementing SMS conversion tracking can significantly enhance the effectiveness of business marketing campaigns.

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

Enable tracking by setting up a conversionTracking object within your message body.

For more details on how to send an SMS with conversion tracking enabled, see the API Reference (opens in a new tab).

A messageId is returned in the POST Send SMS Message response, which you need to provide to Infobip, as follows:

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, and so on), 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.