SMS Relay. API Documentation SPLIO - SPRING Contact and Campaign SMS Relay API - EN v1.2.docx

Transcription

1 SMS Relay API Documentation

2 Summary Introduction... 3 Access... 3 Base URL... 3 Europe hosting... 3 Asia hosting... 3 Authentication... 3 Single call... 4 Bulk call... 4 Transactional messages... 4 Request format... 4 Response format... 5 Error Codes & Responses... 5 Endpoints... 5 SPRING Contact and Campaign... 6 Accepted parameters... 6 Message / Content... 7 Examples... 8 Usages and samples of returned data... 8 Send a long, Unicode SMS... 8 Send two different SMS in bulk

3 Introduction The SPLIO SMS Relay API provides resources for SPLIO customers or partners to send short text messages (SMS: Short Message Service) to a SIM card hosted in a mobile phone device. 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 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 authentication method differs if you re using the single or the bulk call. 3

4 Single call The parameters universe and key are provided within the argument of the URL Example: nt=%2b &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 SPRING 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 Account Manager to get more information! Request format Parameter values should use UTF-8 encoding, and JSON formatting for the bulk mode. 4

5 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 response "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. 5

6 SPRING Contact and Campaign 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 6

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

8 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=%2b &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%B 0%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%8 D%B0%E6%9C%BA%E5%88%BB%E6%84%8F%E6%89%93%E4%B9%B1%E4%BA%8 6%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 POST /api/forwardsms/2.0/ Example query data: "universe": "my_universe_id", "key": "my_api_key", "messages": [ "recipient": " ", "content": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod", "unicode": true, 8

9 "long": true, "tag": "tag", "callback_url":" state ", "sender": "MyCompany", "recipient": " ", "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":

10 SPLIO is a SaaS marketing software company specialized in Retail. Our SaaS Customer Experience Platform ties together all essential components to implement a digital customer hub orchestrating processes of realtime omnichannel strategies. Building on 15 years of vision, partnerships and understanding of the needs of 500+ global and local retailers, SPLIO has developed a unique intuitive platform that allows marketers to unleash their strategy and aligns all departments of a company ensuring a consistent customer centric approach. SPLIO has offices in Paris, Barcelona, Milan, Beijing, Shanghai, Warsaw and São Paulo