HTTP(S) GATEWAY

Dette dokument beskriver metoder og brugen af afsendelse af SMS gennem HTTP POST/GET.

Vores service er baseret på et script, der lytter efter de forskellige request parametre, der definere hvilken besked der skal afsendes.
Parametre navnene er ligefrem, f.eks. hedder modtager parametret "to", og afsender parametret "from".

Systemet sørger automatisk for at dele beskeder der er længere end 160 tegn, modtageren vil stadig se beskeden som en besked, såfremt modtageres telefon understøtter dette.
Såfremt en besked er længere end 160 tegn, vil hver del den deles i blive afregnet.

SMS Afsendelse er baseret på både GET og POST URL forespørgsler.

Forespørgslen skal sendes til en af følgende adresser:



Sidst 2 nævnte er SSL Krypteret.

De tilsendte variabler, analyseres som enten GET eller POST parametre.
Alle parametre skal URL Encodes, i henhold til RFC 1738, med undtagelse af at + betragtes som et mellemrum([SPACE]).

En forespørgsel vil se således ud:



Dette vil sende en besked til +4512345678, med afsender "SMS HTTP GW", og med teksten "hello world".

Når du afsender en SMS vil der være en HTTP Header med navnet X-Status der enten vil være "success" eller "failure", afhængig af resultatet af forespørgslen.
Det anbefales at kontrollere resultatet af din forespørgsel med denne header.

Indholdet af dokumentet er afhængig af den valgte "resulttype".

urlencoded:

Indholdet er en urlencoding af 2 variabler, status og result.

status=STATUS&result=RESULT

status parametret er enten "success" eller "failure".
Afhængig af resultatet af forespørgslen, vil parametret result være en beskrivelse af resultatet.
Er status sat til "success" vil der være et ekstra parametre kaldet msgid. Dette indeholder det interne ID på beskeden fra CoolSMS.


xml:

For XML dokumentet findes der en DTD på http://sms.coolsmsc.dk/dtd/smsc.dtd


Hverken xml eller urlencoded:

Indholdet af resultatet vil være en streng der beskriver resultatet.

Special beskeder er afhængig af den underlæggende gateway der benyttes.

Såfremt du har problemer med at benytte en speciel type beskeder, er du yderst velkommen til at kontakte os, så vi kan hjælpe dig videre.

Med binære beskeder kan du afsende special beskeder, f.eks. Nokia vcard og lignende.

For at afsende binære beskeder kan der benyttes en række ekstra parametre:

format		I forbindelse med binære beskeder skal denne sættes til værdien BINARY.
port		Porten der skal sendes til på telefonen. Porten defineres som en decimal værdi, så hvis du er vant til at benttte porte med HEX værdier, som 158A skal disse konverteres.
message		Beskden der ønskes sendt som. Værdien skal være en binær streng.

Med klasser kan du definere vigtigheden af beskeden, samt hvor den skal gemmes.

class

Værdien af den klasse der skal benyttes. Ønsker du ikke at benytte klasser skal du undlade denne parameter.

Der er 4 forskellige klasser der kan benyttes:

0		Beskeden vises direkte på telefonen, og gemmes ikke i telefonens hukommelse, med mindre brugeren vælger dette. Denne besked type kaldes ofte for flash beskeder.
1		Denne besked klasse indikerer at beskeden skal gemmes i telefonens hukommelse. Enten på telefonen eller SIM Kortet afhængig af tilgængeligheden.
2		Denne klasse indikerer at beskeden indeholder SIM kort data.
3		Denne klasse indikerer at beskeden skal sendes til en ekstern enhed, benyttes til Terminal udstyr.

Medmindre du ved hvordan du benytter klasserne bør du undlade at benytte dette.

I en almindelig SMS er der plads til 140 Octest, for at udvide dette har man udviklet 7 bit alfabetet, der gør at man kan sende 160 tegn på 140 Octets.

Dette begrænser dog udvalget af tegn. Har man derfor brug for at sende mere eksotiske tegn, kan man benytte sig af UNICODE, dette bruges f.eks. i forbindelse med Russiske, Arabiske, Kinesiske og Japanske tegn.

Dette begrænser dog beskedens længde til 70 tegn pr. besked.

For at sende UNICODE beskeder skal du benytte parameteret type og sætte det til værdien UNICODE.

Du kan også benytte charset parametret som tidligere beskrevet for at sende med et andet tegnsæt.

Hvis du ønsker at sende i hex skal du sætte % foran alle hexadecimal værdier.

Et eksempel på en arabisk besked:

Wappush beskeder, er beskeder hvor i der bliver sendt et link, så kan åbnes direkte i telefonens browser, når beskeden er modtaget af telefonen.

For at sende en wappush besked kan du benytte følgende parametre:

format	Påkrævet	Ved wappush beskeder skal værdien sættes til WAPPUSH
pushurl	Påkrævet	URL'en du ønsker der skal sendes til Mobil Terminalen
message	Påkrævet	Beskrivelse af linket som vil blive vist på Mobil Terminalen
pushexpire		Udløbsdatoen på linket, angivet som et UNIX Timestamp. Som standard sættes dette til nuværende dato + 7 dage

For at sende en wappush besked med link til http://www.coolbiz.dk med teksten CoolBIZ, gør da følgende:

Mms beskeder, er en præsentation med en række vedhæftede filer der sendes til telefonen.

For at sende en MMS besked skal du benytte følgende parametre:

format	Påkrævet	Ved MMS beskeder skal værdien sættes til MMS
message	Påkrævet	Indeholder emnet på den MMS du sender.
attachment[]	Påkrævet	Dette parameter kan forekomme flere gange, og indeholder en URL til de filer du vil have sendt med beskeden. Hvis du ønsker at sende en præsentation skal det første attachment[] være linket til en SMIL fil, der ender på .smil

For at sende en MMS besked med et billede, og emnet CoolBIZ, gør da følgende:

Hvis du ønsker at overtaksere en besked, og har adgang til 2-Vejs kommunikation, kan du udsende takserings beskeder via gateway'en.

Når du overtaksere en besked skal du sætte 2 parametre:

from	Påkrævet	Skal sættes til applikationskoden du overtaksere fra.
push_price	Påkrævet	Skal sættes til værdien på takseringen i Øre.

Derudover skal afsenderen altid være den applikationskode der skal takseres på.

I nedenstående eksempel er der vist hvordan man overtaksering på applikationskoden 1272, med 1 Kr. og 50 øre.

For at følge leveringen af SMS Beskeder, samt eventuelt, se hvilke beskeder der ikke bliver leveret, kan du anmode om at få tilsendt status rapporter.

Status rapporterne sendes via et HTTP GET kald, til en URL du angiver.

Det anbefales at dine systemer er online 24x7 da fejlede status rapporter ikke vil blive forsøgt igen.

For at modtage status rapporter skal du benytte følgende parametre:

status	Påkrævet	For at modtage status rapporter skal værdien sættes til on
statusurl	Påkrævet	URL'en du ønsker at modtage status rapporter på
returndata		En streng på 255 octets, som kunden kan bruge som deres eget ID

Hvis resulttype ikke er angivet til en værdi, vil retur svaret fra gateway'en være et unikt ID, i stedet for en beskrivende tekst.
For andre værdier af resulttype henvises til afsnittet "HTTP Svar"

Når Status rapporten sendes til kunden vil den have følgende parametret specificeret:

msgid	Det unikke besked ID på beskeden
receivetime	UNIX Timestamp for status rapporten
to	Modtageren af beskeden der kommer en status rapport for
status	Status på beskeden. Statusen kan være en af følgende værdier. received - Beskeden er modtaget rejected - Beskeden er afvist af SMSC'en, af forskellige årsager (Se statuscode for forklaring) buffered - Beskeden er forsøgt leveret, vil blive forsøgt igen senere expired - Gyldighedsperioden er udløbet, beskeden har ikke kunnet blive leveret
reason	Beskrivelsen af status på beskeden
statuscode	Fejlkoden på den afviste besked, jævnfør nedenstående fejlkoder
returndata	Hvis returndata er specificeret, ved afsendelse af SMS, vil denne være udfyldt med den af kunden angivne værdi
logdate	Dato for afsendelse af beskeden, i formatet YYYY_mm_dd