HTTP SMS API Technische Specificatie
messagebird.com
versie 1.1.6 -‐ 05 mei 2014
1
Inhoudsopgave INHOUDSOPGAVE
2
1 VERBINDING MET DE API
4
1.1 QUICK START
4
2 SMS PARAMETERS
5
2.1 VERPLICHTE PARAMETERS 2.1.1 USERNAME 2.1.2 PASSWORD 2.1.3 SENDER 2.1.4 BODY 2.1.5 DESTINATION 2.2 OPTIONELE PARAMETERS 2.2.1 REFERENCE 2.2.2 TIMESTAMP 2.2.3 RESPONSETYPE 2.2.4 REPLACECHARS 2.2.5 INBOX 2.2.6 TYPE 2.2.7 UDH 2.2.8 DLR_URL 2.2.9 GATEWAY_ID 2.2.10 TEST
6 6 6 6 6 7 7 7 7 7 8 8 8 8 9 9 9
3 PREMIUM SMS PARAMETERS
10
3.1 VERPLICHTE PARAMETERS 3.1.1 PREMIUM SMS PARAMETER: TARIFF 3.1.2 PREMIUM SMS PARAMETER: SHORTCODE 3.1.3 PREMIUM SMS PARAMETER: KEYWORD 3.2 OPTIONELE PARAMETERS 3.2.1 PREMIUM SMS PARAMETER: MID 3.2.2 PREMIUM SMS PARAMETER: MEMBER
10 10 10 10 11 11 11
4 RESPONSE CODES
12
4.1 XML RESPONSE 4.2 PLAIN RESPONSE 4.3 SIMPLE RESPONSE
13 13 13
5 API VOORBEELDEN
14
6 STATUS RAPPORT
15
6.1 PARAMETER SPECIFICATIE 6.1.1 GSM 6.1.2 STATUS 6.1.3 REFERENCE
15 15 15 15
7 APPENDIX A: TYPE FORMATEN
16
2
3
1 Verbinding met de API De verbinding met onze API verloopt via het internet. Om gebruik te kunnen maken van onze API heeft u een account nodig bij Messagebird https://www.messagebird.com/user/create. De SMS API kunt u afschermen op IP-‐adres/range. U kunt uw IP-‐adres of range instellen in uw account. De Messagebird SMS API is te bereiken op url: http://api.messagebird.com/api/sms Alle beschreven parameters in dit document dienen UTF-‐8 gecodeerd te zijn. Onze API accepteert zowel GET als POST requests, met de application/x-‐www-‐form-‐ urlencoded codering.
1.1 Quick start http://api.messagebird.com/api/sms?username=[gebruikersnaam]&password= [password]&destination=[ontvanger(s)]&body=[bericht]&sender=[afzender] Table 1 Voorbeeld direct versturen
http://api.messagebird.com/api/sms?username=[gebruikersnaam]&password= [password]&destination=[ontvanger(s)]&body=[bericht]&sender=[afzender] ×tamp=[timestamp] Table 2 Voorbeeld inplannen
http://api.messagebird.com/api/sms?username=[gebruikersnaam]&password= [password]&destination=[ontvanger(s)]&body=[bericht]&sender=1008 &tariff=[tarief in centen]&shortcode=1008&keyword=[te gebruiken keyword] Table 3 Voorbeeld premium SMS
4
2 SMS Parameters Hier onder staan de parameters welke in de aanroep naar onze API gebruikt kunnen worden. Hoofdstuk 3 toont de extra parameters die nodig zijn voor een premium SMS bericht. Parameter Omschrijving username Gebruikersnaam van het Messagebird account password Wachtwoord van het Messagebird account sender Afzender van het bericht body Het bericht dat verzonden moet worden destination Één of meerdere ontvangers
Optionele parameter reference timestamp
Omschrijving Unieke referentie De datum waarop het bericht verstuurd moet worden
responsetype
Het formaat van de response
replacechars
Niet GSM-‐7 karakters vervangen door passende geldige GSM-‐7 karakters Bericht met een shared of dedicated afzender sturen zodat antwoorden in de inbox komen. Bij het versturen van een bericht kunt u aangeven wat voor type bericht het is. De UDH parameters is verplicht wanneer u een binary SMS wilt versturen. Deze parameter dient de “header” van het SMS bericht te bevatten. Een alternatieve url waar u uw statusrapport voor het bericht wilt ontvangen. De SMS-‐route die u wilt gebruiken
inbox type udh dlr_url gateway_id test
Als test op true staat, dan zal het bericht niet daadwerkelijk verzonden of ingepland worden en zullen er geen credits worden afgeschreven.
Table 4 HTTP SMS parameters
5
2.1 Verplichte parameters Hieronder volgt per parameter een uitgebreide specificatie.
2.1.1 username De gebruikersnaam van het Messagebird account. Attribuut Waarde Type Alfanumeriek, ook underscore '_' wordt geaccepteerd Voorbeeld Messagebird
2.1.2 password Wachtwoord van het Messagebird account. Attribuut Waarde Type UTF-‐8 Voorbeeld geheim1
2.1.3 sender Afzender van het bericht. Deze is verplicht tenzij er een inbox bericht met een shared VMN als afzender verstuurd moet worden. Voor een inbox bericht met een dedicated VMN dient de sender parameter deze DVMN te bevatten. Attribuut Waarde Verplicht Ja (nee als inbox parameter is geset) Type Numeriek of alfanumeriek+ Maximale lengte Numeriek: 16 Alfanumeriek+: 11 Voorbeelden +31600000001 0031600000002 31600000003 Messagebird
2.1.4 body Het bericht wat verzonden moet worden. Als er tekens in het bericht gebruikt worden die niet in de GSM-‐7 tabel staan, dan wordt de body als UTF-‐8 beschouwd. Er is echter een uitzondering zie de parameter replacechars . Tevens zijn er in het GSM-‐7 alfabet bepaalde tekens welke dubbel moeten worden beschouwd zie Appendix A voor meer informatie. LET OP: een premium bericht kan uit maximaal 160 tekens bestaan. Attribuut Waarde Type GSM 7-‐bit alfanumeriek of UTF-‐8 Maximale lengte GSM 7-‐bit: 1377 UTF-‐8: 603 Voorbeelden GSM 7-‐bit: Dit is een gsm 7-‐bit test bericht. UTF-‐8: Dit is een UTF-‐8 teşt beriçht. (De tekens ş en ç vallen buiten het GSM-‐7 alfabet).
6
2.1.5 destination Één of meerdere ontvangers komma gescheiden. Verplicht Ja Type MSISDN numeriek (internationaal formaat zonder 00 of +) Maximale lengte 1000 MSISDN's Voorbeelden 31600000001 31600000001,31600000002,31600000003,31600000004
2.2 Optionele parameters Hieronder volgt per parameter een uitgebreide specificatie.
2.2.1 reference Een unieke referentie voor het bericht. Als deze parameter afwezig is, dan wordt er geen status rapport verstuurd. Attribuut Waarde Type Alfanumeriek Maximale lengte 128 Voorbeeld 268431687, bericht1
2.2.2 timestamp De datum wanneer het bericht verstuurd moet worden. Wordt verstuurd in de tijdzone die ingesteld staat in uw account. Het is niet mogelijk om premium SMS berichten in te plannen. Attribuut Waarde Type Numeriek (JaarMaandDagUurMinuut) Standaard Nu Voorbeelden 201202151125 (15 februari 2012 om 11:25) 201308020025 (2 augustus 2013 om 00:25)
2.2.3 responsetype Het formaat welke terug gegeven wordt direct na de aanroep naar de API. Attribuut Waarde Type Alfanumeriek Standaard SIMPLE Waarden SIMPLE = Alleen de response code PLAIN = De response code en response tekst gescheiden door een pipeline “|”. XML = Een XML Document met alle beschikbare gegevens. Voorbeeld XML
7
2.2.4 replacechars Hiermee kan worden bepaald of dat er moet wordt geprobeerd niet GSM-‐7 karakters te vervangen door alternatieve karakters. Mocht het zo zijn dat er na het vervangen nog steeds niet GSM-‐7 karakters in het bericht zitten, dan wordt het bericht als UTF-‐8 verstuurt. Wanneer een bericht als UTF-‐8 verstuurd wordt, dan kunnen er maximaal 603 karakters gebruikt worden, anders 1377 karakters. Zie ook de parameter body. Attribuut Waarde Type Alfanumeriek Standaard true Waarden true = Er wordt geprobeerd niet GSM-‐7 karakters te vervangen door alternatieve karakters. false = Er vindt geen vervanging plaats. Voorbeeld false
2.2.5 inbox Als inbox op true staat, dan zal het bericht als inbox bericht worden verzonden. De sender parameter kan dan achterwege gelaten worden, tenzij het Messagebird account over een dedicated VMN beschikt. Antwoorden op deze berichten komen in de inbox op de website van Messagebird en kunnen ook worden doorgestuurd naar een email of een URL. Attribuut Waarde Type Alfanumeriek Standaard false Waarden true = Het bericht wordt als inbox bericht verstuurd. false = Het bericht wordt niet als inbox bericht verstuurd.
2.2.6 type Bij het versturen van een bericht kunt u aangeven wat voor type bericht het is. Attribuut Waarde Type Alfanumeriek Standaard normal Waarden normal, binary, flash Voorbeeld normal
2.2.7 udh De UDH parameters is verplicht wanneer u een binary SMS wilt versturen. Deze parameter dient de “header” van het SMS bericht te bevatten. Attribuut Waarde Type Alfanumeriek
8
2.2.8 dlr_url Als u de dlr notificatie van het bericht naar een andere url wilt sturen dan dat u standaard heeft ingesteld op de website kunt u deze parameter gebruiken. Attribuut Waarde Type Alphanumeriek Standaard false Waarden Een geldige URL Voorbeeld http://www.voorbeeld.nl/dlr-‐messagebird.php
2.2.9 gateway_id De SMS-‐route die u wilt gebruiken. Stel hier de kwaliteit in van de gateway die u wilt gebruiken om de SMS te versturen. Deze instelling overschrijft de “standaard kwaliteit” die u heeft ingesteld in uw account voor dit bericht. https://messagebird.com/nl/settings/index Attribuut Waarde Type Numeriek Waarden 8 = Voice (inclusief vaste nummers) 2 = Basic 1 = Business+ Voorbeeld 2
2.2.10 test Als test op true staat, dan zal het bericht niet daadwerkelijk verzonden of ingepland worden en zullen er geen credits worden afgeschreven. Validate van het bericht vindt wel plaats, en u ontvangt ook een normale response terug van de API. In de XML en plain response ontvangt u een test variabele mee om aan te geven dat het een test betreft. Attribuut Waarde Type Alphanumeriek Standaard false Waarden true = Het is een test bericht false = Verstuur het bericht normaal
9
3 Premium SMS parameters Voor het versturen van premium SMS berichten via de API zijn er 5 aparte parameters beschikbaar. Naast deze aparte parameters zijn de normale parameters, opgesomd in hoofdstuk 2 ook van toepasing. Parameter Omschrijving tariff Het tarief van het bericht member Lid of geen lid van keyword (abonnementsdienst) shortcode De shortcode keyword Het keyword mid Inkomende "message ID" Table 5 HTTP Premium SMS Parameters
3.1 Verplichte parameters Hieronder volgt per parameter een uitgebreide specificatie.
3.1.1 Premium SMS parameter: tariff Dit is het tarief wat ontvanger betaald voor het bericht Attribuut Waarde Type Numeriek Standaard 000 Waarden 000, 025, 040, 055, 060, 070, 080, 090, 110, 150, 200* of 300* Voorbeeld 025
* Aangezien Telfort geen € 2,00 en € 3,00 premium-‐berichten afhandelt, zult u hier zelf rekening mee moeten houden in uw script. U kunt filteren op basis van operator prefix van het nummer, of de parameter in de MO report. Wanneer u wel een hoger tarief naar een Telfort-‐nummer stuurt, zullen wij in de DLR afleverrapportage een error teruggeven
3.1.2 Premium SMS parameter: shortcode De shortcode waarvandaan het premium bericht wordt verstuurd. Attribuut Waarde Type Bool Standaard false Waarden true, false Voorbeeld true
3.1.3 Premium SMS parameter: keyword Het keyword waarvandaan het premium bericht wordt verstuurd. Attribuut Waarde Type Alphanumeriek Standaard False Voorbeeld TO MESSAGEBIRD START GAME
10
3.2 Optionele parameters Hieronder volgt per parameter een uitgebreide specificatie.
3.2.1 Premium SMS parameter: mid Wanneer er een reactie wordt gestuurd op een ontvangen bericht van een eindgebruiker moet hier het message-‐id van het ontvangen bericht worden meegegeven. Attribuut Waarde Verplicht Nee Type Numeriek Standaard False Voorbeeld 103842033
3.2.2 Premium SMS parameter: member Deze parameter geeft aan of de ontvanger wel of geen lid is van een abonnementsdienst. Attribuut Waarde Verplicht Nee Type Bool Standaard false Waarden true, false Voorbeeld true
11
4 Response Codes Code Omschrijving 01 Request succesvol verwerkt 69 Het bericht mag niet op deze datum ingepland worden 70 Er is een verkeerde timestamp notatie gebruikt 72 Het bericht is te lang 89 Ongeldige afzender 93 Één of meerdere ontvangers zijn ongeldig 95 Er is geen of een leeg bericht meegegeven 96 U heeft onvoldoende credits 97 Ongeldige gebruikersnaam en/of wachtwoord 98 Uw IP adres is niet toegestaan met dit account 99 Kan geen verbinding maken met 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
- 01 OK
Table 7 XML Response Voorbeeld
4.2 PLAIN Response 01|OK
Table 8 PLAIN Response voorbeeld
4.3 SIMPLE Response 01
Table 9 SIMPLE Response voorbeeld
13
5 API Voorbeelden http://api.messagebird.com/api/sms?username=uw_gebruikersnaam&password=uw _wachtwoord&destination=31600000001&body=Dit%20is%20een%20gsm%207-‐ bit%20test%20bericht.&sender=Messagebird Table 9 Voorbeeld direct versturen
http://api.messagebird.com/api/sms? username=uw_gebruikersnaam&password=uw_wachtwoord&destination=31600000 001&body=Dit%20is%20een%20gsm%207-‐ bit%20test%20bericht.&sender=Messagebird×tamp=201402151125 Table 10 Voorbeeld inplannen
http://api.messagebird.com/api/sms? username=uw_gebruikersnaam&password=uw_wachtwoord&destination=31600000 001&body=Dit%20is%20een%20premium%207-‐bit%20test%20bericht.&sender=1008 &tariff=150&member=false&shortcode=1008&keyword=TO%20MESSAGEBIRD Table 11 Voorbeeld premium SMS
14
6 Status rapport Op onze website kan een url worden ingesteld waar de status rapport afgeleverd dienen te worden. De status wordt verzonden middels een GET request met de application/x-‐www-‐form-‐urlencoded codering. De request bevat de volgende parameters: Parameter Omschrijving GSM De MSISDN van de ontvanger STATUS De status van het bericht REFERENCE De referentie van het bericht welke u heeft opgegeven tijdens het versturen Table 12 Status rapport parameters
6.1 Parameter specificatie Hieronder volgt per parameter een uitgebreide specificatie.
6.1.1 GSM De MSISDN van de ontvanger. Attribuut Waarde Type MSISDN numeriek (internationaal formaat zonder 00 of +) Voorbeeld 31600000001
6.1.2 STATUS De status van het bericht gekoppeld aan de reference en GSM Attribuut Waarde Type Alfanumeriek Waarden delivered = Het bericht is succesvol afgeleverd not delivered = Het bericht kon niet worden afgeleverd buffered = Het bericht staat in de wacht. (Telefoon niet bereikbaar of staat uit) Voorbeeld delivered
6.1.3 REFERENCE De unieke referentie van het bericht. Deze heeft u zelf opgegeven bij het versturen van uw bericht. Attribuut Waarde Type AlphaNumeriek Minimale lengte 1 Maximale lengte 128 Voorbeeld SMS268431687
15
7 Appendix A: Type formaten Parameter Alfanumeriek Alfanumeriek+ Numeriek GSM-‐7 (03.38)
UTF-‐8
MSISDN
Timestamp Table 13 Type formaten
Omschrijving abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ 0123456789 Zie Alfanumeriek, en de volgende tekens: @ -‐ + _ . 0123456789 Zie Alfanumeriek, en de onderstaande karakters: @ £ $ ¥ è é ù ì ò Ç Ø ø Å å _ Æ æ ß É ! “ # ¤ % & ' ( ) * + , -‐ . / : ; < = > ? ¡ Ä Ö Ñ Ü § ¿ ä ö ñ ü à spatie Linebreak (Enter) De volgende karakters moeten als twee tekens worden beschouwd: ^ { } \ [ ~ ] | € Voor meer informatie kunt u naar één van de onderstaande websites gaan. http://nl.wikipedia.org/wiki/UTF-‐8 http://www.utf8-‐chartable.de/ Numeriek, afhankelijk van het land, kan de lengte verschillen. De lengte in Nederland is 11 tekens, dat is met land code en zonder de voorloper 0, bijvoorbeeld 31600000001. Voor meet informatie kunt u naar één van de onderstaande websites gaan. http://en.wikipedia.org/wiki/MSISDN http://en.wikipedia.org/wiki/E.164 http://www.numberingplans.com/?page=plans&sub=phonenr 12 numerieke tekens. De opmaak van de timestamp is: YYYYMMDDHHII (jaar, maand, dag, uur, minuut).
16
