Nimbow API

Nimbow API

The Nimbow API provides functionality to send SMS automatically. Additionally the delivery status and several other information are provided through the API responses. The Nimbow API can easily be integrated into applications required to send SMS – A2P (Application to Person).

Security of the Nimbow API

The Nimbow API meets the demand on security supporting the possibility to call all Nimbow API functions via an encrypted http connection. The Nimbow API uses the standardised HTTPS over SSL/TLS protocol. The HTTPS connections are established through the port 443 whereas HTTP connections use port 80.

To use an encrypted connection the prefix ‘https’ has to be used to the Nimbow API function.

Besides the secure connection via HTTPS the HTTP can be used. Data exchanges via HTTP are not encrypted.

Format Rules of the API documentation

This section gives a short overview how to use the following information.

Text in monospaced font is meant to be copied and taken as it is.

Text enclosed in [square brackets] must be replaced.

Nimbow API Specification

The Nimbow API is very easy to use and intuitively structured. The following scheme describes the structure of the Nimbow API:

format

Following table lists the supported protocols of the Nimbow API.

Protocols Meaning
http Use http via Port 80
https Use http via Port 443

 

The table below lists all Nimbow API calls. For a more detailed description and usage see the correspondent sections.

Nimbow API Call Meaning
sms Send a single message
balance Get the current balance

 

All format types of the responses supported by the Nimbow API calls are listed in the following table.

Format Type Meaning
HTML (default) Response of the API Call is returned as Hyper Text Mark-up Language (HTML)
JSON Response of the API Call is returned as JavaScript Object Notation (JSON)
XML Response of the API Call is returned as Extensible Mark-up Language (XML)

 

Each Nimbow API call returns a status code. Appendix A provides a list of all Nimbow API calls and the correspondent status codes.

Send SMS

This API function provides the possibility to send a single SMS.

Http(s)-Methods:

GET/POST

Http GET Examples

Send a message:

http://api.nimbow.com/sms?key=COdk59Q1dmr&from=Max&to=4917212345670&text=Hi

Send a Unicode message:

http://api.nimbow.com/sms?key=COdk59Q1dmr&from=Max&to=4917212345670&text=039303B503B903AC002003C303BF03C50020039A03CC03C303BC03B50021&type=unicode

Send a binary Message:

http://api.nimbow.com/sms?key=COdk59Q1dmr&from=Max&to=4917212345670&text=424547494E3A56434152440A56455253494F4E3A322E310A4E3A6E696D626F772E636F6D0A54454C3B574F524B3B564F4943453A303330353535353535350A54454C3B574F524B3B4641583A303330353535353535340A454D41494C3A696E666F406E696D626F772E636F6D0A454E443A5643415244&type=binary&udh=06050423F423f4

Send a flash message:

http://api.nimbow.com/sms?key=COdk59Q1dmr&from=Max&to=4917212345670&text=Hi&flash=true

Send a Unicode flash message:

http://api.nimbow.com/sms?key=COdk59Q1dmr&from=Max&to=4917212345670& text=039303B503B903AC002003C303BF03C50020039A03CC03C303BC03B50021&type=Unicode&flash=true

Parameter:

URL Parameter Required/Optional Description
Key REQUIRED API key saved in your user profile; for HTTP POST: use header ‘X-Nimbow-API-Key’
To REQUIRED Numeric receiver with 5-16 digits
Text REQUIRED Content of message (min. 1 character)
If the number of characters become longer than 160 characters the SMS will be split into parts with each max. 153 characters.
From OPTIONAL Sender can be

  1. Numeric: up to 16 digits
  2. Alpha-numeric: 1-11 characters

If none is given a default sender will be used.

ClientRef OPTIONAL User defined reference given as string. Allowed characters are:

  • a-z
  • A-Z
  • 0-9
  • Dash ‘-‘
  • Underscore ‘_’
GetMessageId OPTIONAL If set to ‘1’ or ‘true’ the API call response contains ‘MessageId’
GetMessageParts OPTIONAL If set to ‘1’ or ‘true’ the API call response contains ‘MessageParts’
GetFrom OPTIONAL If set to ‘1’ or ‘true’ the API call response contains ‘From’
GetTo OPTIONAL If set to ‘1’ or ‘true’ the API call response contains ‘To’
GetCost OPTIONAL If set to ‘1’ or ‘true’ the API call response contains ‘Cost’
GetDeliveryReport OPTIONAL If set to ‘0’ or ‘false’ no delivery report will be send to provided call back
Test OPTIONAL If set to ‘1’ or ‘true’ the message will be handled as follow

  • Saved like each other message
  • Usage of each API Call parameter
  • No DLR Call back handling
  • No transmission
  • No billing
Type OPTIONAL Type can be used to send either Unicode or Binary coded messages:

  • Set to ‘unicode’ to send Unicode message
  • Set to ‘binary’ to send Binary message

Message text must be given in hexadecimal encoded characters, e.g.

&text=039303B503B903AC002003C303BF03C50020039A03CC03C303BC03B50021

Udh OPTIONAL Can be used together with binary messages, i.e. if Type is set to Binary.
Flash OPTIONAL Can be used to send Flash messages.
Format OPTIONAL Can be

  • json
  • html
  • xml

The response of this API function contains at least a status code. If requested in the API call using the correspondent parameter the response can be extended.

Response:

Key Sent in Response Value
StatusCode ALWAYS See Appendix A
MessageId IF REQUESTED Unique Id of the transmitted Message
MessageParts IF REQUESTED Number of messages the SMS was split into
From IF REQUESTED Sender of the transmitted Message
To IF REQUESTED Receiver of the transmitted Message
NetCost IF REQUESTED Cost of the sent Message

Delivery Report

A call-back URL can be provided in the user profile at the Nimbow platform to receive SMS Delivery Reports. The GET URL has to have a valid format containing optional Nimbow parameter. The Nimbow parameter must be given in angle brackets – ‘<‘ and ‘>’.

Example:

Call customer DLR GET URL providing the message ID and delivery state:

http://customer.com/dlr?MsgID=&MsgState=<State>

Parameter:

Parameter Description
MessageId ID of the Message sent
To Normalised ‘To’ number from sent message
From Normalised ‘From’ alphanumeric or numeric sender
State One of the following:
DELIVERED, SUBMITTED, BUFFERED and UNDELIVERED.
ReceiveTS UTC time stamp given as Unix epoch time the DLR was received
EXAMPLE: “1423919873”
SendTS UTC time stamp given as Unix epoch time the Message was sent
EXAMPLE: “1423919873”
ReceiveDT UTC date time given as ISO 8601 the DLR was received
EXAMPLE: “2015-02-14T13:17:53Z”
SendDT UTC date time given as ISO 8601 the Message was sent;
EXAMPLE: “2015-02-14T13:17:53Z
ClientRef Given client reference text of sent Message

Request the current Balance

This API function provides the possibility to request the current balance of the account. The balance value is provided as ‘InvariantCulture’, i.e. the decimal mark is a point.

Http(s)-Methods:

GET/POST

Http GET Examples

Request current balance:

http://api.nimbow.com/balance?key=COdk59Q1dmr

Parameter:

URL Parameter Required/Optional Description
Key REQUIRED API key saved in your user profile; for HTTP POST: use header ‘X-Nimbow-API-Key’
GetDT OPTIONAL If set to ‘1’ or ‘true’ the API call response contains ‘DateTime’
GetTS OPTIONAL If set to ‘1’ or ‘true’ the API call response contains ‘Timestamp’
GetFMC OPTIONAL If set to ‘1’ or ‘true’ the API call response contains ‘FreeMessagesCount’
Format OPTIONAL Can be

  • json
  • html
  • xml

Response:

Key Sent in Response Value
StatusCode ALWAYS See Appendix A
Balance ALWAYS The balance at the time of the request given as InvariantCulture
DateTime IF REQUESTED UTC date time given as ISO 8601 the balance value was taken
EXAMPLE: “2015-02-14T13:17:53Z”

Appendix A Nimbow API Calls and their Status Codes

The following table shows the Nimbow API calls and their status codes and meanings.

API Call Code Meaning Description
All 0 Success The message was successfully accepted for delivery
1 Internal Error An error has occurred in the platform while processing this message
2 Unknown Error An undocumented error occurred
3 Out of Credits Your account does not have sufficient fund to process this message
4 Invalid API Call A valid URL to call the API must be used
5 Invalid API Credentials The provided API key could be wrong or the IP Addressed used is not configured to be allowed to use the API.
sms 101 ‚to‘ – missing The request contains no receiver information
102 ‚text‘ – missing or empty The request contains no message content
200 ‚from‘ – invalid length The numeric sender is allowed to contain max. 16 digits.
203 ‘text’ – contains non GSM character The message text must contain only GSM characters.
If non GSM character shall be sent, please use ‘type=unicode’.
204 ‘from´ – invalid alpha numeric length The alpha numeric sender is allowed to have 1 to 11 characters.
205 ‘to’ – invalid length The receiver must have a length between 5 and 16 digits.
208 ´clientref’ – contains invalid character The ‘clientref’ must contain only valid characters.
209 Invalid Type Wrong type given. See documentation of API Call ‘sms’.
210 Invalid UDH The given UDH is wrong:

  • UDH can only contain hexadecimal characters (0-9 a-f)
  • UDH can only contain up to 14 hexadecimal characters
211 Message Text Needs to be Encoded Using type=Unicode requires the message text to be hex encoded

Appendix B GSM Character Set

If not given otherwise the text of the SMS is sent encoded using the GSM 7-bit default alphabet – see table below [1]. Each character used consumes one place in the message text, i.e. 160 characters can be used in a single message part.

0 1 2 3 4 5 6 7
0 @ sign2 SP 0 ¡ P ¿ p
1 £ _ ! 1 A Q a q
2 $ sign3 2 B R b r
3 ¥ sign3 # 3 C S c s
5 è sign3 % 5 E U e u
6 ù sign3 & 6 F V f v
7 ì sign3 7 G W g w
8 ò sign3 ( 8 H X h x
9 Ç sign3 ) 9 I Y i y
10 LF sign3 * : J Z j z
11 Ø 1) + ; K Ä k ä
12 ø Æ , < L Ö l ö
13 CR æ = M Ñ m ñ
14 Å ß . > N Ü n ü
15 å É / ? O § o à

 

The table below shows the extended character set [1]. Each of those characters consumes two places in a SMS message text.

0 1 2 3 4 5 6 7
0 |
1
2
3
4 ^
5
6
7
8 {
9 }
10 3)
11 1)
12 [
13 ~
14 ]
15 \

NOTE 1):

This code is reserved for the extension to another extension table. On receipt of this code, a receiving entity shall display a space until another extension table is defined. It is not intended that this extension mechanism should be used as an alternative to UCS2 to enhance the 7bit default alphabet character repertoire for national specific character sets.

NOTE 2):

Void

NOTE 3):

This code is defined as a Page Break character and may be used for example in compressed CBS messages. Any mobile station which does not understand the GSM 7 bit default alphabet table extension mechanism will treat this character as Line Feed.