LabsMobile - API - HTTP - GET - Interface - V - 1 - 12 - en
LabsMobile - API - HTTP - GET - Interface - V - 1 - 12 - en
Index
Page
1 Introduction 3
1.1 Changelog 3
11 Recommendations 18
12 Glossary of terms 20
13 GSM 3.38 7-bit alphabet 22
2 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
1 Introduction
This document is based on the LabsMobile API-SMS HTTP/GET 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:
www.labsmobile.com
1.1 Changelog
v2.09 - 01/16/2016
- Prices request
v2.10 - 03/16/2016
- Receive visits (CLICKs)
v2.11 - 03/30/2016
- Confirmations request (ACK)
- Retries in receiving confirmations (ACK)
- Creating a subid when a request has been processed correctly.
v2.12 - 04/18/2017
- Status and error information in ACK confirmations.
3 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
IMPORTANT: All these parameters will be assigned with the values by default to all accounts.
https://api.labsmobile.com/get/send.php
This URL will be shared by all API-SMS accounts that use this interface. The HTTP/GET call
may be authenticated as explained below and may also contain a series of GET variables
that enable delivery of the message.
https://api.labsmobile.com/get/send.php?username=[X]
&password=[X]&message=[X]&msisdn=[X]&sender=[X]
IMPORTANT: The content of all variables must be encoded as URL. It is especially important for
variables message and sender.
Name Description
username Required. Identifies the account that sent the message. It will be
configured as an email account and corresponds to the username
(login) used to access the WebSMS application.
4 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
Name Description
msisdn Required. Telephone numbers that the message is sent to. These
numbers must contain the corresponding country code and be
separated by commas (','). Example: 34609033162,34609362742
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
Example:
&ackurl=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Fclientserver.com%2Freceive_ack.p
hp
5 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
Name Description
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
Example:
&clickurl=https%3A%2F%2Ffanyv88.com%3A443%2Fhttp%2Fclientserver.com%2Freceive_click.p
hp
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%20%17:34:00
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
Example: &[email protected]
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
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.
6 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
2.4 Examples
Sending standard message with numerical sender:
https://api.labsmobile.com/get/send.php?
[email protected]&password=te52wd98&message=helloworld&msisdn=346
09033162&sender=34609033163
https://api.labsmobile.com/get/send.php?
[email protected]&password=te52wd98&message=helloworld&msisdn=346
09033162,34609033163,34609033142&sender=DEMO
If the request is processed correctly the result will always contain a subid field that will
identify the sending. Example:
Code Description
7 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
Code Description
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.
8 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
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.
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:
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.
You can also get in touch with us if you have any doubts or questions:
[email protected] or +34 93 100 35 35.
9 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
The delivery process is the same, but the long variable must be added. All messages with
this variable will be treated as SMSLong messages. All other variables are valid and have the
same features. An example of SMSLong message would be:
https://api.labsmobile.com/get/send.php?
[email protected]&password=te52wd98&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+r
ead+this+text+as+one+single+message.&long=1&msisdn=34609033162&sender=
34609033163
10 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
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:
https://api.labsmobile.com/get/send.php?
[email protected]&password=te52wd98&message=Аликанте+приглашает&u
cs2=1&msisdn=34609033162&sender=34609033163
11 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
The delivery process is the same, but the crt variable must be added. All messages with this
variable will be treated like SMSCert messages. All other variables are valid and have the
same features. An example of SMSCert message would be:
https://api.labsmobile.com/get/send.php?
[email protected]&password=te52wd98&message=Test+message+SMSCert.
&[email protected]&msisdn=34609033162&sender=34609033163
12 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [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=…×tamp=YYYY-MM-DD%20HH:MM:SS
Variable Values
status ok, ko
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.
13 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [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
msisdn Required. The number including the country code without ‘+’ ó ‘00’.
https://[username]:[password]@api.labsmobile.com/ack.php?
subid=[x]&msisdn=[x]
Status Description
IMPORTANT: The timestamp variable contains hours in GMT or UTC and, therefore, will change to
adapt to client's time zone or local time.
14 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [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.
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.
15 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
9 Credit inquiry
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
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.
16 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
10 Prices inquiry
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. The connection is made in the same way that HTTP/
GET sending is made.
The output format can be selected using the format variable and could have the value CSV
(default), XML or JSON.
FR,33,France,1.114
DE,49,Germany,1.8
XML
JSON
{"FR":{"isocode":"FR","prefix":"33","name":"France","credits":1.114},"DE":
{"isocode":"DE","prefix":"49","name":"Germany","credits":1.8}}
17 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [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.
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:
< => <
> => >
& => &
" => "
' => '
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”.
18 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [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.
19 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [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.
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.
20 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [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
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.
21 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
0x00 COMMERCIAL AT @ 64
22 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
0x20 SPACE 32
0x27 APOSTROPHE 39
23 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
0x2A ASTERISK * 42
0x2C COMMA , 44
0x2D HYPHEN-MINUS - 45
0x3A COLON : 58
0x3B SEMICOLON ; 59
24 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
25 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
26 / 27
API-SMS HTTP/GET Interface T. 34 93 100 35 65
April 18, 2017 - v1.12 [email protected]
* Characters that are codified with two bytes that take up two spaces within an SMS.
27 / 27