Search Icon

API - Documentation and examples

Infobip APIs allow developers to gain easy access to a range of Infobip mobile services.

HTTP XML xml formatted data

Documentation

Download API documentation and one page reference sheet.

 Download

Sending Messages

Send messages using HTTP XML POST – with this method it is possible to send SMS messages to a number of recipients using XML-formatted data sent to a corresponding URL.

URL for Sending Messages

http://api.infobip.com/api/v3/sendsms/xml

File Format customize with parameters

Parameters

<username>
Client username for Infobip system Login.
<password>
Client password for Infobip system Login.
<sender>
Dynamic message sender ID.
Possible values:
Alphanumeric max. Length 11 characters
Numeric max. length 14 characters
<text>
Message body at the moment 160 characters.
<flash>
Message style when delievered to mobile phone.
Possible values:
0 sends a normal SMS
1 sends Flash SMS
<type>
Message type, optional parameter.
Possible values:
bookmark To send WAP bookmarks
longSMS To send concatenated SMS
nSMS To send notification SMS
<wapurl>
WAP Push content.
Example:
www.infobiiip.com/something.jpq
<binary>
Binary content, using hexadecimal format.
Cannot be used together with text parameter
Example:
410A0D4243
<datacoding>
Data coding parameter.
Default value: 0
Example:
8 (Unicode data)
<esmclass>
Esm_class parameter
Default value: 0
<srcton>
Source - ton parameter
<srcnpi>
Source - npi parameters
<destton>
Destination - ton parameter
<destnpi>
Destination — npi parameter
<sendDateTime>
Used for scheduled SMS (SMS not sent immediately but at scheduled time).
Example:
4d3h2m1s message will be sent 4 days, 3 hours, 2 minutes and 1 second from now.
You're allowed to use any combination and leave out unnecessary variables.
<ValidityPeriod>
Validity of a message.
Validity period longer then 48h is not supported (it will be automatically set to 48h in that case).
Validity Period pattern:
HH:mm
<appid>
Delievery reports for application.
Possible options:
Value is not recieved all DLR-s without appid will be sent when client send putt request with no appid specified.
Value is recieved only DLR-s with given appid will be delivered when client pulls reports for that appid.
<pushurl>
Where should delievery reports be pushed.
Possible options:
Value is not recieved / Value is no push all DLR-s without pushurl will be pushed to default URL set for your account.
Value is recieved all DLR is sent to the given IJRL (sent as pushurl value), rather than to the default one set for your account.
<nopush>
Which messages should be pushed or pulled.
Possible options:
Value not recieved / Value is 0 all DLR-s with nopush=0 will be pushed, as usual.
Value is recieved / Value is 1 all DLR-s with nopush=1 wilt not be pushed. and will be available for pull.
<gsm>
Message destination address,
must be in international (format without leading 0 or +)
Example:
41793026727
<gsm messageId=“clientmsgID1“>
Registered delivery - messageID set by client.

XML Structure

An XML formatted string needs to have XML= preceding it for the server to accept it. 
XML=<SMS> 
   <authentication> 
      <username></username> 
      <password></password> 
   </authentication> 
   <message> 
      <sender></sender> 
      <text></text> 
      <flash></flash> 
      <type></type> 
        <wapurl></wapurl> 
        <binary></binary> 
        <datacoding></datacoding> 
        <esmclass></esmclass> 
        <srcton></srcton> 
        <srcnpi></srcnpi> 
        <destton></destton> 
        <destnpi></destnpi> 
        <sendDateTime></sendDateTime> 
        <ValidityPeriod></ValidityPeriod> 
        <appid></appid> 
        <pushurl></pushurl> 
        <nopush></nopush> 
     <recipients>   
         <gsm></gsm>
         <gsm></gsm>
         <gsm></gsm>  
        <gsm messageId=“clientmsgID1“></gsm>   
        <gsm messageId=“clientmsgID2“></gsm> 
     </recipients> 
      </message>  
     
      <message> 
       ...
      </message>  
      <recipients>   
        <gsm></gsm> 
        <gsm></gsm> 
        <gsm messageId=“clientmsgID3“></gsm>   
        <gsm messageId=“clientmsgID4“></gsm> 
        <gsm messageId=“clientmsgID5“></gsm> 
        <gsm messageId=“clientmsgID6“></gsm> 
      </recipients>
</SMS>

Request example

POST http://api.infobip.com/api/v3/sendsms/xml
Host:  api.infobip.com
Content-Type: application/xml
Accept: */*

Return values every post returns values

Status codes

Status Value Description
AUTH_FAILED - 1 Invalid username or password
XML_ERROR - 2 Incorrect XML format
NOT_ENOUGH_CREDITS - 3 Not enough credits in user account
NO_RECIPIENTS - 4 No good recipients
GENERAL_ERROR - 5 Error in processing your request
SEND_OK > 0 Number of recipients to which message was sent

XML file

Status Code: 200
Content-Type: text/csv;charset= UTF-8
Content-Length: 411
Date: Tue, 22 May 2012 12:39:48 GMT
 
<?xml version="1.0" encoding="UTF-8"?>
<results>
  <result>
    <status>0</status>
    <messageid>092052214394830334</messageid>
    <destination>385951111111</destination>
  </result>
    <result>
    <status>0</status>
    <messageid>032052214394832214</messageid>
    <destination>385952222222</destination>
  </result>
  <result>
    <status>0</status>
    <messageid>092052214394831436</messageid>
    <destination>385953333333</destination>
  </result>
</results>

Examples copy, modify, use

1 message to 1 recipient 

XML=
<SMS>
   <authentication>
      <username>test</username>
      <password>test</password>
   </authentication>
   <message>
      <sender>Infobip</sender>
      <text>Hello</text>
      <recipients>
         <gsm>385951111111</gsm>
      </recipients>
   </message>
</SMS>

1 message to many recipient

XML=
<SMS>
   <authentication>
      <username>test</username>
      <password>test</password>
   </authentication>
   <message>
      <sender>Infobip</sender>
      <text>Hello</text>
      <recipients>
         <gsm>385951111111</gsm>
         <gsm>385952222222</gsm>
         <gsm>385953333333</gsm>
      </recipients>
   </message>
</SMS>

Send Scheduled SMS

XML=
<SMS>
   <authentication>
      <username>test</username>
      <password>test</password>
   </authentication>
   <message>
      <sender>Infobip</sender>
      <text>Hello</text>
       <sendDateTime>4d3h2m1s</sendDateTime>
      <recipients>
         <gsm>385951111111</gsm>
      </recipients>
   </message>
</SMS>

Send Unicode Message

XML=
<SMS>
   <authentication>
      <username>test</username>
      <password>test</password>
   </authentication>
   <message>
      <sender>Infobip</sender>
      <text>Some unicode characters as č ć š ž </text>
       <datacoding>8</datacoding>
      <recipients>
         <gsm>385951111111</gsm>
      </recipients>
   </message>
</SMS>

Send Concatenated Message

XML=
<SMS>
   <authentication>
      <username>test</username>
      <password>test</password>
   </authentication>
   <message>
      <sender>Infobip</sender>
      <text> Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea commodo consequat. </text>
       <type>longSMS</type>
      <recipients>
         <gsm>385951111111</gsm>
      </recipients>
   </message>
</SMS>

Send Flash Message

XML=
<SMS>
   <authentication>
      <username>test</username>
      <password>test</password>
   </authentication>
   <message>
      <sender>Infobip</sender>
      <text>Hello</text>
      <datacoding>240</datacoding>
         <recipients>
            <gsm>385951111111</gsm>
         </recipients>
   </message>
</SMS>

Back to overview

HTTP Plain passing parameters as query string variables

Query string parameters

<user>
Client username for Infobip system Login.
<password>
Client password for Infobip system Login.
<sender>
Message sender name.
Possible values:
Alphanumeric max. Length 11 characters
Numeric max. length 14 characters
<SMSText>
Message body at the moment 160 characters.
<GSM>
Recipient mobile number in internationa format.
<IsFlash>
Flash message - displays directly on handset screen.
Possible values:
0 Default, false
1 True
<Type>
Message type, optional parameter.
Possible values:
bookmark To send WAP bookmarks
longSMS To send concatenated SMS
nSMS To send notification SMS
<Bookmark>
The WAP URL link..
<DataCoding>
Data coding parameter.
Default value: 0
Example:
8 (Unicode data)
<Esmclass>
Esm_class parameter
Default value: 0
<Binary>
Binary content, optional parameter.

HTTP Plain

Messages sent with the HTTP Plain method, use the HTTP GET protocol.

Similar to the XML method, this method allows SMS messages to be sent, by passing parameters directly as query string variables.

URL for Sending Messages

http://api.infobip.com/api/v3/sendsms/plain

Examples 

http://api.infobip.com/api/v3/sendsms/plain?user=test&password=test&sender=Friend&SMSText=messagetext&GSM=38598514674

http://api.infobip.com/api/v3/sendsms/plain?user=test&password=test&sender=Friend&SMSText=messagetext&SendDateTime=1d2h5m3s&GSM=38598514674

Back to overview

SMPP

Supported SMPP versions

Version Supported
SMPP version 3.4
SMPP version 3.3

Allowed bind modes

Mode Description
bind_transmitter (TX) for submitting submit_sm PDUs
bind_receiver (RX) for receiving deliver_sm PDUs
bind_transceiver (TRX) for submitting and receiving submit_sm and deliver_sm PDUs

The number of simultaneous sessions for a single account is four 4 . In specific circumstances, this cap can be removed on request.

Infobip supported PDUs

  • bind_transmitter
  • bind_receiver
  • bind_transceiver
  • unbind
  • submit_sm
  • deliver_sm
  • enquire_link

Back to overview

Server Responses

Return Values

Upon message submission, Infobip’s server platform will provide the user with a corresponding response value for each message.

This does not apply to SMPP.

Default Response Format

Depending on send method a default output format will be returned by the server.

Method Format
HTTP XML XML
HTTP Plain CSV

Table 1 - Return Values

Value Description
-1 SEND_ERROR (Currently not in use)
-2 NOT_ENOUGHCREDITS
-3 NETWORK_NOTCOVERED
-4 SOCKET_EXCEPTION (Currently not in use)
-5 INVALID_USER_OR_PASS
-6 MISSING_DESTINATION_ADDRESS
-7 MISSING_SMSTEXT
-8 MISSING_SENDERNAME
-9 DESTADDR_INVALIDFORMAT
-10 MISSING_USERNAME
-11 MISSING_PASS
-12 INVALID_DESTINATION_ADDRESS
> 0 Successful, sent MESSAGE ID is the return value

Examples

The default response output format for HTTP XML send method is XML.

<result> 
  <status>0</status> 
  <messageid>[41220100000000001]</messageid> 
  <destination>38598514674</destination> 
  <status>0</status> 
  <messageid>[41220100000000002]</messageid> 
  <destination>447511402446</destination> 
</result>

For HTTP Plain method of sending, the default response is formatted as CSV data.

By adding the output parameter to the submitted request, the user can ignore the default formats, and receive responses in XML, CSV, or JSON formatted values.

Back to overview

PUSH method available to every user

Dedicated URL

A dedicated URL set to receive data from Infobip’s server needs to be assigned to the user’s account.

Delivery Reports

The option to receive message delivery reports (DLR) via PUSH method is available to every user. A dedicated URL set to receive data from Infobip’s server needs to be assigned to the user’s account; either by logging the information in the Infobip Web Application, or having the account manager do it internally.

In case of unavailability of user’s dedicated URL for PUSH delivery reporting during the first attempt, another attempt is made in 60 seconds, another in five minutes, and subsequently every hour for the next 24 hours. If the URL is still not available after this period, delivery report data is discarded.

Examples 

<DeliveryReport> 
   <message id=[Message ID] 
   sentdate=[Sent Date] 
   donedate=[Done Date] 
   status=[Status] /> 
      ..... 
</DeliveryReport>

Back to overview

PULL method pass parameters as query string variables

Possible server error responses include

Code Error
5 Invalid username and/or password
10 Username missing
11 Password missing

PULL method

Similar to the XML method, this method allows sending SMS messages passing parameters directly as query string variables.

URL for submitting the PULL GET request

http://api.infobip.com/api/v3/dr/pull

Examples 

http://api.infobip.com/api/v3/dr/pull?user=test&password=test
http://api.infobip.com/api/v3/dr/pull?user=test&password=test

messageid is an optional parameter, for the users that wish to request delivery reports for specific messages only. It is possible to request data for multiple messages by using comma ( , ) to separate the values.

DLR Examples

<DeliveryReport> 
   <message 
     id=[MsgID 1] 
     sentdate=[Sent Date] 
     donedate=[Done Date] 
   status="DELIVERED" /> 
   <message 
     id=[MsgID 2] 
     sentdate=[Sent Date] 
     donedate=[Done Date] 
   status="NOT_DELIVERED" /> 
   <message 
     id=[MsgID 3] 
     sentdate=[Sent Date] 
     donedate=[Done Date] 
   status="NOT_ENOUGH_CREDITS" /> 
</DeliveryReport>

Back to overview

SMPP

Message Statuses

message_stat can contain the following statuses

  • DELIVERD
  • EXPIRED
  • DELETED
  • ACCEPTD
  • UNKNOWN
  • REJECTED

SMPP Delievery Reports

Delivery reports are contained in the 'deliver_sm' PDU, received by user through a receiver or transceiver bind, in the following format:

id:<message_id> 
sub:<message_sub> 
dlvrd:<message_dlvrd> 
submit date:<message_submit_date> 
done date:<message_done_date> 
stat:<message_stat> 
err:<message_err>

Back to overview

Number Context over HTTP

Types of HTTP Request

  1. SYNCHRONOUS
  2. ASYNCHRONOUS

URL for submitting SYNCHRONOUS requests

http://api.infobip.com/api/hlr/sync

Example

With PUSH method, the delivery report is formatted as XML data

http://api.infobip.com/api/hlr/sync?user=[username]&pass=[password]&destination=38598514674&output=[output]

By adding the output parameter to the submitted request, the user can ignore the default format, and receive responses in XML, CSV, or JSON formatted values.

Synchronous HTTP Number Context method is limited to a single query per request, but the Number Context information is returned immediately as a server response, eliminating the need for the callback server. Both GET and POST are valid methods for submitting requests.

CSV RESPONSE Example

38598514674; 12a1d36009f-1-1d; DELIVRD; 219011000245540; 38598042003; 0;3859812004; T-MobileHR; T-MobileHR; T-MobileHR; HR; 21901; Croatia; 100; 98; Croatia; HR; 385; false; 98; 385; true;

Response parameters

  • Destination
  • Id
  • Status
  • IMSI
  • Serving MSC
  • Error code
  • Serving Number Context
  • Original network name
  • Ported network name
  • Roaming network name
  • Roaming country code
  • MCCMNC
  • Roaming country name
  • Price per message
  • Original network prefix
  • Original country name
  • Original country code
  • Original country prefix
  • Is number ported
  • Roaming network prefix
  • Roaming country prefix
  • Is number correct

URL for submitting ASYNCHRONOUS requests

http://api.infobip.com/api/hlr/query.aspx

Example

http://api.infobip.com/api/hlr/query.aspx?user=[username]&pass=[password]&destinations=38598514674;447511402446

Multiple destination addresses (MSISDNs) can be submitted for an asynchronous Number Context query in a single request, by separating values with a semicolon ( ; ).

Asynchronous HTTP Number Context method allows user to submit up to a hundred (100) queries in a single request. Data is processed immediately, and responses returned to the user through a standard HTTP server response.

OK 38598514674; OK; 134320ac0d7-f0b-1 447511402446;OK;134320ac0d7-f0b-2

The first line of the response is [OK] when the request is processed correctly. A [FAILED] response means that a parameter is missing or incorrect. If the request is [OK], the response will contain the following data, separated by line breaks for every MSISDN:

[Destination Address]; [Request Status]; [Message ID]

Asynchronous Number Context – delivery reports

A single report can contain information on up to a hundred (100) MSISDNs. It’s delivered in a HTTP request sent to the user’s callback URL, and contained within a POST variable [dlr] in the following format:

Statuses may be: DELIVRD, UNDELIV, or UNKNOWN (in case of a request error).

Back to overview

Number Context over SMPP

How to use

Using Infobip SMPP account, it is possible to request Number Context data (IMSI).

Use your default system_id and password, setting system_type = HLR in Bind PDU.

'SubmitSM' PDU is used for submitting the Number Context request, having destAddress parameter set to the required destination address. All other parameters will be ignored (srcAddress, TON/NPI, etc). Infobip Number Context subsystem will respond using a regular SubmitSMResp, containing messageid reference.

Once the Number Context request is being finalized on the Infobip system, you will receive DeliverSM PDU, containing the IMSI for the required destAddress, or error code in case of failure. DeliverSM will contain short message data with our regular delivery report, together with IMSI:xxxxxxxxx part (containing IMSI), serving MSC and a number of optional info fields depending on your package.

Table : Optional SMPP Info Parameters

Name Type Hex Decimal
Original network name TLVString 0x1412 5138
Original network prefix TLVString 0x140B 5131
Original country TLVString 0x1422 5154
Original country code TLVString 0x1423 5155
Original country prefix TLVString 0x1424 5156
Ported network name TLVString 0x1413 5139
Is number ported TLVInt 0x1421 5153
Roaming network name TLVString 0x1414 5140
Roaming network prefix TLVString 0x1419 5145
Roaming country name TLVString 0x1415 5141
Roaming country code TLVString 0x1417 5143
Roaming country prefix TLVString 0x1420 5152
MCCMNC TLVString 0x1416 5142
Price per message TLVInt 0x1418 5144
Serving Number Context TLVString 0x1409 5129
Is number correct TLVInt 0x1425 5157

Besides DeliverSM.shortMessage, IMSI has been included as an extra-optional parameter: SMPP_VENDOR_SPECIFIC_IMSI = 0x1403

Examples

In case of a valid response, deliver_sm will be as follows

addr: 0 0 38591xxxxxxx addr: 0 0 0000000000 msg: id:40072910491427628 sub:001 dlvrd:001 submit date:1007291049 done date:1007291049 stat:DELIVRD err:000 IMSI:219101100935850 MSC:38591016 Number Context:38591xxxxxxx ORN:VipNet PON:VipNet RON:VipNet ROC:HR MCCMNC:21910 opt: (oct: (tlv: 1059) 030000) (byte: (tlv: 1063) 2) (str: (tlv: 30) 40072910491427628) (str: (tlv: 5129) 38591xxxxxxx) (str: (tlv: 5138) VipNet) (str: (tlv: 5139) VipNet) (str: (tlv: 5140) VipNet) (str: (tlv: 5141) Croatia ) (str: (tlv: 5143) HR) (str: (tlv: 5142) 21910) (int: (tlv: 5144) 1) (str: (tlv: 5145) 91) (str: (tlv: 5152) 385) (int: (tlv: 5153) 1) (str: (tlv: 5154) Croatia ) (str: (tlv: 5155) HR) (str: (tlv: 5156) 385) (int: (tlv: 5157) 1) ) (extraopt: (oct: (tlv: 5123) 323139313031313030393335383530) (oct: (tlv: 5126) 3338353931303136) )

In case of a an error, deliver_sm will be as follows

addr: 0 0 385915369423 addr: 0 0 0000000000 msg: id:40072910491419819 sub:001 dlvrd:001 submit date:1007291049 done date:1007291049 stat:UNDELIV err:001 IMSI: MSC: ORN:VipNet MCCMNC: opt: (oct: (tlv: 1059) 030001) (byte: (tlv: 1063) 5) (str: (tlv: 30) 40072910491419819) (str: (tlv: 5138) VipNet) (str: (tlv: 5142) ) (int: (tlv: 5144) 1) (int: (tlv: 5153) 0) (str: (tlv: 5154) Croatia ) (str: (tlv: 5155) HR) (str: (tlv: 5156) 385) (int: (tlv: 5157) 1)

Back to overview

Table : API Parameters

  XML POST HTTP GET HLR SMPP

Authentication

 username user user system_id
password password pass password

Message

 sender sender / /
text SMSText / /
Flash DEPRECATED IsFlash / /
type Type / /
wapurl Bookmark / /
binary Binary / /
DataCoding DataCoding / /
Esmclass Esmclass / /
Srcton Srcton / /
Srcnpi Srcnpi / /
Destton Destton / /
Destnpi Destnpi / /
ValidityPeriod ValidityPeriod / /
sendDateTime sendDateTime / /
/ encoding / /
pushurl 1 pushurl 1 / /
nopush 2 nopush 2 / /

Recipients

 GSM GSM Destination  
GSM      
output (HLR Only)      
messageId=“clientmsgID“      

1 If value is not received or received value is nopush, all DLR-s without pushurl will be pushed to default URL set for your account. If a value is received, DLR is sent to the given URL (sent as pushurl value), rather than to the default one set for your account.

2 If value is not received or received, value is 0 all DLR-s with nopush=0 will be pushed, as usual. If a value is received and received value is 1 all DLR-s with nopush=1 will not be pushed, and will be available for pull.

Pushurl and nopush combinations

  • If pushurl value is not empty and nopush=0, DLR will be pushed
  • If pushurl value is not empty and nopush=1, DLR will not be pushed

 

Back to overview