Messaging Service REST API Specification V2.3.2 Last Modified: 07.October, 2016

Transcription

1 Messaging Service REST API Specification V2.3.2 Last Modified: 07.October, 2016 page 1

2 Revision history Version Date Details Writer /16/2014 First draft Sally Han /13/2014 Revised v.1.1 document. Sally Han /14/2014 Revised v.1.2 document. Sally Han /19/2014 Revised v1.3 document. Sally Han /11/2014 Revised v1.4 document. Sally Han /02/ Changed XML parameters. (replaced _ (underscore) with - Sally Han (bar)) 2. Added Report Responses and return values /23/ Added the description on Concatenated Message. Sally Han 2. Added the Submit packet charset field. 3. Removed to_country from the report set. 4. Added charset to the Submit field /29/ Added the msg_type field to Response. Sally Han 2. Added rescnt to REPORT Response /08/2015 Supplemented specification description. Sally Han /08/2015 Added the report connection information. Sally Han /17/2015 Added the MMS title field. Sally Han /03/2015 Added error codes related a Korean regulation of Sender ID. Sally Han /27/ Changed the Base URL./Added the HTTPS protocol. 2. Changed the report receiving IP. Goonghee Nam 3. Changed the result code. 4. Added the response code (credit/sender ID alteration, etc.) 5. Removed the status parameter of the result sending API Changed Report format Added Sample code Goonghee Nam correct the Response Code : Success example Cliff Lee <err_code>1000</err_code> <err_code>r000</err_code> Request format Added payment_code, client_sub_id field Goonghee Nam As is : path: 'sms/xml?id' + encodeuricomponent('infobank_test') To be : path: 'sms/xml?id=' + encodeuricomponent('infobank_tes t') Goonghee Nam page 2

3 Added Report Return code : Charset conversion error Goonghee Nam page 3

4 Table of Contents 1. INTRO SERVICE FLOWCHART MESSAGE SPECIFICATIONS BASE URL RECEIVING THE RESULT INFORMATION REQUEST FORMAT Example of Request PHP Shell(BASH) Python Ruby nodejs REQUEST RESPONSE FORMAT Example of Request Response Success Fail REPORT FORMAT Example of Report Format Success Failure REPORT RESPONSE FORMAT Example of Report Response RESPONSE AND RESULT CODE RESPONSE RETURN CODE REPORT RETURN CODE APPENDIX CONCATENATED SMS CONTACT US...14 page 4

5 1. Intro This document defines the protocol specification for constructing the interface that enables the Client to send SMS messages via the Infobank Server. Using the HTTP API specification (RESTful method) described in this document, the following functionality is provided: - Connecting & disconnecting to the Infobank Servers (platform) - Sending messages using HTTP, XML and plain text - Collect delivery receipt (DLR) 2. Service Flowchart 6. Response Reports Wireless Environment 1. Request HTTP: The client sends a message according to the REST API specification, using TCP/IP communication. 2. Response HTTP: The server responds to the message sending request received from the client. 3. SEND SMS: The server sends the message to the local carrier. 4. Get Reports: The server receives the message report from the local carrier. 5. Get Reports: Transfers the message report to the client, which has been sent to the server by the local carrier. 6. Response Reports: Transfers the response about the normal reception of the message report to the server. page 5

6 3. Message specifications HTTP METHOD - The HTTP GET/POST method is provided to make a transfer request, and the XML method is used for the transfer response. ENCODING - UTF-8 encoding is provided by default. TIMEZONE - Korean Standard Time KST (UTC+9) is used as the base time of the message Base URL HTTP HTTPS Receiving the result information The IP of the Infobank s server, which sends the result value, should be allowed to access and send us your IP and PORT, in order to receive the message sending result. IP information of the server that sends the result: / Please send your IP and PORT to support@infobank.net 3.3. Request format UTF-8 encoding is used to support various languages. [M] Mandatory, [O] Optional Parameter M/O Type Description from M Char Sender ID (up to 16bytes) e.g.,) When sending to Korea: from= to_country M Char Country code (1 ~ 3 bytes) e.g.,) When sending to Korea: to_country=82 to M Char Recipient (up to 13bytes) e.g.,) When sending to Korea: to= title O Char Message title (up to 40 byte) - The message title requires UTF-8 and URL encoding. - Valid only when sending LMS to Korea. message M Char Message content - The message content requires UTF-8 and URL encoding. report_req M Char Report receiving status - 1 : Reports are received. (This parameter should be set.) page 6

7 charset O Char Encoding setting (1: UTF-8, 2: euc-kr) - UTF-8 encoding will be applied if this parameter is not set. e.g.,) charset=2 (euc-kr) ref O Char A spare field that can be set by the user. (Up to 20bytes, alphabets/numbers only) ttl O Char Valid time of the message (in seconds) e.g.,) ttl=86400 (24hour = 60 * 60 * 24) payment_code O Char Field for separating payment by departments (Max 20 byte) client_sub_id O Char Filed for using several Sender ID and Signature (Max 20 byte) The Sender ID only supports numeric format. If a message exceeding 90bytes in size is sent to Korea, the message will be automatically switched to an LMS (MMS without an attached file) Example of Request PHP <?php $url = ' http_build_query([ 'id' => 'infobank_test', 'pwd' => 'pwinfobank', 'from' => ' ', 'to_country' => '82', 'to' => ' ', 'message' => 'Hello Infobank', 'report_req' => '1' ]); $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $xml = simplexml_load_string($response); if ($xml === false) { echo "Failed loading XML: "; } else { //print_r($xml); //echo($xml->to_country); //echo($xml->to); echo("response code : ". $xml->messages->message->err_code); page 7

8 }?> Shell(BASH) #!/bin/bash curl ' \ -d id=infobank_test \ -d pwd=pwinfobank \ -d from= \ -d to_country=82 \ -d to= \ --data-urlencode "message=hello Infobank" \ -d report_req= Python import urllib params = { 'id': 'infobank_test', 'pwd': 'pwinfobank', 'from': ' ', 'to_country': '82', 'to': ' ', 'message': 'Hello Infobank', 'report_req': '1' } url = ' + urllib.urlencode(params) response = urllib.urlopen(url) print response.read() Ruby require "net/http" require "uri" uri = URI.parse(" params = { "id" => "infobank_test", page 8

9 } "pwd" => "pwinfobank", "from" => " ", "to_country" => "82", "to" => " ", "message" => "Hello Infobank", "report_req" => "1" response = Net::HTTP.post_form(uri, params) puts response.body nodejs var https = require('https'); var options = { host: 'rest.supersms.co', path: 'sms/xml?id=' + encodeuricomponent('infobank_test') + '&pwd=' + encodeuricomponent('pwinfobank') + '&from=' + encodeuricomponent(' ') + '&to_country=' + encodeuricomponent('82') + '&to=' + encodeuricomponent(' ') + '&message=' + encodeuricomponent('hello Infobank') + '&report_req=' + encodeuricomponent(1) }; var req = https.request(options); req.end(); var responsedata = ''; req.on('response', function(res){ res.on('data', function(chunk){ responsedata += chunk; }); res.on('end', function(){ }); console.log(responsedata); page 9

10 }); 3.4. Request Response format Success/Failure can be checked using the response to the request. [M] Mandatory: [O] Optional: Parameter M/O Type Description msgid M Char An ID assigned to the sent message. to_country M Char Country code (1 ~ 3 bytes) e.g.,) When sending to Korea <to_country>82</to_country> to M Char Recipient err_code M Char Message sending result code messages cnt M Char Number of messages msg_type M Char Message type (1. SMS, 2. MMS) E.g.,) If the message has been sent as an MMS <msg_type>2</msg_type> ref O Char A spare field that can be set by the user. - Transfers the ref value set in Request Example of Request Response Success <?xml version='1.0' encoding='utf-8'?> <submit_response> <to_country>82</to_country> <to> </to> <messages cnt= 1 > <message> <msgid> </msgid> <err_code> R000</err_code> <msg_type>1</msg_type> </message> </messages> <ref>aa </ref> </submit_response> Fail <?xml version='1.0' encoding='utf-8'?> <submit_response> page 10

11 <to_country>82</to_country> <to> </to> <messages cnt= 1 > <message> <err_code>r007</err_code> </message> </messages> <ref>aa </ref> </submit_response> See 4.1 Response Return Code for err_code 3.5. Report Format The report transfers the result value with the GET method, using the access information provided by the client. [M] Mandatory: [O] Optional: Parameter M/O Type Description msgid M Char An ID assigned to the sent message. to M Char Recipient (Country code should be excluded) ex) to_country M Char Country code of recipient number ex) 82 err_code M Char Detailed report result code network M Char Mobile network MCCMNC. (MCC: Country code, MNC: Local carrier code) e.g.,) (SKT), (LGU+), (KT) rescnt M Char Number of actual message billing cases * For concatenated messages, send the number of messages that is actually charged. sent_date O Char Time of sent - Based on Korean Standard Time: KST(UTC+9), YYYYMMDDHHMMSS ref O Char A spare field that can be set by the user. - Transfers the ref value set in Request Example of Report Format Success?msgid = &to= &to_country=82&ref=AA &network=45008 &rescnt=1&err_code=1000&sent_date= page 11

12 Failure?msgid= &to= &to_country=82&ref=AA &network=45008&rescnt= 0&err_code=3001 See 4.2. Report Return Code for more details on err_code & status Report Response Format Please see 3.2 Receiving the result information to receive report. The report transfers the result value with the GET method, using the access information provided by the client. [M] Mandatory: [O] Optional: Parameter M/O Type Description msgid M Char An ID assigned to the sent message. to_country M Char Country code (1 ~ 3 bytes) e.g.,) When sending to Korea: to_country=82 To M Char Recipient Example of Report Response <?xml version='1.0' encoding='utf-8'?> <report_response> <msgid> </msgid> <to_country>82</to_country> <to> </to> </report_response > 4. Response and result code 4.1. Response Return Code Status code Description SUCCESS R000 Success FAILURE R001 Server busy INVALID R002 Verification failed INVALID R003 Incorrect recipients format INVALID R004 Incorrect Sender ID format INVALID R005 Invalid message format INVALID R006 Invalid TTL page 12

13 INVALID R007 Invalid parameter error INVALID R008 Spam filtering INVALID R009 Server capacity exceeded. Please retry. INVALID R010 Unregistered Sender ID INVALID R011 A Sender ID is used that violated the Sender ID alteration prevention standard. INVALID R012 No right to send the pertinent service type INVALID R013 Exceeded the maximum number of messages that can be sent UNKNOWN R999 Unknown error 4.2. Report Return Code Status code Description SUCCESS 1000 Success FAILURE 2000 Sending time exceeded. FAILURE 2001 Failed to send. FAILURE 2002 Failed to send. FAILURE 2003 The handset is turned off. FAILURE 2004 The handset message is full. FAILURE 2005 Shadow area FAILURE 2006 The message has been deleted. FAILURE 2007 Temporary handset problem INVALID 3000 Unable to send. INVALID 3001 No subscriber INVALID 3002 Age verification failed. INVALID 3003 Invalid recipients format INVALID 3004 Handset service suspended temporarily. INVALID 3005 Handset call processing state INVALID 3006 Declining incoming calls INVALID 3007 Handset cannot receive a callback URL. INVALID 3008 Other handset problems INVALID 3009 Invalid message format INVALID 3010 Handset that doesn t support MMS. INVALID 3011 Server error INVALID 3012 Spam INVALID 3013 Service denial INVALID 3014 Others INVALID 3015 No transmission path page 13

14 INVALID 3016 Failed to limit the size of the attached file. - Violated the bylaws to prevent alteration of Sender ID. - Some messages during a broadcast message violated the bylaws. INVALID 3018 Prohibited sender ID by Korean carriers. INVALID 3019 Prohibited sender ID by Korean governmental agencies. INVALID 3022 Charset conversion error 5. APPENDIX 5.1. Concatenated SMS A method of sending messages longer than 160 characters. This method is supported by some countries and local carriers. The entire message will be shown as a single message on the actual mobile phone. It is charged according to the number of characters, based on one standard SMS message. When concatenated SMS messages are used, the code to process a long message is included. As a result, 153 characters are considered as the maximum message length when charging the fee. For example, if a 350 character-long message is sent to a country that uses a 160 character-long SMS message as a standard, the fee of three messages will be charged (153 characters characters + 44 characters = 350 characters). 6. Contact Us For any inquiries or comment about these specifications, please send us an (support@infobank.net). page 14