KUULALAAKERI
1(6)
LUOTTAMUKSELLINEN
Messto HTTP API
Messto HTTP API on sovelluskehittäjiä varten kehitetty helppo tapa toteuttaa tekstiviesti- ja
multimediaviestisovelluksia. Rajapinnan avulla voidaan esimerkiksi integroida tekstiviestinlähetys
olemassaoleviin sovelluksiin ja palveluihin.
Messto Basicin avulla voidaan lähettää tekstiviestejä kaikkiin suomalaisiin matkapuhelinliittymiin.
Messto Pron avulla voidaan lisäksi vastaanottaa teksti- ja multimediaviestejä kaikista suomalaisista
matkapuhelinliittymistä. Messto Pro sisältää myös Messto Basicin ominaisuudet.
Sisältö
Lähetys..................................................................................................................................................... 2 Palvelimen URL................................................................................................................................. 2 Pakolliset muuttujat tekstiviesteille (SMS)......................................................................................... 2 Valinnaiset muuttujat tekstiviesteille (SMS)....................................................................................... 2 Muuttujat multimediaviesteille (MMS)................................................................................................ 3 Maksulliset push-viestit (SMS) .......................................................................................................... 3 Esimerkki (SMS ja MMS) .................................................................................................................. 3 Vastaanotto .............................................................................................................................................. 4 Palvelun kytkeminen ......................................................................................................................... 4 Palvelun asetukset ............................................................................................................................ 4 Sovellusten luominen ........................................................................................................................ 4 Sovellukselle välitettävät muuttujat ................................................................................................... 4 Esimerkki QLA MS text –sovelluksesta ............................................................................................. 5 Esimerkki QLA MS extended –sovelluksesta.................................................................................... 6 Virhelogi ............................................................................................................................................ 6 30.12.2010
Kuulalaakeri Oy
PL 271
20101 TURKU
Puh: (02) 334 3000
Faksi: (02) 334 3100
Kotisivu: www.kuulalaakeri.fi
Y-tunnus: 1545919-9
Kotipaikka: Turku
KUULALAAKERI
2(6)
LUOTTAMUKSELLINEN
Lähetys
Palvelimen URL
Salaamattomana: http://www.messto.com/send
SSL-salauksella: https://www.messto.com/send
Tekstiviestin (SMS) lähetyksessä voidaan käyttää HTTP POST (suositus) tai HTTP GET-muotoa.
Multimediaviestin (MMS) lähetyksessä pitää käyttää HTTP POST –muotoa.
Pakolliset muuttujat tekstiviesteille (SMS)
Parametri
sms_username
sms_password
Selitys
Messto HTTP API-palvelun käyttäjätunnus.
Messto HTTP API-palvelun salasana.
Vastaanottajan matkapuhelinnumero,
kansainvälisessä (+358…) muodossa.
Lähetettävä tekstiviesti ISO-8859-1 merkistöllä.
sms_dest
sms_text
Jos haluat lähettää moniosaisia tekstiviestejä, voit antaa sms_text-kenttään yli 160-merkkiä pitkän
viestin. Messto huolehtii viestin jakamisesta osiin.
Valinnaiset muuttujat tekstiviesteille (SMS)
Parametri
Selitys
Voidaan käyttää sms_text:n sijaan lähetettäessä
binääriviestejä.
Voidaan käyttää sms_text:n sijaan lähetettäessä
unicode-viestejä.
Viestiin liitettävä User Data Header.
Viestin lähettäjänä näkyvä teksti. Sallitu teksti on
hyväksyttävä ensin Kuulalaakeri Oy:llä.
URL jota kutsutaan, kun viestille on saatu
toimituskuittaus. Pyyntöön lisätään onnistuneessa
toimituksessa arvo &receipt_value=ack tai
epäonnistuneessa &receipt_value=nack.
Viestin viivästetty lähetys, muodossa
yyyymmddhhmm (UTC ajassa)
Viestin viivästetty lähetys sekunteina nykyisestä
hetkestä.
Viestin viimeinen voimassaoloaika, muodossa
yyyymmddhhmm.
Viestin voimassaoloaika sekunteina nykyisestä
hetkestä.
Protocol identifier (GSM 03.40).
Viestin luokka (GSM 03.40).
Viestin hintaluokka, katso kohta maksulliset pushviestit.
Odotetaan vastausviestiä ilman avainsanaa.
Muuttujan arvoksi annetaan kaksisuuntaisen
palvelun avainsana ilman yrityskohtaista alkuosaa
(esim. QLA TILAUS -> TILAUS). 1
Vaustausviestin odotusaika sekunteina (max 86400
= 1 vuorokausi, oletus 86400)
sms_binary
sms_unicode
sms_udh
sms_source
sms_receipt
sms_delayed_abs
sms_delayed_rel
sms_valid_abs
sms_valid_rel
sms_pid
sms_class
sms_tariff
sms_magicmapping
sms_magicmapping_ttl
Binääriviesti ja UDH tulee enkoodata 8-bitin ryhmissä, esimerkiksi ‘XYZ’ on enkoodattuna 58595a.
Unicode-viestit tulee enkoodata 16-bitin ryhmissä, esimerkiksi ‘XYZ’ on enkoodattuna 00580059005a.
30.12.2010
Kuulalaakeri Oy
PL 271
20101 TURKU
Puh: (02) 334 3000
Faksi: (02) 334 3100
Kotisivu: www.kuulalaakeri.fi
Y-tunnus: 1545919-9
Kotipaikka: Turku
KUULALAAKERI
3(6)
LUOTTAMUKSELLINEN
Muuttujat multimediaviesteille (MMS)
Parametri
username
password
Selitys
Messto HTTP API-palvelun käyttäjätunnus.
Messto HTTP API-palvelun salasana.
Viestin lähettäjä (ei pakollinen). Hyväksyttävä ensin
Kuulalaakeri Oy:llä.
Vastaanottajan matkapuhelinnumero,
kansainvälisessä (+358…) muodossa.
Viestin otsikko UTF-8 merkistöllä.
Liitetiedoston nimi (X=1-99).
Liitetiedoston mime-tyyppi (X=1-99).
Liitetiedoston sisältö (X=1-99).
from
to
subject
content_nameX
content_typeX
content_bodyX
Multimediaviestit koostuvat yhdestä tai useammasta osasta (teknisesti ottaen liitetiedostoja),
esimerkiksi tekstistä (.txt text/plain), kuvista (.jpg image/jpeg tai .gif image/gif) ja smil-esityksestä (.smil
application/smil). Suositeltava merkistökoodaus tekstiliitteille on UTF-8 (text/plain; charset=UTF-8).
Sisältö enkoodataan asciiheksaksi 8-bitin ryhmissä, esimerkiksi ‘Messto’ on enkoodattuna
4d657373746f.
Maksulliset push-viestit (SMS)
Push-viestien tilaajan tulee liittyä Messton push-ryhmään erikseen Kuulalaakeri Oy:n kanssa
sovittavalla avainsanalla. Messto poistaa tilaajat push-ryhmästä automaattisesti lopetusviestin tullessa
(esim. 17252: PUSH SULJE tai 17252: STOP). Avainsanaa käytetään sms_tariff –parametrinä
lähetettäessä maksullisia push-viestejä.
Ennen lähetystä voi Messton osoitekirjasta kysyä aktiiviset push-tilaajat http-kyselyllä:
https://user:[email protected]/xtras/abhelper.phtml?search[]=&limit[group_and]=17252+push
Push-ryhmän nimi on muotoa palvelunumero + välilyönti + avainsana, ylläolevassa esimerkissä se on
“17252 push”.
Jos tilaaja ei kuulu push-ryhmään lähetys ei onnistu ja http-kysely palauttaa virhetekstin.
Esimerkki (SMS ja MMS)
Lähetetään alla mainittu HTTP-pyyntö palvelimelle.
Tekstiviesti (SMS):
https://www.messto.com/send?sms_username=kalle&sms_password= kehveli&sms_dest=%2b358401
234567&sms_text=Terveisi%e4+Messtosta
Multimediaviesti (MMS):
https://www.messto.com/send?username=kalle&password=kehveli
&to=%2b358401234567&subject=Otsikko&content_name1=text.txt
&content_type1=text%2fplain%3b+charset%3dUTF-8
&content_body1=5465727665697369c3a4204d657373746f737461
Palvelin vastaa seuraavasti (Content-Type: text/plain, rivinvaihtona ‘\n’):
Onnistunut lähetys:
rivi 1: OK
rivi 2: <lisätietoa lähetyksestä tai rivi 2 puuttuu kokonaan>
Epäonnistunut lähetys (esim. virheellinen tunnus tai virheelliset parametrit):
rivi 1: ERROR
rivi 2: <virheteksti>
30.12.2010
Kuulalaakeri Oy
PL 271
20101 TURKU
Puh: (02) 334 3000
Faksi: (02) 334 3100
Kotisivu: www.kuulalaakeri.fi
Y-tunnus: 1545919-9
Kotipaikka: Turku
KUULALAAKERI
4(6)
LUOTTAMUKSELLINEN
Vastaanotto
Messton HTTP-lisäpalvelulla voit ohjata saapuneita teksti- (sms) ja multimediaviestejä (mms) omalle
sovelluksellesi. Sovellus voi lähettää vastauksen viestiin.
Palvelun kytkeminen
Luo tarvittaessa uusi avainsana, jota haluat käyttää HTTPlisäpalvelun kanssa.
Valitse Kaksisuuntaiset Palvelut –valikosta avainsana, johon
saapuneet viestit haluat ohjata HTTP-lisäsovellukselle. Valitse
Saapunut viesti -pudotusvalikosta vaihtoehto “Ohjataan
lisäpalvelulle:HTTP”.
Aseta muutokset voimaan klikkaamalla Muuta-painiketta.
Palvelun asetukset
Palveluun ohjatut avainsanat näkyvät Lisäpalvelut-valikon alla.
Valitse Lisäpalvelut-valikon alta avainsana, jonka asetuksia
haluat muuttaa.
Määrittele avainsanalle sovelluksesi URL, jota kutsutaan viestin
saapuessa palveluun. Tuettu protokolla on http://.
Aseta rajapinnan tyypiksi “QLA MS text” (suositus) tai “QLA MS
extended”.
Aseta muutokset voimaan klikkaamalla Muuta-painiketta.
Sovellusten luominen
Sovelluksissa on käytettävä QLA MS text tai QLA MS extended rajapintaa.
Rajapinta vaikuttaa siihen miten sovelluksen pitää lähettää
vastausviesti tilaajalle. Käytettäessä QLA MS text –rajapintaa kaikki
sovelluksen palauttama teksti 160 merkkiin saakka välitetään tilaajalle
tekstiviestinä. QLA MS text -rajapinnalla ei voi lähettää unicode- tai
binääriviestejä.
QLA MS extended -rajapintaa käytettessä sovelluksen pitää palauttaa riveittäin avain=arvo -pareja,
joiden perusteella vastausviesti lähetetään. QLA MS extended -rajapinnalla voidaan lähettää myös
binääriviestejä (esim. soittoääniä ja logoja) sekä unicode-merkistöllä olevia viestejä.
Sovellukselle välitettävät muuttujat
Tekstiviesteille (sms) sovellus saa Messtolta seuraavat muuttujat:
Parametri
Selitys
sms_source
Tilaajan numero kansainvälisessä muodossa.
sms_dest
Numero johon viesti on lähetty.
sms_command
Viestin avainsana.
sms_params
Viestin avainsanan jälkeinen osa.
sms_text
Tekstiviesti alkuperäisessä muodossa.
Messto koostaa automaattisesti yli 160-merkkiset moniosaiset tekstiviestit yhdeksti pitkäksi viestiksi.
30.12.2010
Kuulalaakeri Oy
PL 271
20101 TURKU
Puh: (02) 334 3000
Faksi: (02) 334 3100
Kotisivu: www.kuulalaakeri.fi
Y-tunnus: 1545919-9
Kotipaikka: Turku
KUULALAAKERI
5(6)
LUOTTAMUKSELLINEN
Multimediaviestit (mms) koostuvat yhdestä tai usemmasta osasta, esim. tekstistä, kuvista, äänistä,
videoista ja smil-esityksistä. Sovellus saa Messtolta seuraavat muuttujat:
Parametri
From
to
subject
parts
content_typeX
content_nameX
content_bodyX
Selitys
Tilaajan numero kansainvälisessä muodossa.
Numero johon viesti on lähetty.
Viestin aihe.
Osien lukumäärä.
Mime-tyyppi (X = 1 ... parts).
Tiedostonimi (X = 1 ... parts).
Binääridata heksamuodossa (X = 1 ... parts)
Sovelluksen palauttamat muuttujat
Sovelluksen Messtolle antamat avain=arvo –parit käytetettäessä QLA MS extended -rajapintaa:
Parametri
sms_text
Selitys
Tekstiviesti ISO 8859-1 merkistöllä.
Voidaan käyttää sms_text:n sijasta lähetettäessä
binääriviestejä.
Voidaan käyttää sms_text:n sijasta lähetettäessä
Unicode-viestejä
Viestiin liitettävä User Data Header.
URL jota kutsutaan kun viestille on saatu
toimituskuittaus. URL:ään loppuun onnistuneessa
toimituksessa &receipt_value=ack ja
epäonnistuneessa &receipt_value=nack.
Viestin viivästetty lähetys, muodossa
yyyymmddhhmm.
Viestin viivästetty lähetys sekunteina nykyisestä
hetkestä.
Viestin viimeinen voimassaoloaika, muodossa
yyyymmddhhmm.
Viestin voimassaoloaika sekunteina nykyisestä
hetkestä.
Protocol identifier (GSM 03.40).
Viestin luokka (GSM 03.40).
Viestin hinta (esim. 0.50e tai 0.00e). Tarkista
ajantasaiset tariffiluokat Kuulalakeri Oy:ltä ennen
käyttöönottoa.
sms_binary
sms_unicode
sms_udh
sms_receipt
sms_delayed_abs
sms_delayed_rel
sms_valid_abs
sms_valid_rel
sms_pid
sms_class
sms_tariff
Binääriviesti ja UDH tulee esittää heksana 8 bitin ryhmissä, esimerkiksi ‘QLA’ on enkoodattuna
514c41. Unicode-viesti tulee esittää heksana 16 bitin ryhmissä, esimerkiksi ‘QLA’ on enkoodattuna
0051004c0041.
Esimerkki QLA MS text –sovelluksesta
Sovellus lähettää vastausviestin “Time: 14:42, Your GSM-number is +358408421895. Bye!”.
example_text.php:
<?
// PHP Example of QLA MS / Messto HTTP API text)
// QLA MS accepts only text/plain, not needed for Messto HTTP API
header("Content-Type: text/plain");
// Returns fancy message to subscriber
printf("Time: %s. Your GSM-number is %s. Bye!",
strftime("%H:%M"),
$sms_source);
?>
30.12.2010
Kuulalaakeri Oy
PL 271
20101 TURKU
Puh: (02) 334 3000
Faksi: (02) 334 3100
Kotisivu: www.kuulalaakeri.fi
Y-tunnus: 1545919-9
Kotipaikka: Turku
KUULALAAKERI
6(6)
LUOTTAMUKSELLINEN
Esimerkki QLA MS extended –sovelluksesta
Sovellus lähettää vastausviestinä soittoäänen.
example_extended.php:
<?
// PHP Example of QLA MS / Messto HTTP API (extended)
// QLA MS accepts only text/plain, not needed for Messto HTTP API
header("Content-Type: text/plain");
$udh = "06050415810000";
$binary = "024a3a59c995ada5c994041ea4c956a0d512692839449a492a1a4a89d126927
12a39449a4176134a8ad125525d2a354495413620e2544e88345728e24e24aa4aa4d24d25a4e8934
834938c51ca24d20bb09a5456892a92a82ec51aa24aa09b10712a2744932b944d2552692000";
print "sms_dest=$sms_source\n";
print "sms_udh=$sms_udh\n";
print "sms_binary=$sms_binary\n";
?>
Virhelogi
Valitse Lisäpalvelut –valikosta lisäpalvelu HTTP.
Jos palvelun logissa on epäonnistuneita HTTP-pyyntöjä tai muita virheita, ne listataan virhelogissa.
Virhelogissa jokainen virhe näkyy omana rivinään, joka alkaa päivämäärällä, jota seuraa varsinainen
virhekoodi ja viimeisenä sulkujen sisällä palvelunumero ja avainsana. Uusin virhetilanne näkyy
viimeisenä listassa.
Voit tyhjentää virhelogin painamalla tyhjennä-linkkiä.
30.12.2010
Kuulalaakeri Oy
PL 271
20101 TURKU
Puh: (02) 334 3000
Faksi: (02) 334 3100
Kotisivu: www.kuulalaakeri.fi
Y-tunnus: 1545919-9
Kotipaikka: Turku