Trigger API SMS
Introduction
The Splio Customer Platform Trigger SMS API allows authorized users to send a text message picked from their universe to one or several recipients.
Designs are identified by their ID in Splio (9 alpha-numeric characters), and recipients by their cellphone number. System fields (firstname
, lastname
, etc.) and customer fields declared in Splio can be used to customize the content of the message.
Campaigns are gathered per day and design to provide consolidated statistics.
It is not possible to use the
$MobileWalletsUrl$
variable with the SMS Trigger API.
Access
Base URL
Like other Splio APIs, the base URL depends on the hosting location of the universe.
- Europe hosting: https://s3s.fr/api/triggersms/
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)
Request format
Parameter values should use UTF-8 encoding. JSON formatting is required for the parameter rcpts
. GET HTTP method is also supported for backward-compatibility reasons, but is deprecated. PUT must be used instead as it overdraws length limitations that GET can have.
Endpoint
PUT/api/triggersms/nph-4.pl
Parameters
Hereafter is a list of mandatory and supported parameters which can be used with
the API:
Object | Type | Requirement | Description |
---|---|---|---|
universe | string | mandatory | Universe ID as provided by Splio |
key | string | mandatory | SMS API key as provided by Splio |
message | string | mandatory | ID of the design to send to the recipient(s), as seen in Splio |
rcpts | array[object] | mandatory | List of recipients cellphone numbers, optionally including custom field values for each |
opcode | array[object] | optional | Splio operation code to assign to the campaign |
category | string | optional | Splio category for the campaign |
The list of recipients should not contain duplicate cellphones. If a cellphone number is present several times, the recipient will receive as many messages as its phone number is repeated.
Response format
Data returned in response messages is always UTF-8 encoded and JSON formatted. The unique response language is English.
Error Codes & Responses
Responses are returned as JSON objects that contain code
, name
, and description
attributes. code
and name
are the HTTP code and name response.
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 decipher errors. In case of success (Return code 200), the addition attribute result
is provided as well, containing the following items:
- todo: count of cellphone numbers received
- done: count of valid cellphone numbers
- inserted: count of messages queued
- campaign_id: related to Splio’s campaign ID
Examples of response
{"status":"ok","result":{"done":1,"inserted":"1","campaign_id":"6tJglf8zd","todo":1},"message"
:"ok","code":200}
{"status":"error","message":"invalid key for this universe","code":400}
Response list
- 200 - OK, message queued.
- 200 - Status = blocked: this means that you have insufficient credit.
- 400 - Bad Request: missing parameters, invalid universe ID, API key or message ID, invalid JSON
- 500 - Internal Server Error, Something is broken.
Examples
Send a message to a single recipient
Example JSON data for rcpts
:
rcpts
:[
{
"cellphone": "+33612345678"
}
]
Send a message to two recipients
Example JSON data for rcpts
:
rcpts
:[
{
"cellphone": "+33612345678"
},
{
"cellphone": "+8618612345678"
}
]
Send a message to two recipients with custom fields
Example JSON data for rcpts
:
rcpts
:[
{
"firstname": "John",
"cellphone": "+33612345678",
"c0": "123456",
"lastname": "Doe"
},
{
"firstname": "Jane",
"cellphone": "+8618612345678",
"c0": "123457",
"lastname": "Doe"
}
]
Example response:
{
"status": "ok",
"result": {
"done": 2,
"inserted": "2",
"campaign_id": "6tJglf8zd",
"todo": 2
},
"message": "ok",
"code": 200
}
Updated 2 months ago