How can I set up the SMS relay? (EN) – Splio - Documentation

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"}

{"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"
}
]
}