Dokumentation

Indholdsfortegnelse

Kort introduktion til at bruge Text Reactor
Send sms'er
Obligatoriske parametre
Valgfrie parametre
Fejlkoder
Callback-koder
Kodeeksempel for afsendelse af sms med ASP
Kodeeksempel for afsendelse af sms med PHP
Tips og tricks
Appendix A: Landekoder
Appendix B: GSM-tegn
Appendix C: Dobbelttegn

Kort introduktion til at bruge Text Reactor

Text Reactor er en tjeneste, hvor igennem privatpersoner eller firmaer kan købe sms'er, der herefter kan udsendes til en ganske fornuftig pris. Dokumentationen er enkel, og ønsker man at sende sms'er, kan man komme i gang på 10 minutter.

For at komme i gang, skal der oprettes der en bruger - dette er gratis og kan gøres her. Når brugeren er oprettet, kan man i kontrolpanelet købe sms'er ved at vælge linket Køb sms'er. Her kan man oprette en faktura til sig selv på et givent beløb, som man herefter kan betale enten med kreditkort, bankoverførsel eller Paypal. Grunden til, at man skal oprette en faktura først, er, at man så kan se, hvilket fakturanummer, der kommer til at figurere på ens kontoudtog, hvilket vil gøre bogføring nemmere.

Når man har gennemført betalingen og købt et antal sms'er, kan man se en opgørelse over ens beholdning under Sms-Konto. Under Sms-Konto kan man ligeledes se, hvad det koster at sende sms'er til forskellige destinationer.
På Trafikoversigten kan man søge på og se status for de enkelte afsendte sms'er.

En samling af alle køb og faktura er tilgængelig under Fakturaoversigt.

Send sms'er

Afsendelse af sms'er sker ved at kalde en side på Text Reactor med en række GET-parametre. Siden, der skal kaldes er

http://api.textreactor.com/legacy/sms.php

Når denne side kaldes med et sæt af værdier, vil der blive sendt en sms med de informationer, der er specificerede.

Obligatoriske parametre

Parameter	Paramtertype	Beskrivelse

username	URL-kodet Tekststreng (Maks 64 tegn).	Brugernavnet på Text Reactor - det brugernavn, der er købt sms'er på.


password	URL-kodet Tekststreng eller MD5-kodet Tekststreng (Maks 64 tegn).	Passwordet til Text Reactor. Kan MD5-krypteres, hvis det ønskes.


dialcode	Heltal	Landekoden for modtageren af sms'ens destination. En liste over gyldige landekoder kan ses i Appendix A: Landekoder.

recipient	Heltal	Telefonnummeret på modtageren af sms'en


text	URL-kodet GSM-tekststreng (Maks 459 tegn)	URL-kodet tekst, der skal sendes til modtageren. Text Reactor URL-afkoder selv teksten. Der kan maksimalt sendes 459 tegn, hvilket svarer til 3 sammenkædede sms'er. Tekststrengen må kun indeholde GSM-tegn, der er kan findes en tabel over i Appendix B: GSM-tegn. Desuden er der 9 tegn, der fylder for to, når de sendes til en mobiltelefon. Vær opmærksom på, at brug af sådanne tegn kan forårsage, at sms'en bliver delt op i to, selvom den reelt kun indeholder 160 tegn eller mindre. En liste over disse 9 tegn kan findes i Appendix C: Dobbelttegn.


Eksempel	http://api.textreactor.com/legacy/sms.php?username=textreactor &password=e10adc3949ba59abbe56e057f20f883e&dialcode=45&recipient=12345678 &text=Meddelelse+fra+Text+Reactor%3a+Du+har+netop+sendt+en+sms. Ovenstående kald vil sende en sms til +45 12345678 med teksten Meddelelse fra Text Reactor: Du har netop sendt en sms. gennem brugeren textreactor.

Valgfrie parametre

Parameter	Paramtertype	Beskrivelse

from	Tekststreng [a-ZA-Z0-9] (Maks. 11 tegn - begrænset tegnsæt)	Den afsender, der skal stå på modtagerens telefon. Bemærk at kun store og små bogstaver fra "a" til "z" og tal kan bruges. Hvis der ikke bliver specificeret en afsender, vil afsenderen blive sat som Textreactor.


callback_url	URL-kodet tekststreng	Den side, der skal kaldes, når sms'en er enten afleveret eller fejlet. Der kan specificeres egne GET-parametre - Text Reactor vil blot lægge sine egne parametre til. Dette kan være praktisk, når der skal holdes styr på sms'er. Læs mere om dette under Tips og tricks.




Eksempel	http://api.textreactor.com/legacy/sms.php?username=textreactor &password=e10adc3949ba59abbe56e057f20f883e&dialcode=45&recipient=12345678 &text=Meddelelse+fra+Text+Reactor%3a+Du+har+netop+sendt+en+sms. &from=John+Doe&=callback_url=http%3a%2f%2fwww.example.org%2fcallback%2f%3fsmsid%3d42 Ovenstående kald vil sende en sms til +45 12345678 med teksten Meddelelse fra Text Reactor: Du har netop sendt en sms. gennem brugeren textreactor med afsenderen John Doe. Når Text Reactor får status for sms'en, bliver den sendt videre til http://www.example.org/callback/ med GET-værdierne id, der er 42, og status, der holder koden, der angiver sms'ens status.

Fejlkoder

Efter http://api.textreactor.com/legacy/sms.php er blevet kaldt, vil siden outputte en eller flere fejlkoder som ren tekst (MIME-type text/plain), der indikerer, hvordan beskeden blev modtaget af gatewayen. Hvis der er flere fejlkoder, vil de være adskildt af simikolon, ";".

0	Afventningsstatus
0.0	Beskeden er afleveret til gatewayen og afventer bekræftigelse af aflevering til telefonen.
0.1	Beskeden er afleveret til gatewayen, men der var ikke forbindelse til leverandøren. Beskeden er lagt i kø og vil blive afsendt, når forbindelsen er genoprettet.
0.2	Beskeden er afleveret til gatewayen, men der var ikke forbindelse til leverandøren. Beskeden er termineret.
0.3	Beskeden blev termineret.
1	Autorisationsfejl
1.0	'username'-parameteren kan ikke være tom.
1.1	'username'-parameteren er for lang.
1.2	'password'-parameteren kan ikke være tom.
1.3	'password'-parameteren er for lang.
1.4	Kombinationen af brugernavn og password blev ikke genkendt.
1.5	Brugeren er blokeret.
2	Inputformateringsfejl
2.0	'dialcode'-parameteren kan ikke være tom.
2.1	'dialcode'-parameteren må kun indeholde heltal.
2.2	'dialcode'-parameteren specificerer en destination, der ikke er understøttet.
2.3	'recipient'-parameteren kan ikke være tom.
2.4	'recipient'-parameteren må kun indeholde heltal.
2.5	'recipient'-parameteren er for lang.
2.6	'text'-parameteren kan ikke være tom.
2.7	'text'-parameteren er for lang.
2.8	'text'-parameteren indeholder ulovlige tegn.
2.9	'from'-parameteren er for lang.
2.10	'from'-parameteren indeholder ulovlige tegn.
2.11	'callback'-parameteren er for lang.
2.12	'retry'-parameteren indeholder ikke en gyldig værdi.
3	Kreditfejl
3.0	Brugeren har ikke dækning for sms'en
4	Callbackfejl
4.0	Siden 'callback'-parameteren specificerede var ikke tilgængelig.
5	SMSC-fejl
5.0	SMSC-fejl
6	Timeout
6.0	Beskedens gyldighedsperiode på 7 døgn udløb.
127	Afleveringsstatus
127.0	Beskeden er bekræftet afleveret til telefonen.

Callback-koder

Hvis der specificeres en callback (via parameteren callback_url) - en side, der skal kaldes tilbage til, når Text Reactor har fået status for sms'en - sender Text Reactor en kode med tilbage, der indikerer status for den afsendte sms. Alle callback-koder har en tilsvarende fejlkode.

Text Reactor vil selv lægge en ekstra GET-paramter på callback-URL'en, der hedder status og indeholder en af følgende værdier:

Værdi	Betydning
127.0	Beskeden er bekræftet afleveret til telefonen.
5.0	SMSC fejl. Dette kan skyldes, sms'en er sendt til et nummer, der ikke eksisterer, eller sendt via et netværk, Text Reactor ikke understøtter.
6.0	Beskedens gyldighedsperiode på 7 døgn udløb. Dette kan skyldes, at telefonen, sms'en er sendt til, ikke har været i stand til at modtage sms'en, inden sms'ens gyldighedsperiode udløb. Enten har telefonen været slukket, eller også har den ikke returneret bekræftigelse på modtagelsen.

Kodeeksempler for afsendelse af sms med ASP

Her er et eksempel på, hvordan man kan sende sms igennem Text Reactor med ASP 3.0.

              <%
    ' Build Parameters
    strParameters = "?username=textreactor" &_
                     "&password=123456" &_
                     "&dialcode=45" &_
                     "&recipient=70221961" &_
                     "&text=" & Server.URLEncode("Du har netop modtaget en sms sendt via Text Reactor!")
    ' Send sms
    set objHTTP = Server.CreateObject("MSXML2.ServerXMLHTTP")
        objHTTP.open "GET", "http://api.textreactor.com/legacy/sms.php" & strParameters, False
        objHTTP.send
    ' Save output in strOutput
    strOutput = objHTTP.responseText
    ' Release HTTP-object
    set objHTTP = Nothing
%>

            

Kodeeksempler for afsendelse af sms med PHP

Her er et eksempel på, hvordan man kan sende sms igennem Text Reactor med PHP 5.

              <?php
    // Build Parameters
    $strParameters = "?username=textreactor" .
                     "&password=123456" .
                     "&dialcode=45" .
                     "&recipient=70221961" .
                     "&text=" . urlencode("Du har netop modtaget en sms sendt via Text Reactor!");
    // Send sms and save output in $strOutput
    $strOutput = file_get_contents("http://api.textreactor.com/legacy/sms.php" . $strParameters);
?>

            

Tips og tricks

Sms-specifikke ID'er i callback
Når man laver kaldet til Text Reactor, kan man med fordel i callback_url-parameteren selv sætte en GET-parameter, der indeholder id'en på sms'en fra ens eget system. Så vil den side, der bliver kaldt af callback'en fra Text Reactor, nemt kunne finde ud af, hvilken sms, der skal opdateres status på.

Password i callback
Hvis man er nervøs for, om en ondsindet bruger kan finde på at kalde ens callback-side manuelt og derved ødelægge status for sms'erne i ens egen database, kan man specificere en password-GET-parameter med en given værdi. Når callback'et fra Text Reactor kalder den specificerede callback-side, sender den passwordet med i GET-parameteren. Hvis en ondsindet bruger kalder siden manuelt uden passwordet, udføres der ingen ændringer.

MD5-krypter password
Når man kalder Text Reactor, sendes data i ren tekst. Både på den udgående server og de servere, man går igennem på nettet, for at nå frem til Text Reactor, vil GET-parametrene være synlige i HTTP'headeren, som sandsynligvis bliver gemt i en log et eller flere steder undervejs. Derfor understøtter Text Reactor, at man kan MD5-kryptere passwordet, således at det ikke nemt kan misbruges. PHP understøtter MD5-kryptering direkte med funktionen md5. Programmerer man i ASP, er der flere forskellige MD5-krypteringsscripts, der frit kan hentes fra nettet.

Det bemærkes, at der gøres alt for at holde nedetid på et minimum. Planlagte driftsforstyrrelser vil blive annonceret via email.

Appendix A: Landekoder

Følgende værdier er gyldige for dialcode-parameteren.

Land	Landekode
Afghanistan	93
Albanien	355
Algeriet	213
Andorra	376
Angola	244
Antarktis	672
Argentina	54
Armenien	374
Aruba	297
Aserbajdsjan	994
Australien	61
Bahrain	973
Bangladesh	880
Belarus	375
Belgien	32
Belize	501
Benin	229
Bhutan	975
Bolivia	591
Bosnien & Hercegovina	387
Botswana	267
Brasilien	55
Brunei Darussalam	673
Bulgarien	359
Burkina Faso	226
Burundi	257
Cambodja	855
Cameroun	237
Chile	56
Colombia	57
Comorerne	269
Congo	242
Cook-øerne	682
Costa Rica	506
Cuba	53
Danmark	45
De Forenede Arabiske Emirater	971
De Nederlandske Antiller	599
Den Centralafrikanske Republik	236
Den Demokratiske Republik Congo	243
Ecuador	593
Egypten	20
El Salvador	503
Elfenbenskysten	225
Estland	372
Etiopien	251
Fiji	679
Filippinerne	63
Finland	358
Frankrig	33
Fransk Polynesien	689
Færøerne	298
Gabon	241
Gambia	220
Georgien	995
Ghana	233
Gibraltar	350
Grækenland	30
Grønland	299
Guadeloupe	590
Guatemala	502
Guinea	224
Guinea-Bissau	245
Guyana	592
Haiti	509
Holland	31
Honduras	504
Hongkong	852
Indien	91
Indonesien	62
Irak	964
Iran	98
Irland	353
Island	354
Israel	972
Italien	39
Japan	81
Jordan	962
Kap Verde-øerne	238
Kenya	254
Kina	86
Kirgisistan	996
Kiribati	686
Kroatien	385
Kuwait	965
Laos	856
Lesotho	266
Letland	371
Libanon	961
Liberia	231
Libyen	218
Liechtenstein	423
Litauen	370
Luxembourg	352
Macau	853
Madagaskar	261
Makedonien	389
Malawi	265
Malaysia	60
Maldiverne	960
Malta	356
Marokko	212
Marshall-øerne	692
Mauretanien	222
Mauritius	230
Mexico	52
Moldova	373
Monaco	377
Mongoliet	976
Montenegro	382
Mozambique	258
Namibia	264
Nepal	977
New Zealand	64
Nicaragua	505
Niger	227
Nigeria	234
Nordamerika (USA og Canada)	1
Norge	47
Ny Kaledonien	687
Oman	968
Pakistan	92
Palau	680
Panama	507
Paraguay	595
Peru	51
Polen	48
Portugal	351
Qatar	974
Republikken Mali	223
Rumænien	40
Rusland	7
Rwanda	250
Rèunion	262
Salomonøerne	677
Saudi-Arabien	966
Schweiz	41
Senegal	221
Serbien	381
Seychellerne	248
Sierra Leone	232
Singapore	65
Slovakiet	421
Slovenien	386
Somalia	252
Spanien	34
Sri Lanka	94
St. Pierre & Miquelon	508
Storbritannien	44
Sudan	249
Surinam	597
Sverige	46
Swaziland	268
Sydafrika	27
Sydkorea	82
Syrien	963
Taiwan	886
Tajikistan	992
Tanzania	255
Tchad	235
Thailand	66
Timor-Leste	670
Tjekkiet	420
Togo	228
Tonga Øerne	676
Tunesien	216
Turkmenistan	993
Tyrkiet	90
Tyskland	49
Uganda	256
Ukraine	380
Ungarn	36
Uruguay	598
Usbekistan	998
Vanuatu	678
Venezuela	58
Vietnam	84
Yemen	967
Zambia	260
Zimbabwe	263
Østrig	43

Appendix B: GSM-tegn

Når man sender data til Text Reactor, skal man blot sørge for at URL-encode sin meddelelse. Text Reactor tager sig af at konvertere tegnene til GSM-kodning og sende beskeden videre ud til telefonen via GSM-protokollen.

Følgende liste viser, hvordan de enkelte tegn skal kodes i kaldet til Text Reactor. Tegn, der ikke er beskrevet her, er ikke gyldige, og vil resultere i en fejl "2.8: 'text'-parameteren indeholder ulovlige tegn", hvis de optræder i meddelelsen.

URL-kodningen af tegnene er nøjagtig den samme, som urlencode()-funktionen i PHP og Server.URLEncode()-funktionen i ASP konverterer til.

Bemærk, at linjeskift i sms'er laves ved at kombinere LINE FEED (%0A) og CARRIAGE RETURN (%0D) - altså begge tegn.

Tegn	URL-kodet værdi	Engelsk beskrivelse
@	%40	COMMERCIAL AT
£	%C2%A3	POUND SIGN
$	%24	DOLLAR SIGN
¥	%C2%A5	YEN SIGN
è	%C3%A8	LATIN SMALL LETTER E WITH GRAVE
é	%C3%A9	LATIN SMALL LETTER E WITH ACUTE
ù	%C3%B9	LATIN SMALL LETTER U WITH GRAVE
ì	%C3%AC	LATIN SMALL LETTER I WITH GRAVE
ò	%C3%B2	LATIN SMALL LETTER O WITH GRAVE
ç	%C3%A7	LATIN CAPITAL LETTER C WITH CEDILLA
	%0A	LINE FEED
Ø	%C3%98	LATIN CAPITAL LETTER O WITH STROKE
ø	%C3%B8	LATIN SMALL LETTER O WITH STROKE
	%0D	CARRIAGE RETURN
Å	%C3%85	LATIN CAPITAL LETTER A WITH RING ABOVE
å	%C3%A5	LATIN SMALL LETTER A WITH RING ABOVE
Δ	%CE%94	GREEK CAPITAL LETTER DELTA
_	_	LOW LINE
Φ	%CE%A6	GREEK CAPITAL LETTER PHI
Γ	%CE%93	GREEK CAPITAL LETTER GAMMA
Λ	%CE%9B	GREEK CAPITAL LETTER LAMBDA
Ω	%CE%A9	GREEK CAPITAL LETTER OMEGA
Π	%CE%A0	GREEK CAPITAL LETTER PI
Ψ	%CE%A8	GREEK CAPITAL LETTER PSI
Σ	%CE%A3	GREEK CAPITAL LETTER SIGMA
Θ	%CE%98	GREEK CAPITAL LETTER THETA
Ξ	%CE%9E	GREEK CAPITAL LETTER XI
^	%5E	CIRCUMFLEX ACCENT
{	%7B	LEFT CURLY BRACKET
}	%7D	RIGHT CURLY BRACKET
\	%5C	REVERSE SOLIDUS (BACKSLASH)
[	%5B	LEFT SQUARE BRACKET
~	%7E	TILDE
]	%5D	RIGHT SQUARE BRACKET
\|	%7C	VERTICAL BAR
€	%E2%82%AC	EURO SIGN
Æ	%C3%86	LATIN CAPITAL LETTER AE
æ	%C3%A6	LATIN SMALL LETTER AE
ß	%C3%9F	LATIN SMALL LETTER SHARP S (German)
É	%C3%89	LATIN CAPITAL LETTER E WITH ACUTE
	+	SPACE
!	%21	EXCLAMATION MARK
"	%22	QUOTATION MARK
#	%23	NUMBER SIGN
¤	%C2%A4	CURRENCY SIGN
%	%25	PERCENT SIGN
&	%26	AMPERSAND
'	%27	APOSTROPHE
(	%28	LEFT PARENTHESIS
)	%29	RIGHT PARENTHESIS
*	%2A	ASTERISK
+	%2B	PLUS SIGN
,	%2C	COMMA
-	-	HYPHEN-MINUS
.	.	FULL STOP
/	%2F	SOLIDUS (SLASH)
0	0	DIGIT ZERO
1	1	DIGIT ONE
2	2	DIGIT TWO
3	3	DIGIT THREE
4	4	DIGIT FOUR
5	5	DIGIT FIVE
6	6	DIGIT SIX
7	7	DIGIT SEVEN
8	8	DIGIT EIGHT
9	9	DIGIT NINE
:	%3A	COLON
;	%3B	SEMICOLON
<	%3C	LESS-THAN SIGN
=	%3D	EQUALS SIGN
>	%3E	GREATER-THAN SIGN
?	%3F	QUESTION MARK
¡	%C2%A1	INVERTED EXCLAMATION MARK
A	A	LATIN CAPITAL LETTER A
B	B	LATIN CAPITAL LETTER B
C	C	LATIN CAPITAL LETTER C
D	D	LATIN CAPITAL LETTER D
E	E	LATIN CAPITAL LETTER E
F	F	LATIN CAPITAL LETTER F
G	G	LATIN CAPITAL LETTER G
H	H	LATIN CAPITAL LETTER H
I	I	LATIN CAPITAL LETTER I
J	J	LATIN CAPITAL LETTER J
K	K	LATIN CAPITAL LETTER K
L	L	LATIN CAPITAL LETTER L
M	M	LATIN CAPITAL LETTER M
N	N	LATIN CAPITAL LETTER N
O	O	LATIN CAPITAL LETTER O
P	P	LATIN CAPITAL LETTER P
Q	Q	LATIN CAPITAL LETTER Q
R	R	LATIN CAPITAL LETTER R
S	S	LATIN CAPITAL LETTER S
T	T	LATIN CAPITAL LETTER T
U	U	LATIN CAPITAL LETTER U
V	V	LATIN CAPITAL LETTER V
W	W	LATIN CAPITAL LETTER W
X	X	LATIN CAPITAL LETTER X
Y	Y	LATIN CAPITAL LETTER Y
Z	Z	LATIN CAPITAL LETTER Z
Ä	%C3%84	LATIN CAPITAL LETTER A WITH DIAERESIS
Ö	%C3%96	LATIN CAPITAL LETTER O WITH DIAERESIS
Ñ	%C3%91	LATIN CAPITAL LETTER N WITH TILDE
Ü	%C3%9C	LATIN CAPITAL LETTER U WITH DIAERESIS
§	%C2%A7	SECTION SIGN
¿	%C2%BF	INVERTED QUESTION MARK
a	a	LATIN SMALL LETTER A
b	b	LATIN SMALL LETTER B
c	c	LATIN SMALL LETTER C
d	d	LATIN SMALL LETTER D
e	e	LATIN SMALL LETTER E
f	f	LATIN SMALL LETTER F
g	g	LATIN SMALL LETTER G
h	h	LATIN SMALL LETTER H
i	i	LATIN SMALL LETTER I
j	j	LATIN SMALL LETTER J
k	k	LATIN SMALL LETTER K
l	l	LATIN SMALL LETTER L
m	m	LATIN SMALL LETTER M
n	n	LATIN SMALL LETTER N
o	o	LATIN SMALL LETTER O
p	p	LATIN SMALL LETTER P
q	q	LATIN SMALL LETTER Q
r	r	LATIN SMALL LETTER R
s	s	LATIN SMALL LETTER S
t	t	LATIN SMALL LETTER T
u	u	LATIN SMALL LETTER U
v	v	LATIN SMALL LETTER V
w	w	LATIN SMALL LETTER W
x	x	LATIN SMALL LETTER X
y	y	LATIN SMALL LETTER Y
z	z	LATIN SMALL LETTER Z
ä	%C3%A4	LATIN SMALL LETTER A WITH DIAERESIS
ö	%C3%B6	LATIN SMALL LETTER O WITH DIAERESIS
ñ	%C3%B1	LATIN SMALL LETTER N WITH TILDE
ü	%C3%BC	LATIN SMALL LETTER U WITH DIAERESIS
à	%C3%A0	LATIN SMALL LETTER A WITH GRAVE

Appendix C: Dobbelttegn

I GSM-protokollen er hvert tegn 7 bit, således at der er plads til 127 tegn. Da der, siden standarden blev defineret, er kommet nye til, har man måttet lade disse nye tegn fylde to tegn for at få plads. Derfor kan man, når man sender en sms, der egentlig kun et 158 tegn lang, stadig komme over de 160 tegn og dele sms'en i to, ved at benytte tre af nedenstående tegn, således at den samlede mængde tegn, der skal sendes, er 161.

Tegn	URL-kodet værdi	Engelsk beskrivelse
[	%5B	LEFT SQUARE BRACKET
\	%5C	REVERSE SOLIDUS (BACKSLASH)
]	%5D	RIGHT SQUARE BRACKET
^	%5E	CIRCUMFLEX ACCENT
{	%7B	LEFT CURLY BRACKET
\|	%7C	VERTICAL BAR
}	%7D	RIGHT CURLY BRACKET
~	%7E	TILDE
€	%E2%82%AC	EURO SIGN