Receive SMS with the Pull method

This method allows you to pull received messages over an API call.

This tutorial will show you how to access messages sent by your customers. Before you proceed to implement this method, please read the introduction on how to receive inbound messages where you can learn about numbers and the initial setup.

Tutorial

This tutorial covers accessing messages via the Pull method. Besides the Pull method, received messages can be forwarded to your application URL in real-time. Learn more about the Forward method.

Accessing your received messages in our system is pretty much straightforward. All you need to do is make a simple API call which will return the received messages.

Important!

All received messages can be pulled only once! Once a certain message has been pulled by this method, it will not be available for the next API call. This means that every time you make an API call, you will receive only new messages, the ones that arrived since the last API call.

Request example:

GET /sms/1/inbox/reports HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json
GET /sms/1/inbox/reports HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/xml
curl -X GET \
-H 'Accept: application/json' \
-H "Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" \
https://api.infobip.com/sms/1/inbox/reports
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "http://api.infobip.com/sms/1/inbox/reports",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
require 'uri'
require 'net/http'

url = URI("https://api.infobip.com/sms/1/inbox/reports")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
request["accept"] = 'application/json'

response = http.request(request)
puts response.read_body
import http.client

conn = http.client.HTTPSConnection("api.infobip.com")

headers = {
    'authorization': "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
    'accept': "application/json"
    }

conn.request("GET", "/sms/1/inbox/reports", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.infobip.com/sms/1/inbox/reports")
  .header("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
  .header("accept", "application/json")
  .asString();
var client = new RestClient("https://api.infobip.com/sms/1/inbox/reports");

var request = new RestRequest(Method.GET);
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==");

IRestResponse response = client.Execute(request);
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.infobip.com/sms/1/inbox/reports");
xhr.setRequestHeader("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==");
xhr.setRequestHeader("accept", "application/json");

xhr.send(data);

Response:

{
  "results": [
    {
      "messageId": "817790313235066447",
      "from": "385916242493",
      "to": "385921004026",
      "text": "QUIZ Correct answer is Paris",
      "cleanText": "Correct answer is Paris",
      "keyword": "QUIZ",
      "receivedAt": "2016-10-06T09:28:39.220+0000",
      "smsCount": 1,
      "price": {
        "pricePerMessage": 0,
        "currency": "EUR"
      },
      "callbackData": "callbackData"
    }
  ],
  "messageCount": 1,
  "pendingMessageCount": 0
}	
  

Response body parameters

If successful, the response header HTTP status code will be 200 OK and messages will be returned in the response body.

If you try to get received messages without authorization, you will get a response with HTTP status code 401 Unauthorized.

SMSResponse

Parameter Type Description
results Messages Collection of reports, one per every received message.
messageCount Int Number of returned messages in this request.
pendingMessageCount Int Number of remaining new messages on our server ready to be returned in the next API call.

Messages

Parameter Type Description
messageId String The ID that uniquely identifies the received message.
from String Sender ID that can be alphanumeric or numeric.
to String The message destination address.
text String Full text of the received message.
cleanText String Text of received message without a keyword (if a keyword was sent).
keyword String Keyword extracted from the message text.
receivedAt Date Tells when Infobip platform received the message. It has the following format: yyyy-MM-dd'T'HH:mm:ss.SSSXXX.
smsCount Int The number of sent message segments.
pricePerMessage Decimal Cost of receiving a message.
currency String Currency of the message price.
callbackData int Custom callback data can be inserted during setup phase.

Keywords

Learn more about keywords and how to use them in the introduction.

Get limited number of messages

You can limit the number of messages in one request by introducing the limit parameter like this:

/sms/1/inbox/reports?limit=2

Request example:

GET /sms/1/inbox/reports?limit=2 HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/json
GET /sms/1/inbox/reports?limit=2 HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Accept: application/xml
curl -X GET 
-H 'Accept: application/json' 
-H "Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==" 
https://api.infobip.com/sms/1/inbox/reports?limit=2
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "http://api.infobip.com/sms/1/inbox/reports?limit=2",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => "",
  CURLOPT_HTTPHEADER => array(
    "accept: application/json",
    "authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=="
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
require 'uri'
require 'net/http'

url = URI("https://api.infobip.com/sms/1/inbox/reports?limit=2")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
request["accept"] = 'application/json'

response = http.request(request)
puts response.read_body
import http.client

conn = http.client.HTTPSConnection("api.infobip.com")

headers = {
    'authorization': "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
    'accept': "application/json"
    }

conn.request("GET", "/sms/1/inbox/reports?limit=2", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.infobip.com/sms/1/inbox/reports?limit=2")
  .header("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
  .header("accept", "application/json")
  .asString();
var client = new RestClient("https://api.infobip.com/sms/1/inbox/reports?limit=2");

var request = new RestRequest(Method.GET);
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==");

IRestResponse response = client.Execute(request);
var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.infobip.com/sms/1/inbox/reports?limit=2");
xhr.setRequestHeader("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==");
xhr.setRequestHeader("accept", "application/json");

xhr.send(data);

The response will return a collection with only the selected number of messages. The rest of the messages will be included in the next call you make.