How can I set up the SMS relay? (EN)

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

Accepted parameters

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