Trigger SMS API. API Documentation SPLIO - SPRING Contact and Campaign Trigger SMS API - EN v4.0.docx

Transcription

1 API Documentation

2 Summary Introduction... 3 Access... 3 Base URL... 3 Europe hosting... 3 Asia hosting... 3 Authentication... 3 Request format... 4 Response format... 4 Error Codes & Responses... 4 Endpoints... 5 SPRING Contact and Campaign... 5 Accepted parameters... 5 Examples... 6 Usages and samples of returned data... 6 Send a message to a single recipient... 6 Send a message to two recipients... 7 Send a message to two recipients with custom data

3 Introduction SPRING Contact s and SPRING Campaign s 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 SPRING (9 alpha-numeric characters), and recipients by their cellphone number. System fields (firstname, lastname, etc.) and customer fields declared in SPRING can be used to customize the content of the message. Campaigns are gathered per day and per design in order to provide consolidated statistics. Access Base URL Like other SPRING 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 Account Manager. Europe hosting Asia hosting 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 parameters universe and key are provided as argument of the call Example in Postman: 3

4 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 reason, but deprecated. POST must be used instead as it overdraws length limitations that GET can have. 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. 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 4

5 campaign_id: related SPRING s campaign ID Examples of response "status":"ok","result":"done":1,"inserted":"1","campaign_id":"6tjglf8zd","todo":1,"message" :"ok","code":200 or "status":"error","message":"invalid key for this universe","code":400 Response list 200 => OK, message queued. 400 => Bad Request: missing parameters, invalid universe ID, API key or message ID, invalid JSON 500 => Internal Server Error, Something is broken Endpoints The following table lists the available endpoints and their usage. Examples are provided later in the document. SPRING Contact and Campaign METHOD ENDPOINT USAGE RETURNS POST /api/triggersms/nph-4.pl Send a message JSON GET (deprecated) /api/triggersms/nph-4.pl (deprecated) Send a message (deprecated) JSON (deprecated) Accepted parameters Object Type Requirement Description universe string mandatory Universe Id as provided by key string mandatory SMS API key as provided by 5

6 message string mandatory the ID of the design to send to the recipient(s), as seen in SPRING rcpts array[object] mandatory list of recipients cellphone numbers, optionally including custom fields values for each opcode array[object] mandatory SPRING operation code to assign to the campaign category string mandatory SPRING category for the campaign The settings related to the SMS content, such as unicode", long or sender are defined in the design in SPRING. 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. Examples Usages and samples of returned data Send a message to a single recipient POST /api/triggersms/nph-4.pl Example in Postman: 6

7 Example JSON data for rcpts : [ ] "cellphone": " " Example response: "status": "ok", "result": "done": 1, "inserted": "1", "campaign_id": "6tJglfa5d", "todo": 1, "message": "ok", "code": 200 Send a message to two recipients POST /api/triggersms/nph-4.pl 7

8 Example in Postman: Example JSON data for rcpts : [ "cellphone": " ", "cellphone": " " ] Example response: "status": "ok", "result": "done": 2, "inserted": "2", "campaign_id": "6tJglff9e", "todo": 2, "message": "ok", "code": 200 8

9 Send a message to two recipients with custom data POST /api/triggersms/nph-4.pl Example in Postman: Example JSON data for rcpts : [ "firstname": "John", "cellphone": " ", "c0": "123456", "lastname": "Doe", "firstname": "Jane", "cellphone": " ", "c0": "123457", "lastname": "Doe" ] 9

10 Example response: "status": "ok", "result": "done": 2, "inserted": "2", "campaign_id": "6tJglf8zd", "todo": 2, "message": "ok", "code": 200 Considering the following design with ID 6d7K9804z : Hello $firstname$! Your code is $custom_code$ And that the custom field with ID 0 is named custom_code, Then the following messages would be received: RECIPIENT CONTENT Hello John! Your code is Hello Jane! Your code is

11 , French independent group created in 2001, is software provider of Customer Experience Management in Saas mode and specialized in the retail industry., whose R&D is located in France, has a presence in three continents with offices in Paris, Barcelona, Warsaw, Beijing, Shanghai and Sao Paulo. offers solutions that can easily be integrated and have the ability to meet the creative needs of marketers.