The Splio SMS Relay API provides resources for Splio customers or partners to send short text messages (SMS: Short Message Service) to fixed line or mobile phone devices.
This API has two main uses: the “single” mode, to submit SMS one by one, and the “bulk” mode, which allows to send many SMS in a single API call. There is no hard limit to the number of SMS, but it is considered fair to not send more than 1000 per call.
Authentication methods and parameters format differ between these two modes. These differences are detailed in the present document.
Access
Base URL
Like other Splio APIs, the base URL depends on the hosting location of the universe.
If you’re unsure about the hosting location of your universe, please ask your contact in Splio.
Europe hosting: https://s3s.fr/api/forwardsms/
Asia hosting: https://api.spl4cn.com/api/forwardsms/
Authentication
All requests need to be authenticated through mandatory parameters.
These credentials are generated and communicated to the customer upon request.
- universe id (e.g.: my_universe_id)
- password (e.g.: my_api_key)
The authentication method differs if you’re using the single or the bulk call.
Single call
The parameters “universe” and “key” are provided within the argument of the URL.
Example:
https://s3s.fr/api/forwardsms/1.php?universe=my_universe_id&key=my_api_key&recipie nt=%2B8618600000000&message=Hello%20There
Bulk call
The information “universe” and “key” are elements of the JSON payload.
Example:
{
"universe": "my_universe_id", "key": "my_api_key", "messages": [
{
[…]
}
]
}
Transactional messages
In case of pre-approved transactional traffic, a specific route can be setup for the message to be delivered. Reasons for doing so can be an higher quality of delivery report, the ability to customize the sender name, or to deliver the message during the night, among other things.
A single Splio universe can therefore have several API keys, one for marketing, and one for transactional SMS.
Make sure to specify the type of message you want to send when requesting an API key, and reach out your contact in Splio to get more information!
Request format
Parameter values should use UTF-8 encoding, and JSON formatting for the bulk mode.
Response format
Data returned in response messages is always UTF-8 encoded and JSON formatted. The unique response language is English.
Error Codes & Responses
In addition to the HTTP Return code, responses are returned as JSON objects that contain "code", "name" and "description" attributes. "code" and "name" are the HTTP code and name response.
The description is a human-readable explanation to help deciphering errors.
Examples of responses:
{"code":200,"name":"OK","description":"message queued, status=waiting"}
or
{"code":400,"name":"Bad Request","description":"Given payload is missing some mandatory fields ()"}
Response list
200 => OK: Message is queued
400 => Bad Request: Invalid JSON, Wrong arguments or Missing mandatory fields
401 => Unauthorized: something is wrong with your universe/api key
500 => Internal Server Error: Something Blew up on our side
403 => Forbidden 404 => Not Found
406 => Not Acceptable, Overquota (not enough credit)
500 => Internal Server Error, Something is broken
501 => Not Implemented
Endpoints
The following table lists the available endpoints and their usage. Examples are provided later in the document.
Splio Customer Platform
|
METHOD |
ENDPOINT |
USAGE |
RETURNS |
|
GET |
/api/forwardsms/1.php |
Send a single message |
JSON |
|
POST |
/api/forwardsms/2.0/ |
Send messages in bulk |
JSON |
Accepted parameters
|
Object |
Mode |
Type |
Requirement |
Description |
|
universe |
Both |
string |
mandatory |
Universe Id as provided by Splio |
|
key |
Both |
string |
mandatory |
SMS API key as provided by Splio |
|
message |
Single |
string |
mandatory |
the message to send to the recipient’s telephone number |
|
recipient |
Both |
string |
mandatory |
the recipient’s telephone number, preferably in international format (preceded by “+” or “00”) |
|
messages |
Bulk |
array[object] |
mandatory |
list of SMS to send, including for each: recipient, content, unicode, long, tag, callback_url and sender |
|
content |
Bulk |
string |
mandatory |
the message to send to the recipient’s telephone number |
|
unicode |
Both |
integer |
optional |
set to “1” if your message is Unicode encoded. Default is “0”, meaning GSM-7bit characters only. The maximum size of an unicode-encoded SMS falls to 70 characters. For Chinese characters, this argument must be set to “1” |
|
long |
Both |
integer |
optional |
if set to “1”, a message longer that the maximum allowed size would be sent through multiple SMS. Default value is “0”, meaning oversized messages are truncated. Multipart SMS are billed one message every 153 characters, or 67 characters if Unicode is used |
|
tag |
Both |
string |
optional |
alphanumeric ID linked to the API call to identify the message or campaign later on |
|
callback_url |
Bulk |
string |
optional |
the given URL would be called by an HTTP GET request when a new state occurs for the message. The placeholder state would be replaced by one of these values: “done”, “stop” or “failed”. |
|
sender |
Both |
string |
optional |
customize the message sender displayed on the phone, if allowed by the operators and countries. Please refer to the local laws and rules in that matter. |
Message / Content
The message can be submitted with options detailed in the below sections.
The message should not be more than 160 characters long if ASCII, 70 for Unicode (see below for options “unicode” and “long”).
However, it is important to be aware of the restrictions that could apply in the country of delivery, such as the requirement of a signature, or of an opt-out method in the message. Both these examples would use character space in the message, resulting in either message being truncated, or using more than one credit. If these items (signature and opt-out method) are mandatory but not provided, default values might be added instead, with the same consequences.
For instance, message submitted to China (62 characters):
Hello, and welcome! We wish you a pleasant experience with us!
And message received (71 characters, it therefore costs 2 credits):
【速立优】Hello, and welcome! We wish you a pleasant experience with us!回T退订
Examples: Usages and samples of returned data
Send a long, unicode SMS
GET /api/forwardsms/1.php?universe=my_universe_id&key=my_api_key&recipient=%2B8618600000000&message=Lorem%20Ipsum%EF%
BC%8C%E4%B9%9F%E7%A7%B0%E4%B9%B1%E6%95%B0%E5%81%87%E6%96%87%E6%88%96%E8%80%85%E5%93%9 1%E5%85%83%E6%96%87%E6%9C%AC%
EF%BC%8C%20%E6%98%AF%E5%8D%B0%E5%88%B7%E5%8F%8A%E6%8E%92%E7%89%88%E9%A2%86%E5%9F%9F%E6%89%80%E5%B8%B8%E7%94%A8%E7%9A
%84%E8%99%9A%E6%8B%9F%E6%96%87%E5%AD%97%E3%80%82%E7%94%B1%E4%BA%8E%E6%9B%BE%E7%BB%8F%E4%B8%80%E5%8F%B0%E5%8C%BF%E5%
90%8D%E7%9A%84%E6%89%93%E5%8D%B0%E6%9C%BA%E5%88%BB%E6%84%8F%E6%89%93%E4%B9%B1%E4%BA%86%E4%B8%80%E7%9B%92%E5%8D%B0%E5
%88%B7%E5%AD%97%E4%BD%93%E4%BB%8E%E8%80%8C%E9%80%A0%E5%87%BA%E4%B8%80%E6%9C%AC%E5%AD%97%E4%BD%93%E6%A0%B7%E5%93%81%E4
%B9%A6&long=1&unicode=1
Example response:
{"code":200,"name":"OK","description":"message queued, status=waiting"}
Send two different SMS in bulk
GET /api/forwardsms/2.0/
Example query data:
{
"universe": "my_universe_id", "key": "my_api_key", "messages": [
{
"recipient": "+8618601234567",
"content": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod",
"unicode": true, "long": true, "tag": "tag",
"callback_url":"https://example.org/sms-tracker/my_recipient_id/ state ", "sender": "MyCompany"
},{
"recipient": "+33601234567",
"content": "Donec at ultricies nisl. Phasellus turpis lectus", "unicode": true,
"long": true, "tag": "other-tag",
"sender": "MyCompany"
}
]
}
Example response:
{
"code": 200, "name": "OK", "description":
{
"messages": [
{
"status": "waiting",
"details": [], "nb_unit": 1
},
{
"status": "waiting",
"details": [], "nb_unit": 1
}
],
"nb_message_sent": 2,
"nb_unit_used": 2,
"remaining_quota": 5021
}
}