HTTP SMS API Technical Specification messagebird.com version may 2014

Transcription

1 HTTP SMS API Technical Specification messagebird.com version may 2014

2 Table of contents TABLE OF CONTENTS 2 1 API CONNECTION QUICK START 3 2 SMS PARAMETERS REQUIRED PARAMETERS USERNAME PASSWORD SENDER BODY DESTINATION OPTIONAL PARAMETERS REFERENCE TIMESTAMP RESPONSETYPE REPLACECHARS TYPE UDH DLR_URL GATEWAY_ID TEST 8 3 PREMIUM SMS PARAMETERS REQUIRED PARAMETERS PREMIUM SMS PARAMETER: TARIFF PREMIUM SMS PARAMETER: SHORTCODE PREMIUM SMS PARAMETER: KEYWORD OPTIONAL PARAMETERS PREMIUM SMS PARAMETER: MID PREMIUM SMS PARAMETER: MEMBER 10 4 RESPONSE CODES XML RESPONSE PLAIN RESPONSE SIMPLE RESPONSE 12 5 API EXAMPLE 13 6 STATUS REPORT PARAMETER SPECIFICATION GSM STATUS REFERENCE 14 7 APPENDIX A: TYPE FORMATS 15

3 1 API CONNECTION Connection to our API is made via the Internet. In order to be able to use our API, you need an account with Messagebird You can block the SMS API based on an IP address/range. The IP address or range can be defined in the account. The Messagebird SMS API can be found at url: All parameters below need to be UTF- 8 coded. Our API accepts both GET and POST requests using application/xwww- form- urlencoded coding. 1.1 Quick start [password]&destination=[recipient(s)]&body=[message]&sender=[sender] Table 1 SMS send example [password]&destination=[recipient(s)]&body=[message]&sender=[sender] &timestamp=[timestamp] Table 2 Schedule example [password]&destination=[recipient(s)]&body=[message]&sender=1008 &tariff=[tariff in cents]&shortcode=1008&keyword=[keyword used] Table 3 Premium SMS send example

4 2 SMS Parameters Beneath you will find the parameters that can be used to send a SMS via our API. Parameter username password reference sender body destination Description Username of the Messagebird account Password of the Messagebird account Unique reference Sender of the message The message that needs to be sent One or several receivers Optional parameter reference timestamp responsetype replacechars type udh dlr_url gateway_id test Description Unique reference The date on which the message needs to be sent The format of the response Replace non GSM- 7 characters by appropriate valid GSM- 7 characters When sending a message, you can specify what type of message it is. The UDH parameter is required if you want to send a binary SMS If you want a dlr notification of the message send to another url then that you have set on the web site. The SMS- route that you wish to use. If test is TRUE, then the message is not actually sent or scheduled. Table 4 HTTP Parameters

5 2.1 parameters Specifications for each parameter are given below username Username of your Messagebird account. Yes, underscore '_' is also accepted. Example Messagebird password Password of your Messagebird account. Yes UTF- 8 Example Secret sender Sender of the message Yes (no if inbox parameter is set) Numeric or + Maximal length Numeric: 16 +: 11 Example Messagebird body The message that needs to be sent. If the body contains signs that are not listed in the GSM- 7 table, it is considered UTF- 8. Yes GSM 7- bit or UTF- 8 Maximal length GSM 7- bit: 1377 UTF- 8: 603 GSM 7- bit: This is a gsm 7- bit test message. UTF- 8: This is a UTF- 8 teşt message.

6 2.1.5 destination One or several receivers. Ja Ues MSISDN Numeric (international format without 00 or + sign) Maximal length 1000 MSISDN's Example , , , Optional parameters Specifications for each parameter are given below reference Unique reference, if this parameter is absent, no status report is sent. Maximal length 128 Example Message timestamp The date on which the message needs to be sent. Numeric (YearMonthDayHourMinute) Now Example (15 February 2012 on 11:25) (2 August 2013 on 00:25) responsetype The format of the response. SIMPLE s XML = xml format PLAIN = text format, separated by pipes " " SIMPLE = text format, code only XML

7 2.2.4 replacechars Replace non GSM- 7 characters by appropriate valid GSM- 7 characters No true s true = Any characters that are not listed in the GSM- 7 character set are replaced by alternative characters false = No characters are converted into alternative characters, if there are any characters that are not listed in the GSM- 7 character set, the message is sent as UTF- 8 (unicode) False type When sending a message, you can specify what type of message it is. You can send messages in 3 types (normal / binary / flash). Attribuut Waarde No normal s normal, binary, flash normal udh The UDH parameter is required if you want to send a binary SMS. This parameter needs to contain the "header" of the SMS message. Attribuut Waarde Nee Alfanumeriek dlr_url If you want a dlr notification of the message send to another url then that you have set on the web site, you can use this parameter. Attribuut Waarde No false s A valid url messagebird.php

8 2.2.8 gateway_id The SMS- route that you wish to use. Adjust the quality of the gateway that you wish to use to send the SMS. This setting overrides the standard quality that you have set in your account for this message. Attribuut Waarde Numeric Waarden 8 = Voice (inclusief vaste nummers) 2 = Basic 1 = Business+ Voorbeeld test If test is TRUE, then the message is not actually sent or scheduled, and there will be no credits deducted. Validation of the message will take place, and you will also receive a normal response back from the API. In the XML and plain response you will receive a test with variable to indicate that it is a test message. Attribuut Waarde No false s true = It is a test message false = Not a test message true

9 3 Premium SMS parameters To send premium SMS messages via the API there are 5 separate parameters available. On top of these separate parameters, the normal parameters, summarized in Chapter 2, also apply. tariff member shortcode keyword mid Table 5 HTTP Premium SMS Parameters 3.1 parameters Description The tariff of the message Member of keyword (subscription service) or not The shortcode The keyword Incomming "message ID" Below follows an extensive specification per parameter Premium SMS parameter: tariff This is the price that the receiver pays for the message. Numeric 000 s 000, 025, 040, 055, 060, 070, 080, 090, 110, 150, 200* of 300* Example Premium SMS parameter: shortcode The short code from which the premium message is sent. Bool false s true, false Example true Premium SMS parameter: keyword The keyword from which the premium message is sent. False Example TO MESSAGEBIRD START GAME

10 3.2 Optional parameters Below follows an extensive specification per parameter Premium SMS parameter: mid When a response is sent to a received message of an end user the message- ID of the received message must be included. Nee Numeric False Example Premium SMS parameter: member This parameter indicates whether the recipient is or is not a member of a subscription service. Bool false s true, false true

11 4 Response Codes Code Description 01 Request has been processed successfully 69 The message cannot be scheduled on this date 70 An incorrect timestamp notation has been used 72 The message is too long 89 Invalid sender 93 One or several receivers are invalid 95 No message has been selected 96 The number of credits is insufficient 97 Invalid username and/or password 98 Your ip address is not authorized based on this account 99 Cannot connect to the server Premium SMS parameters 40 Ongeldige shortcode 41 Ongeldige mid (MO Message ID) 42 Mid niet gevonden 43 Ongeldig tarief 44 Ongeldig lid (van abonnementsdienst) 45 Combinatie gebruikersnaam en keyword/shortcode niet gevonden 46 Lid van abonnementsdienst heeft al maximum aantal berichten ontvangen 47 Premium SMS niet ondersteund door (provider van) ontvanger Table 6 Response Codes

12 4.1 XML Response <?xml version="1.0"?> <response> <item> <responsecode>01</responsecode> <responsemessage>ok</responsemessage> </item> </response> Table 7 XML Response 4.2 PLAIN Response 01 OK Table 8 PLAIN Response 4.3 SIMPLE Response 01 Table 9 SIMPLE Response

13 5 API Example assword&destination= &body=this%20is%20a%20gsm%207- bit%20test%20message.&sender=messagebird&reference= Table 10 send immediately username=your_username&password=your_password&destination= & body=this%20is%20a%20gsm%207- bit%20test%20message.&sender=messagebird&reference= &timestamp= Table 11 schedule

14 6 Status report A url to which the status report should be sent can be defined on our website. The status is sent via a GET request using application/x- www- form- urlencoded coding. The request contains the following parameters: Parameter GSM STATUS REFERENCE Table 12 Status rapport parameters Description The gsm number of the receiver. The status of the message. The reference of the message 6.1 Parameter specification GSM The gsm number of the receiver. MSISDN Numeric (international format without 00 or + sign) STATUS The status of the message s delivered = the message has been delivered successfully not delivered = the message could not be delivered buffered = the message is on hold (phone cannot be reached/is off) delivered REFERENCE The reference of the message. Minimal length 1 Maximal length 128 SMS

15 7 Appendix A: formats Parameter Description abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ See, and the following - + _. Numeric GSM- 7 (03.38) See, and the characters $ è é ù ì ò Ç Ø ø Å å _ Æ æ ß É! # % & ' ( ) * +, -. / : ; < = >? Ä Ö Ñ Ü ä ö ñ ü à space Linebreak (Enter) UTF- 8 MSISDN Timestamp Table 13 formats The following characters need to be counted as 2 characters: ^ { } \ [ ~ ] For more information, please go to: chartable.de/ Numeric, the length may vary depending on the country. In the Netherlands, the length is 11 characters, for example For more information about number formats, please go to: numeric signs. Timestamp layout is: YYYYMMDDHHII (year, month, day, hour, minute)