0% found this document useful (0 votes)
75 views28 pages

LabsMobile - API - HTTP - POST - Interface - V - 2 - 15 - en

This document provides instructions for integrating applications with LabsMobile's SMS messaging platform API. It describes how to send SMS messages via HTTP POST requests with an XML payload, including required fields like recipient phone numbers and the message text. It also covers optional fields, message formats, and receiving delivery receipts.

Uploaded by

enriquez961472
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
75 views28 pages

LabsMobile - API - HTTP - POST - Interface - V - 2 - 15 - en

This document provides instructions for integrating applications with LabsMobile's SMS messaging platform API. It describes how to send SMS messages via HTTP POST requests with an XML payload, including required fields like recipient phone numbers and the message text. It also covers optional fields, message formats, and receiving delivery receipts.

Uploaded by

enriquez961472
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 28

API-SMS HTTP/POST Interface

Ref. 17041801 - Push SMS, Balance, ACKs.


April 18, 2017 v2.15
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

Index
Page

1 Introduction 3
1.1 Changelog 3

2 Send SMS messages (MT) 4


2.1 Required information 4
2.2 HTTP/POST Messaging 4
2.3 XML format 4

2.4 XML examples 7


2.5 Authentication 7
2.6 Reply or error messages 8
2.7 Filters and security 9

2.8 Supported characters 10


2.9 Account for tests and account applications 10
2.10 Code examples 10

3 Send concatenated messages (SMSLong) 11


4 Send UCS2 messages (SMSUnicode) 12
5 Send certified messages (SMSCert) 13
6 Receive confirmations (ACKs) 14
7 Confirmations request (ACKs) 15
8 Receive visits (CLICKs) 16
9 Credit request 17
10 Prices request 18
10.1 Output examples 18

11 Recommendations 19
12 Glossary of terms 21
13 GSM 3.38 7-bit alphabet 23

2 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

1 Introduction
This document is based on the LabsMobile API-SMS HTTP/POST Interface and it is designed
for technicians and clients that wish to connect their applications to LabsMobile's SMS
messaging platform. The purpose of integrating these applications is to send SMS (MT or
Push SMS) messages and related communications (ACKs and credit search).

This document contains a detailed explanation of the integration process. If you have any
questions or need examples of code, please contact your usual LabsMobile agent or contact
us at:

[email protected]

www.labsmobile.com

1.1 Changelog
v2.12 - 01/16/2016
- Prices request

v2.13 - 03/16/2016
- Receive visits (CLICKs)

v2.14 - 03/30/2016
- Confirmations request (ACK)
- Retries in receiving confirmations (ACK)
- Creating a subid when a request has been processed correctly.

v2.15 - 04/18/2017
- Status and error information in ACK confirmations.

3 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

2 Send SMS messages


(MT)
2.1 Required information
For the integration with the API-SMS HTTP Interface the following information provided by
LabsMobile is essential:
• Username and password (shown on the registration e-mail)
• Specific URL: https://api.labsmobile.com/clients/

Optionally you can communicate to LabsMobile the following parameters:


• IP Address where the messages will be sent. For security purposes the messaging
platform will only admit messages from this/ these IP/s. This functionality is optional, this
option is not activated by default and messages from any IP address will be accepted.
• Sender by default (default TPOA, by default is LABSMOBILE unless otherwise indicated).
• Messages daily limit, by default up to 50,000 sms/per day.
• Messages limit by batch, by default up to 10,000 sms/sending.

IMPORTANT: All these parameters will be assigned with the values by default to all accounts.

2.2 HTTP/POST Messaging


SMS messages are sent through the API-SMS HTTP/POST Interface via HTTP/POST calls to a
URL with the following format:

http://api.labsmobile.com/clients/

The HTTP/POST call may be authenticated as explained below and may also contain a series
of POST variables that enable delivery of the message.

2.3 XML format


The parameters and content of the message will be sent in a HTTP/POST variable named
‘XmlData’ and formatted as XML in the following manner:

$_POST[‘XmlData’] = ‘<sms>...’

The POST 'XmlData' variable must be encoded in UTF-8. Similarly all the answers and
messages sent from the platform LabsMobile are encoded with the same character set
(UTF-8). Below you can see an example of a simple XML format for simple sending:

<?xml version=”1.0” encoding=”UTF-8”?>


<sms><recipient><msisdn>34609542312</msisdn></recipient><message>Test
message number 1</message><tpoa>Sender name</tpoa></sms>

4 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

Name Description

sms Required. Delimits the beginning and end of a message.

recipient Required. Delimits the message recipients.

msisdn Required. Tag that includes a mobile number recipient. The number
must include the country code without ‘+’ ó ‘00’.

Example: 34609033162.

Each customer account has a maximum number of msisdn per


sending. See the terms of your account to see this limit.

message Required. The message to be sent. The maximum message length is


160 characters. Only characters in the GSM 3.38 7bit alphabet, found
at the end of this document, are valid.

tpoa Optional. Sender of the message. May have a numeric (maximum


length, 14 digits) or an alphanumeric (maximum capacity, 11
characters) value. The messaging platform assigns a default sender if
this variable is not included.

By including the sender's mobile number, the message recipient can


easily respond from their mobile phone with the "Reply" button.

The sender can only be defined in some countries due to the


restrictions of the operators. Otherwise the sender is a random numeric
value.

subid Optional. Message ID included in the ACKs (delivery confirmations). It


is a unique delivery ID issued by the API client. It has a maximum
length of 20 characters.

label Optional. Identifies the message for statistical purposes. WebSMS and
other applications use this field to organize and record the message.
Maximum capacity of 255 characters.

Typical information contained in this field: user that has sent the
message, application or module, etc. …

test Optional. If the value is 1, the message will be considered a test. It will
not be sent to the GSM network and, therefore, will not be received on
any mobile devices. However, these messages are accessible using
online search tools. This tag is intended to enable performing
integration tests without an associated cost. Operator and handset
confirmations will not be received.

Example. <test>1</test>

5 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

Name Description

ackurl Optional. URL to which the corresponding delivery confirmation


notifications will be sent. In the preferences section of WebSMS
application you can set the default value for ackurl for all cases without
having to send this tag in each sending.

Example: <ackurl>http://clientserver.com/
receive_ack.php</ackurl>

shortlink Optional. If this field is present in the message and has a value of 1 the
first URL would be replace by a short link of LabsMobile (format: http://
lm0.es/XXXXX). The statistics of visits can be seen in WebSMS
application or can be received in an url with the tag clickurl.

Example: <shortlink>1</shortlink>

clickurl Optional. URL to which the corresponding click confirmation


notifications will be sent if the tag shortlink is enabled. In the
preferences section of WebSMS application you can set the default
value for clickurl for all cases without having to send this tag in each
sending.

Ejemplo: <clickurl>http://clientserver.com/
receive_click.php</clickurl>

scheduled Optional. The message will be sent at the date and time indicated in
this field. If this field has not been specified, the message will be sent
immediately. Format: YYYY-MM-DD HH:MM:SS.

Example: <scheduled>2012-11-07 17:34:00</scheduled>

IMPORTANT: the value of this field must be expressed using GMT time.

long Optional. If this field is present in the message and has a value of 1, the
message field may contain up to 459 characters. Each 153 characters
will be considered a single message (in terms of charges) and the
recipient will receive one, concatenated message.

Example: <long>1</long>

IMPORTANT: This option is only available in some countries due to the


restrictions of the operators.

crt Optional. If this field is present in the message, it will be considered a


certified SMS message. An email with the delivery certificate in an
attachment will be sent to the address contained in this tag.

Example: <crt>[email protected]</crt>

IMPORTANT: This option is only implemented in some countries.

ucs2 Optional. If this field is present in the message the message can
contain any character in the UCS-2 alphabet. In this case the capacity
of the message is 70 characters and can be sent concatenated to a
maximum of 500 characters. Ej. <ucs2>1</ucs2>

6 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

Name Description

nofilter Opcional. If this field is present the platform won’t apply the dupplicate
filter, so no message will be blocked by this filter.

IMPORTANT: The sms, recipient, msisdn, and message tags are mandatory. Messages that
do not contain one or more of these fields will generate an error corresponding to the field in
question. Likewise, blank msisdn and message fields will also generate an error.

2.4 XML examples


Sending standard message with handset delivery confirmation:

<?xml version=”1.0” encoding=”UTF-8”?>


<sms>
<recipient><msisdn>34609542312</msisdn></recipient>
<message>Test message number 1</message>
<acklevel>handset</acklevel>
<ackurl>http://clientserver.com/receive_ack.php</ackurl>
</sms>

Sending multiple test messages with subid and label identifiers:

<?xml version=”1.0” encoding=”UTF-8”?>


<sms>
<recipient>
<msisdn>34609542312</msisdn>
<msisdn>34609542313</msisdn>
<msisdn>34609542315</msisdn>
</recipient>
<test>1</test>
<message>Test message number 1</message>
<subid>L-203</subid>
<label>[from]=websms;[user]=admin
[campaign]=salesJanuary
</label>
</sms>

2.5 Authentication
The authentication method used is specified by the standard IETF RFC 2717. The platform
verifies all calls to the API-Interface SMS HTTP before processing the sending. Also the HTTP
call must be done from a valid IP (optional) and meet all account limitations and filters.

If the user name or password is not correct, the platform will respond with an HTTP 401
Unauthorized standard code.

If the call or HTTP request is from an IP not set as a valid source, the platform will respond
with an HTTP 403 Forbidden standard code.

Authentication example in a url:


https://username%40domain.com:[email protected]/script.php

Example in PHP with curl:


7 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $username.':'.$password);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, 'XmlData='.$sms);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 15);
$result = curl_exec($ch);

2.6 Reply or error messages


Every HTTP call or request shall be verified by the messaging platform. Both if the request is
correct or if an error is found, an XML message will be returned with the code corresponding
with the verification result. The only exception is if an authentication error occurs (HTTP 401
Unauthorized) or if a request is made from an invalid IP address (HTTP 403 Forbidden).

This is the format of the XML response message to an HTTP/POST request:

<?xml version=”1.0” encoding=”UTF-8”?>


<response>
<code>[Numeric code]</code>
<message>[Description]</message>
</response>

If the request is processed correctly the result will always contain a subid field that will
identify the sending. Example:

<?xml version=”1.0” encoding=”UTF-8”?>


<response>
<code>0</code>
<message>Message has been successfully sent</message>
<subid>56fb9baa6bc22</subid>
</response>

This is the complete response code list:

Code Description

0 Message has been successfully sent

10 Missing XML data in request

11 Badly formed XML in request

20 The message element must be present in the XML

21 The message element cannot be empty

22 Message too long. There is a limit of 160 7-bit characters

23 There are no recipients

24 Too many recipients

25 TPOA is exceeding max length

26 TPOA change is not allowed for this account

8 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

Code Description

27 This message contained one or more invalid character(s)

28 Subid is exceeding maximum length

30 There was an error while sending the message

31 AckLevel has been given but missing AckUrl

32 AckUrl has been given but missing AckLevel

33 An unknown value for AckLevel has been given. Allowed values


are gateway, operator or handset.

34 Label field too long

35 The account has no enough credit for this sending

36 Msisdn format [number] is not allowed

37 The account has reach the maximum messages per day

38 There was an error while sending the message to this MSISDNs


(‘<msisdsn>’)

39 The value of the Scheduled field is not a valid datetime format

40 The username cannot send scheduled messages

41 Scheduled messages cannot be send in test mode

2.7 Filters and security


As shown on the error codes and on the Authentication section, there are different security
measures in delivering to prevent improper use:
• Username and password authentication.
• List of IPs of origin accepted.
• Possibility of encryption of the sent/received data (HTTPS).
• Maximum number by batch or delivery.
• Maximum number of daily sent messages.
• Filter of duplicated messages.
• Credit of the account in case of it being a prepaid account.

All these parameters may vary according to the account. Check out the PREFERENCES
section of your WebSMS account to know the values of these filters or contact your
LabsMobile agent.

IMPORTANT: The filter of duplicated messages will block (not deliver) messages with the same text
and sender sent to the same number within the same hour. Therefore, only the first message will be
sent and the duplicated ones (same text) will remain marked as duplicated and will not be sent. The
duplicated messages are visible on the SEARCHER of the application WebSMS.

9 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

2.8 Supported characters


The LabsMobile messaging platform supports the GSM (GSM 3.38 7-bit) alphabet standard.
The message (<message>) and sender (<tpoa>) fields therefore must only contain
characters in this alphabet. The last chapter of this document contains a complete list of the
GSM alphabet.

Messages sent containing unsupported characters will be returned along with the
corresponding error message. From LabsMobile, we advise substituting some of these
character for others that are permitted while conserving the message's meaning. An example
is presented below:

$message = ‘Subs chars áíóúçÑ’;


$ko = array(‘á’,’í’,’ó’,’ú’,’ç’,’Ñ’);
$ok = array(‘a’,’i’,’o’,’u’,’Ç’,’ñ’);
$message = str_replace($ko, $ok, $message);
echo $message;
// output: ‘Subs chars aiouÇñ’

2.9 Account for tests and account applications


You can request your own account following the steps to create an account on
www.labsmobile.com. You will instantly receive an email with your account details (username/
password). This account can be used through the online application (WebSMS - http://
websms.labsmobile.com) or on any of the SMSAPI (POST, GET, Mail, and WebService)
interfaces.

During the integration process, the test tag is available for test messages. These are
simulated messages that will NOT be sent to the specified mobile device and are useful for
performing initial tests at no cost. Test messages will not generate an acknowledgement of
receipt (ACK) and may be accessed on the WebSMS application in the BROWSER module.

2.10 Code examples


In the following link: http://www.labsmobile.com/en/api/code you will find code examples in
different languages and technologies.

You can also get in touch with us if you have any doubts or questions:
[email protected] or +34 93 100 35 35.

10 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

3 Send concatenated messages


(SMSLong)
SMSLong messages are SMS messages with a size that exceeds 160 characters. These
messages are billed as multiple messages (each 153 characters) but the recipient will
receive them as if they were a single message. Please visit the LabsMobile site to learn more
about this type of message.

IMPORTANT: Concatenated messages have a maximum capacity of up to 459 characters.


SMSLong is only available in some countries due to the restrictions of the operators.

The delivery process is the same, but the long tag must be added to the XML format. All
messages with this tag will be treated as SMSLong messages. All other tags are valid and
have the same features. An example of the XML format for an SMSLong message would be

<?xml version=”1.0” encoding=”UTF-8”?>


<sms>
<recipient>
<msisdn>34609542312</msisdn>
</recipient>
<message>Test message SMSLong. This is a very long
message that could reach 459 chars. The output message will be a
unique message and the final user will read this text as one
single message.</message>
<long>1</long>
<tpoa>SenderName</tpoa>
</sms>

11 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

4 Send UCS2 messages


(SMSUnicode)
SMSUnicode messages are SMS messages with characters not present in GSM standard
charset or alphabet. These messages are billed as normal messages for each 70 characters
and with a maximum capacity of 500 characters. Please visit the LabsMobile site to learn
more about this type of message.

IMPORTANT: UCS2 messages have a maximum capacity of up to 500 characters. SMSUnicode is


only available in some countries due to the restrictions of the operators.

The delivery process is the same, but the ucs2 variable must be added. All messages with
this variable will be treated as SMSUnicode messages. All other variables are valid and have
the same features. An example of SMSUnicode message would be:

<?xml version=”1.0” encoding=”UTF-8”?>


<sms>
<recipient>
<msisdn>34609542312</msisdn>
</recipient>
<message>Аликанте приглашает</message>
<ucs2>1</ucs2>
<tpoa>SenderName</tpoa>
</sms>

12 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

5 Send certified messages


(SMSCert)
SMSCert messages are SMS messages with a delivery and receipt certificate. These
messages are unique in that they generate a PDF document that verifies the delivery and
receipt of the message. Please visit the LabsMobile site to learn more about this type of
message.

IMPORTANT: Concatenated messages have a technical capacity of up to 750 characters. SMSCert


is only implemented in some countries.

The delivery process is the same, but the crt tag must be added to the XML format. All
messages with this tag will be treated like SMSCert messages. All other tags are valid and
have the same features. An example of the XML format for an SMSCert message would be:

<?xml version=”1.0” encoding=”UTF-8”?>


<sms>
<recipient>
<msisdn>34609542312</msisdn>
</recipient>
<message>Test message SMSCert.</message>
<crt>[email protected]</crt>
<tpoa>SenderName</tpoa>
</sms>

13 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

6 Receive confirmations
(ACKs)
A client of LabsMobile's API-SMS HTTP Interface may request to receive delivery
confirmations asynchronously in its system. Using the tags subid and ackurl in the XML
format, they can receive HTTP/GET notifications for each mobile number included in the
message. The following levels are available:
• gateway: when the message is sent to the GSM network.
• operator: when the final operator takes charge of the delivery.
• handset: when the mobile device receives the message.
• error: an error occurred while delivering the message. Then the status=ko and the desc
field specifies the error type.

IMPORTANT: Some of the delivery confirmation levels may not be available for some operators or
routes.

The handset confirmation will not be received if there is some type of temporary incident with
the mobile device, such as a lack of coverage/battery power or an inbox issue.

Delivery confirmations will be received at the URL indicated in the ackurl tag and shall have
the following format:

?acklevel=[gateway|operator|handset|error]&msisdn=…&status=[ok|
ko]&desc=…&subid=…&timestamp=YYYY-MM-DD%20HH:MM:SS

Variable Values

acklevel gateway, operator, handset, error

status ok, ko

desc REJECTD, EXPIRED, DUPLICATED, UNDELIV, UNKNOWN

IMPORTANT: The timestamp variable contains hours in GMT or UTC and, therefore, will change to
adapt to client's time zone or local time.

IMPORTANT: If the HTTP/GET call generates an error (HTTP 4xx or 5xx status) the platform would
retry the delivery of the ACK 5 times at the following intervals: 30s, 5m, 30m, 6h, 1d.

14 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

7 Confirmations request
(ACKs)
With a call to a URL (script) it is possible to know the status of an SMS message. The request
must identify the message with two HTTP/GET variables: subid and msisdn. Authentication
should be done with user account and password in the header of the HTTP connection.

Variable Description

subid Required. Sending identifier.

msisdn Required. The number including the country code without ‘+’ ó ‘00’.

The URL for the call confirmation request is:

https://[username]:[password]@api.labsmobile.com/ack.php?
subid=[x]&msisdn=[x]

The result will have the following format:

<?xml version="1.0" encoding="UTF-8"?>


<response>
<subid>X</subid>
<msisdn>X</msisdn>
<status>X</status>
<credits>X</credits>
<desc>X</desc>
<timestamp>X</timestamp>
</response>

The list of possible status are:

Status Description

processed Processed message.

test Message sent in simulated mode with the test variable


enabled.

error Error in message delivery. Then desc field specifies


the error type: REJECTD, EXPIRED, DUPLICATED,
UNDELIV, UNKNOWN.

gateway Message delivered to the GSM network.

operator Message received by the local operator.

handset Message delivered to the device.

IMPORTANT: The timestamp variable contains hours in GMT or UTC and, therefore, will change to
adapt to client's time zone or local time.

15 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

8 Receive visits
(CLICKs)
A client of LabsMobile's API-SMS HTTP Interface may request to receive asynchronously
visit confirmations in an url that was labeled as shortlink. Using the tags subid, shortlink and
clickurl in the XML format, they can receive HTTP/POST JSON notifications for each visit or
click.

To receive these visit notifications is necessary that the message contains the tag shortlink
and its value should be 1. When a visit or click on the shortlink which will replace the original
url occur you will be notified with a HTTP/POST JSON call with all the user details.

The destination URL can be specified in each sending with the tag clickurl or you can set a
default url for all sendings in WebSMS Preferences.

This is the content of a visit notification:

Content-Type: application/json
Accept: application/json

{
"ip" : "XXX.XXX.XXX.XXX",
"useragent" : "…",
"subid" : "…",
"msisdn" : "…",
"timestamp" : "YYYY-MM-DD HH:mm:SS"
}

IMPORTANT: The timestamp variable contains hours in GMT or UTC and, therefore, will change to
adapt to client's time zone or local time.

16 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

9 Credit request
With a call to a URL (script) it is possible to learn the SMS credit for an existing messaging
account. The connection is made with a HTTP/GET call with authentication in the header of
the HTTP connection..

https://[username]:[password]@api.labsmobile.com/balance.php

The result will be in the following format:

<?xml version="1.0" encoding="UTF-8"?>


<response>
<messages>[sms_left]</messages>
</response>

IMPORTANT: The messaging platform will monitor calls to this service and will not allow (block)
constant access. We recommend making credit inquiries only when necessary.

17 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

10 Prices request
With a call to a URL (script) it is possible to know the credits that a single sending will take
depending on the country of delivery.

For all countries::


https://[username]:[password]@api.labsmobile.com/prices.php

For a particular country or countries specifying the ISO country code:


https://[username]:[password]@api.labsmobile.com/prices.php?
countries=FR,DE

The output format can be selected using the format variable and could have the value CSV
(default), XML or JSON.

10.1 Output examples


CSV

FR,33,France,1.114
DE,49,Germany,1.8

XML

<?xml version="1.0" encoding="UTF-8"?>


<prices>
<country>
<isocode>FR</isocode>
<prefix>33</prefix>
<name>France</name>
<credits>1.114</credits>
</country>
<country>
<isocode>DE</isocode>
<prefix>49</prefix>
<name>Germany</name>
<credits>1.8</credits>
</country>
</prices>

JSON

{"FR":{"isocode":"FR","prefix":"33","name":"France","credits":1.114},"DE":
{"isocode":"DE","prefix":"49","name":"Germany","credits":1.8}}

18 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

11 Recommendations
In this section, we introduce 10 items to verify in every integration to ensure that every
message from our SMS messaging platform is sent without a problem. All of the possible
issues and errors are explained in detail in the integration manuals. However, these are 10 of
the most common errors that we recommend you check.

Mandatory fields. The message fields, msisdn (recipient telephone numbers), and the
corresponding authentication fields (user and password) are mandatory.

Message length. The content of the text message must have a value that is not null and does
not exceed the maximum limit of 160 characters for standard SMS messages (459 for
SMSLong).

Valid telephone numbers. The phone numbers must be in numeric format and preceded by
the country code. For messages sent to mobile devices in Spain, the numbers always begin
with 346 or 247 followed by eight more digits.

Capacity of the recipient. The recipient field (TPOA) has a maximum capacity of 16 digits or
11 alphanumeric characters. The permitted characters are letters and numbers ([A-Z|a-z|
0-9]).

Invalid characters in the message. The message field may only contain characters from the
GSM 3.38 7-bit alphabet found in all manuals. We suggest converting some unsupported
characters and disabling other unsupported or replaceable characters.

"á" => "a"


"í" => "i"
"ó" => "o"
"ç" => "Ç"
"¡" => "!"
"`" => "'"

Version and XML codification. All technologies, except for HTTP/GET, use XML as the
language for defining the SMS parameters. The version and codification alphabet must be
specified in the first line. In addition to verifying that it corresponds to the actual messaging
codification, in order to prevent invalid character errors and the escape of reserved
characters:
< => &lt;
> => &gt;
& => &amp;
" => &quot;
' => &apos;

Duplicate message filter. Our platform filters duplicate messages: SMS messages with the
same content sent to the same number within the same hour. The LabsMobile platform will
not charge or send duplicate messages. These messages may be viewed in the WebSMS
application under the label “duplicates”.

19 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

Tests. During the integration period, it is possible to send messages with the test parameter
activated. In this way, clients can perform any type of test at no cost and verify the result in
the WebSMS application.

Traffic limits. LabsMobile accounts have a limit per batch (messages in a single delivery,
10,000 by default) and a SMS limit per day (50,000 by default). If you would like to change
these limits, please contact us.

Security. Once the basic integration is complete, we recommend applying additional security
measures such as an IP filter or HTTPS encryption.

20 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

12 Glossary of terms
XML

Is the abbreviation for eXtensible Markup Language. It´s a extensible metalanguage of tags
developed by W3C. It´s a way of defining languages for a specific need. The SMSAPI of
LabsMobile uses XML to define the format of a SMS message in the http/POST, SMTP (e-mail)
technologies and WebService.

MSISDN

Means Mobile Station Services Digital Network and it identifies a subscription on the GSM or
UMTS net. Meaning, it identifies the subscription and it corresponds with the telephone
number and the SIM card. It has a maximum length of 15 digits and it is composed of the
country code and the member´s number.

ACK

The ACK notifications are the confirmations of delivery of the messages sent by the
LabsMobile messaging platform, It notifies the exact moment on the SMS change of status.

There are three types of ACK notifications:


• Gateway: moment where the message has been validated and sent to the GSM net.
• Operator: moment where the local operator accepts the message and becomes
responsible for its delivery.
• Handset: moment where the message gets to the mobile device. This ACK notification will
not be made if the cell phone: is a valid mobile, it´s turned off or out of signal, has the
voice-mail full or if its in the period of portability.

MT

The SMS-MT messages (Short message Mobile Terminated) are the ones that have a mobile
device as destination. On this information all messages that are sent from the LabsMobile
platform are considered SMS-MT.

MO

The SMS-MO messages (Short message Mobile Originated) are the ones sent from a mobile
device.

The destination can be for example a number associated with the LabsMobile messaging
platform and that this one is able to redirect the message (via WebSMS, SMS, e-mail, http/
GET, http/POST, WebService, etc...).

UTF-8

It´s a set of characters that can represent any Unicode character. It includes all the symbols
used in latin and Anglo-Saxon languages.

This set of characters ( charset) is the one LabsMobile uses and the one that must be used in
communicating with SMSAPI.

21 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

GSM

It´s the global system for the mobile communications (GSM, comes from the french Groupe
Special Mobile). Through this technology of international reach, all SMS messages are send
to mobile devices.

TPOA

Corresponds to the origin of the message or sender. The TPOA (Transmission Path
Originating Address) in a message between two mobiles always contains the mobile number
of the sender but with the LabsMobile messaging platform it can have any value respecting
the maximum size (16 digits if numeric or 11 characters if alphanumeric).

It usually contains the name of the company that sends the message or the number that
wishes to receive the response (InCode, SMSPremium or MSISN).

SSL

The cryptographic protocol SSL (Secure Sockets Layer) ensures a secure connection
through the Internet. This protocol can be used in all communications with the SMSAPI and
the application WebSMS to ensure the privacy and non-vulnerability of the authentication of
the account.

API

Means Application Programming Interface and it establishes rules and specifications to


communicate with the LabsMobile messaging platform from any application. There are
functions developed from various standard technologies (http/POST, http/GET, WebService,
e-mail) to facilitate the integration with any Web, portal, CRM, Desktop application, etc...

http/GET

HTTP is the protocol of communication between web pages. The LabsMobile messaging
platform accepts HTTP/GET calls to send messages. This type of GET invocation sends the
parameters in the same URL.

http/POST

HTTP is the protocol of communication between web pages. The LabsMobile messaging
platform accepts http/POST calls to send messages. This type of POST invocation sends the
parameters of the invocation in the request body and not in the URL.

WebService

A web or WebService is a group of protocols and standards for the data Exchange between
applications. The LabsMobile messaging platform has published WebService for the delivery
of messages with all available options.

22 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

13 GSM 3.38 7-bit alphabet


A list of the characters included in the standard GSM 03.38 7-bit alphabet, supported by the
LabsMobile platform in the message and sender field for SMS messages is presented below.

Hex Description Character ISO-8859-1

0x00 COMMERCIAL AT @ 64

0x01 POUND SIGN £ 163

0x02 DOLLAR SIGN $ 36

0x03 YEN SIGN ¥ 165

0x04 LATIN SMALL LETTER E WITH GRAVE è 232

0x05 LATIN SMALL LETTER E WITH ACUTE é 233

0x06 LATIN SMALL LETTER U WITH GRAVE ù 249

0x07 LATIN SMALL LETTER I WITH GRAVE ì 236

0x08 LATIN SMALL LETTER O WITH GRAVE ò 242

0x09 LATIN CAPITAL LETTER C WITH CEDILLA Ç 199

0x0A LINE FEED 10

0x0B LATIN CAPITAL LETTER O WITH STROKE Ø 216

0x0C LATIN SMALL LETTER O WITH STROKE ø 248

0x0D CARRIAGE RETURN 13

0x0E LATIN CAPITAL LETTER A WITH RING ABOVE Å 197

0x0F LATIN SMALL LETTER A WITH RING ABOVE å 229

0x10 GREEK CAPITAL LETTER DELTA Δ

0x11 LOW LINE _ 95

0x12 GREEK CAPITAL LETTER PHI Φ

0x13 GREEK CAPITAL LETTER GAMMA Γ

0x14 GREEK CAPITAL LETTER LAMBDA Λ

0x15 GREEK CAPITAL LETTER OMEGA Ω

0x16 GREEK CAPITAL LETTER PI Π

0x17 GREEK CAPITAL LETTER PSI Ψ

23 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

Hex Description Character ISO-8859-1

0x18 GREEK CAPITAL LETTER SIGMA Σ

0x19 GREEK CAPITAL LETTER THETA Θ

0x1A GREEK CAPITAL LETTER XI Ξ

0x1B ESCAPE TO EXTENSION TABLE

0x1B0A FORM FEED* 12

0x1B14 CIRCUMFLEX ACCENT* ^ 94

0x1B28 LEFT CURLY BRACKET* { 123

0x1B29 RIGHT CURLY BRACKET* } 125

0x1B2F REVERSE SOLIDUS (BACKSLASH) * \ 92

0x1B3C LEFT SQUARE BRACKET* [ 91

0x1B3D TILDE* ~ 126

0x1B3E RIGHT SQUARE BRACKET* ] 93

0x1B40 VERTICAL BAR* | 124


164
0x1B65 EURO SIGN* €
(ISO-8859-15)
0x1C LATIN CAPITAL LETTER AE Æ 198

0x1D LATIN SMALL LETTER AE æ 230

0x1E LATIN SMALL LETTER SHARP S (German) ß 223

0x1F LATIN CAPITAL LETTER E WITH ACUTE É 201

0x20 SPACE 32

0x21 EXCLAMATION MARK ! 33

0x22 QUOTATION MARK " 34

0x23 NUMBER SIGN # 35

0x25 PERCENT SIGN % 37

0x26 AMPERSAND & 38

0x27 APOSTROPHE 39

0x28 LEFT PARENTHESIS ( 40

0x29 RIGHT PARENTHESIS ) 41

24 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

Hex Description Character ISO-8859-1

0x2A ASTERISK * 42

0x2B PLUS SIGN + 43

0x2C COMMA , 44

0x2D HYPHEN-MINUS - 45

0x2E FULL STOP . 46

0x2F SOLIDUS (SLASH) / 47

0x30 DIGIT ZERO 0 48

0x31 DIGIT ONE 1 49

0x32 DIGIT TWO 2 50

0x33 DIGIT THREE 3 51

0x34 DIGIT FOUR 4 52

0x35 DIGIT FIVE 5 53

0x36 DIGIT SIX 6 54

0x37 DIGIT SEVEN 7 55

0x38 DIGIT EIGHT 8 56

0x39 DIGIT NINE 9 57

0x3A COLON : 58

0x3B SEMICOLON ; 59

0x3C LESS-THAN SIGN < 60

0x3D EQUALS SIGN = 61

0x3E GREATER-THAN SIGN > 62

0x3F QUESTION MARK ? 63

0x40 INVERTED EXCLAMATION MARK ¡ 161

0x41 LATIN CAPITAL LETTER A A 65

0x42 LATIN CAPITAL LETTER B B 66

0x43 LATIN CAPITAL LETTER C C 67

0x44 LATIN CAPITAL LETTER D D 68

25 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

Hex Description Character ISO-8859-1

0x45 LATIN CAPITAL LETTER E E 69

0x46 LATIN CAPITAL LETTER F F 70

0x47 LATIN CAPITAL LETTER G G 71

0x48 LATIN CAPITAL LETTER H H 72

0x49 LATIN CAPITAL LETTER I I 73

0x4A LATIN CAPITAL LETTER J J 74

0x4B LATIN CAPITAL LETTER K K 75

0x4C LATIN CAPITAL LETTER L L 76

0x4D LATIN CAPITAL LETTER M M 77

0x4E LATIN CAPITAL LETTER N N 78

0x4F LATIN CAPITAL LETTER O O 79

0x50 LATIN CAPITAL LETTER P P 80

0x51 LATIN CAPITAL LETTER Q Q 81

0x52 LATIN CAPITAL LETTER R R 82

0x53 LATIN CAPITAL LETTER S S 83

0x54 LATIN CAPITAL LETTER T T 84

0x55 LATIN CAPITAL LETTER U U 85

0x56 LATIN CAPITAL LETTER V V 86

0x57 LATIN CAPITAL LETTER W W 87

0x58 LATIN CAPITAL LETTER X X 88

0x59 LATIN CAPITAL LETTER Y Y 89

0x5A LATIN CAPITAL LETTER Z Z 90

0x5B LATIN CAPITAL LETTER A WITH DIAERESIS Ä 196

0x5C LATIN CAPITAL LETTER O WITH DIAERESIS Ö 214

0x5D LATIN CAPITAL LETTER N WITH TILDE Ñ 209

0x5E LATIN CAPITAL LETTER U WITH DIAERESIS Ü 220

0x5F SECTION SIGN § 167

26 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

Hex Description Character ISO-8859-1

0x60 INVERTED QUESTION MARK ¿ 191

0x61 LATIN SMALL LETTER A a 97

0x62 LATIN SMALL LETTER B b 98

0x63 LATIN SMALL LETTER C c 99

0x64 LATIN SMALL LETTER D d 100

0x65 LATIN SMALL LETTER E e 101

0x66 LATIN SMALL LETTER F f 102

0x67 LATIN SMALL LETTER G g 103

0x68 LATIN SMALL LETTER H h 104

0x69 LATIN SMALL LETTER I i 105

0x6A LATIN SMALL LETTER J j 106

0x6B LATIN SMALL LETTER K k 107

0x6C LATIN SMALL LETTER L l 108

0x6D LATIN SMALL LETTER M m 109

0x6E LATIN SMALL LETTER N n 110

0x6F LATIN SMALL LETTER O o 111

0x70 LATIN SMALL LETTER P p 112

0x71 LATIN SMALL LETTER Q q 113

0x72 LATIN SMALL LETTER R r 114

0x73 LATIN SMALL LETTER S s 115

0x74 LATIN SMALL LETTER T t 116

0x75 LATIN SMALL LETTER U u 117

0x76 LATIN SMALL LETTER V v 118

0x77 LATIN SMALL LETTER W w 119

0x78 LATIN SMALL LETTER X x 120

0x79 LATIN SMALL LETTER Y y 121

0x7A LATIN SMALL LETTER Z z 122

27 / 28
API-SMS HTTP/POST Interface T. 34 93 100 35 65
April 18, 2017 v2.15 [email protected]

Hex Description Character ISO-8859-1

0x7B LATIN SMALL LETTER A WITH DIAERESIS ä 228

0x7C LATIN SMALL LETTER O WITH DIAERESIS ö 246

0x7D LATIN SMALL LETTER N WITH TILDE ñ 241

0x7E LATIN SMALL LETTER U WITH DIAERESIS ü 252

0x7F LATIN SMALL LETTER A WITH GRAVE à 224

* Characters that are codified with two bytes that take up two spaces within an SMS.

28 / 28

You might also like