Send and Receive SMS Over API

Basic API

If you want to automatize your SMS traffic, and you don’t want to use Flow, you can always use our API. There are several APIs you can use to send and receive SMS messages: There is a basic API request that requires only three parameters (From, To, and Text) to send a message:

{  
   "from":"InfoSMS",
   "to":"41793026727",
   "text":"Test SMS."
}

To find out more about the basic API visit, refer to the SMS API documentation on our Infobip API Developer hub.

Fully Featured API

If you need advanced functionalities like validity period, transliteration, etc., you can use our fully featured API. 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 for more details.
  2. PUSH received messages automatically to your dedicated URL.

Both of these of these methods require you to setup a number and 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

This method allows you to preview SMS messages before sending them. Discover the message length, a number of message parts, language, and transliteration output.

Sending an SMS message seems simple enough until you get unexpected results which can be caused by various reasons. Even a single unsupported character can significantly reduce the total number of available characters per message which can cause a message to be split into two or even more messages, significantly increasing the cost of sending messages. Things get even trickier when messages must be sent in different languages and language and transliteration options are introduced.

NOTE

To avoid unpleasant surprises, use this method to preview messages before sending them.

The preview method can provide you with the following information:

  • originalText - original text that was supplied for preview

  • textPreview - preview of the text 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

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:

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

Use ‘simple’ or ‘advanced’ ‘send SMS’ methods to send this message.

SMS to Multiple Destinations

You have opened a wine shop and performed all the necessary preparations for the grand opening. One of the most important things you’ll need to do is to invite your future customers. Do it over SMS—one of the most powerful promotional channels. 

To send the same message to multiple phone numbers, you need to perform an HTTP POST request to https://api.infobip.com/sms/2/text/single.
The example request will contain only two phone numbers for easier understanding:

{  
   "from":"WineShop",
   "to":[  
      "41793026727",
      "41793026834"
   ],
   "text":"Wine shop grand opening at Monday 8pm. Don't forget glasses."
}

The header section of the request should contain authorization and content type:

  • Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

  • Content-Type: application/json

Looking at the request body, there are three parameters:

  • ‘from’ parameter 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’ parameter is an array of message destination addresses. Destination addresses must be in international format (Example: 41793026727).

  • ‘Text' text of the message that will be sent.

This will send an SMS to two addresses with the same content and sender.
 

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

In the response, you’ll receive a bulkId and an array of messages:

  • bulkId is used for getting delivery reports for SMS messages sent to multiple destinations.

  • Array of messages consists of Send SMS response details:

    • ‘To' parameter as a message recipient

    • status object for message status

    • smsCount represents the number of SMS messages sent to one destination

    • messageId uniquely identifies the message sent

After you have sent out invitation messages, it’s time to promote a different product to different customers. With a single API method multiple messages can be sent to a multiple destinations.

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:

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

This way you’ll send specific SMS messages to multiple destinations in a single request. The response you get will contain information about all the messages sent out:

{
	"messages": [
		{
			"from": "Aeromark",
			"destinations": [
				{
					"to": "41793026834"
				}
			],
			"text": "Hello there 1"
		},
		{
			"from": "Aeromark",
			"destinations": [
				{
					"to": "41793026727"
				}
			],
			"text": "Hello there 2"
		}
	]
}

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:

Refer to Response Status and Error Codes for further information.

SMS over URL Parameters

Send SMS by including all of the required parameters in the URL using HTTP GET request.

Owning custom made applications tailored for specific requirements of a single organization is an expensive privilege few can afford. Using third-party software solutions for your business needs is a more common case for businesses today. These “generic” applications are usually highly configurable in order to cover the widest range of use cases. No matter how clever the application is designed, it seems like there is always at least one crucial feature missing.

If you happen to have one of those applications, you probably have options to configure different workflows and triggers. Often the application also offers integration options too. Due to its generic nature, the application has to cover a variety of integration scenarios and also keep a certain level of simplicity to remain intuitive and usable. This trade-off between options and usability can result in a solution with limited integration possibilities.

Integrating our REST API method for sending SMS in such an application may be impossible since you have to configure the request type, headers and body model. This is something that is usually handled by developers and this type of application will not allow you to write custom code. At best it will provide you with a single input to enter the URL of the service you want to trigger, and that’s it.

Simple SMS with Basic Parameters

With this single input problem in mind, we have designed a method which allows you to send SMS in a single line of the HTTP request:

GET /sms/1/text/query?username=myUsername&password=myPassword&to=41793026727&text=Message text HTTP/1.1
Host: api.infobip.com
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. Now, this is something that you could put into your application without writing any code.

The response will be 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"
    }
  ]
}
XML RESPONSE FORMAT

The default response format is JSON. However, if you would like to receive XML instead, you may specify the format .xmlextension at the end of the method URL, such as: https://api.infobip.com/sms/1/text/query.xml

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. What you need to understand is where to put the placeholders.

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.