Aanleveren van te verzenden sms berichten aan SMS Via

Transcriptie

1 Aanleveren van te verzenden sms berichten aan SMS Via 1. Inleiding Er zijn drie methoden van aanlevering van sms berichten mogelijk: via een HTTP request; dit kunt u gebruiken voor één sms bericht tegelijk via een XML request; hierin kunt u meerdere sms berichten tegelijk laten versturen via ; hiervoor zijn twee verschillende formats mogelijk Voordat u deze requests gaat verzenden dient het één en ander geregeld te zijn: U dient het IP-adres van de computer, waar het request vandaan komt op te nemen in de lijst IP-adressen op de SMS Via website. Er wordt door SMS Via altijd gecontroleerd of uw requests ook van één van de door u opgegeven IP-adressen komen. U dient een test sms te verzenden vanaf de SMS Via website. Hierdoor krijgt u een licentie sleutel toegewezen. Deze is te vinden onder Diensten. Voor het versturen van requests heeft u verder nog uw klantnummer (client-id) nodig. Dit nummer is te vinden onder Uw gegevens. Verder is het belangrijk dat een request, dat door ons geaccepteerd is, (nog) niet gegarandeerd bij de ontvanger is afgeleverd. Het afleveren van het request bij de ontvanger kan op een later moment plaatsvinden. Aan u wordt dit teruggemeld door middel van de afleverrapportage (zie paragraaf 5). Aanleveren van te verzenden SMS V1.3 1

2 2. HTTP request Het HTTP request betreft een POST met de volgende parameters: client_id Het klantnummer, dat onder Uw gegevens te vinden is license_key De licentiesleutel, die aan u is toegewezen msisdn Het telefoonnummer van de ontvanger message De te verzenden boodschap Het telefoonnummer van de ontvanger moet een geldig telefoonnummer zijn, van het volgende format (voorbeeld) Hierbij geldt het volgende: 31 is het landnummer van Nederland; uiteraard is een ander landnummer ook mogelijk 623 is het netnummer of het begin van het 06-nummer (zonder 0 dus) is het toestelnummer Dit request stuurt u naar de URL Op de volgende wijze kan met CURL een POST-request worden doorgegeven (alles op 1 regel): curl --data "client_id= &license_key= &msisdn= &message= " Terugkoppeling U krijgt van SMS Via het antwoord OK, wanneer het request goed is ontvangen en zal worden verzonden of het antwoord ERROR <nummer>, wanneer uw request een fout bevat. Wij gebruiken de volgende foutnummers: 001 Msisdn heeft fout format 002 Sender heeft fout format 003 Client-id onbekend 004 License-key onbekend 005 Message te lang (de maximale lengte van een sms is 160 tekens) 006 Deze functie is voor u geblokkeerd. Neem contact op met de SMS Via helpdesk 007 IP Adres is niet bekend 008 Fout in configuratie. Neem contact op met de SMS Via helpdesk 009 Saldo te laag Aanleveren van te verzenden SMS V1.3 2

3 Wanneer u geen resultaat terug krijgt zal het bericht vermoedelijk niet geaccepteerd zijn. Neem dan contact op met de SMS Via helpdesk om te achterhalen welk probleem is opgetreden. In de bijlagen vind u een scripting-voorbeeld hoe dit request te sturen vanuit PHP. Aanleveren van te verzenden SMS V1.3 3

4 3. XML request In een XML request kunnen meerdere sms berichten tegelijk worden opgenomen. De XML heeft het volgende format: <?xml version="1.0" encoding="iso "?> <smss_list> <sms_list> <client_id></client_id> <license_key></license_key> <batch_name></batch_name> <title></title> <via_type></via_type> <sms> <msisdn></msisdn> <name></name> </sms> <sms> <msisdn></msisdn> <name></name></sms> </sms> </sms_list> </smss_list> Er kunnen meerdere berichten in de XML opgenomen worden ( <sms_list> ) en bij een bericht meerdere telefoonnummers waarnaar een sms verzonden moet worden ( <sms> ). Indien gewenst kan het <smss_list> niveau worden weggelaten, wanneer het om slechts één bericht met bijbehorende telefoonnummer(s) gaat. Hierbij geldt tevens het volgende: client-id Het klantnummer, dat onder Uw gegevens te vinden is license-key De licentiesleutel, die aan u is toegewezen batch-name Uw identificatie voor deze batch via-type Het type bericht; dit is voor latere uitbreidingen van de SMS Via diensten en hoeft nog niet te worden meegegeven title De naam van de afzender message De te verzenden boodschap msisdn Het telefoonnummer van de ontvanger (zie paragraaf 2 voor het format) name De naam van de ontvanger Aanleveren van te verzenden SMS V1.3 4

5 De te verzenden boodschap kan één boodschap voor alle nummers zijn, buiten de <sms></sms> tags of een boodschap per nummer, binnen de <sms></sms> tags. Wanneer de boodschap per nummer niet wordt opgenomen, wordt de boodschap buiten de <sms></sms> tags gekozen. Dit request stuurt u naar de URL U krijgt van SMS Via een antwoord in XML-vorm, waarbij voor het bericht als geheel en/of per sms een resultaat wordt opgegeven, in het volgende format: <?xml version="1.0" encoding="iso "?> <smss_result_list> <sms_result_list> <client_id></client_id> <license_key></license_key> <batch_name></batch_name> <title></title> <via_type></via_type> <general_result></general_result> <sms> <msisdn></msisdn> <name></name> <result></result> </sms> <sms> <msisdn></msisdn> <name></name> <result></result> </sms> </sms_result_list> </smss_result_list> Er wordt dus per <sms_list> een algemeen resultaat teruggegeven ( <general_result> ) en per telefoonnummer een resultaat ( <result> ); In de bijlagen vind u een scripting-voorbeeld hoe dit request te sturen vanuit PHP. Aanleveren van te verzenden SMS V1.3 5

6 4. Sms kan via in twee verschillende formats worden aangeleverd. Hieronder zijn beide formats beschreven. Het eenvoudige format (paragraaf 4.1) is alleen bruikbaar voor het versturen van één sms naar één nummer tegelijk. In het XML format (paragraaf 4.2) kunnen meerdere sms berichten naar verschillende nummers worden opgenomen eenvoudig format Met het eenvoudige format kan slechts één sms tegelijkertijd worden verzonden. SMS Via verwacht de volgende informatie in een Van: Geef in dit veld de afzender van de sms aan. De tekst voor mag maximaal 11 karakters zijn Aan: Geef in dit veld het telefoonnummer aan van de ontvanger van het sms bericht, met als Onderwerp: Plaats hier de tekst van de sms Tekst: Plaats hierin je client-id en license-key, gescheiden door een puntkomma (;) Dat ziet er bijvoorbeeld zo uit: Van: uwnaam@uwdomein.nl Aan: @sms-via- .nl Onderwerp: Testbericht van mij Tekst: 1111;AAAAA-BBBBB-CCCCC-DDDDD-EEEEE De sms wordt dan verstuurd aan het nummer met als afzender Uwnaam. Let op dat de tekst van de niet als HTML is opgemaakt, want dat wordt door de SMS Via server niet geaccepteerd! Wanneer er geen correcte informatie wordt doorgegeven in de , wordt de sms niet verstuurd. Neem bij vragen contact op met onze support afdeling: techniek@sms-via.nl. Aanleveren van te verzenden SMS V1.3 6

7 4.2. XML format Met het XML format kunnen meerdere sms berichten tegelijkertijd worden opgenomen. De XML heeft hetzelfde format als bij het XML request (zie paragraaf 3). SMS Via verwacht de volgende informatie in deze Van: Aan: Deze informatie wordt niet gebruikt Geef in dit veld het telefoonnummer aan van de ontvanger van het sms bericht, met als Let op, het telefoonnummer dient ook in de XML opgenomen te zijn. Onderwerp: Deze informatie wordt niet gebruikt Tekst: Plaats hier de XML Het is ook mogelijk om de XML door te geven in een bijlage (attachment) bij de . Let op dat de tekst van de niet als HTML mag worden opgemaakt, want dit wordt door de SMS Via server niet geaccepteerd! Wanneer er geen correcte informatie wordt doorgegeven in de , wordt de sms niet verstuurd. Neem bij vragen contact op met onze support afdeling: Aanleveren van te verzenden SMS V1.3 7

8 5. Afleverrapportage Om er zeker van te zijn dat een bericht ook daadwerkelijk is afgeleverd bij de beoogde ontvanger kan een afleverrapportage worden ingesteld. Deze rapportage wordt bezorgd op een door u opgegeven URL als een HTTP POST request. De rapportage omvat de volgende gegevens: msisdn Het telefoonnummer van de ontvanger batch De identificatie van het bericht. Dit is uw batchname of de datum/tijd waarop is aangeleverd status De status van het bericht error Een eventuele fout situatie, die is opgetreden Wij verwachten op dit POST request het antwoord OK. Wanneer we dit niet ontvangen, wordt er geregistreerd dat de afleverrapportage niet is aangekomen. De rapportage wordt dan niet nogmaals verzonden. De status kan de volgende waarden aannemen: Het bericht is afgeleverd Het bericht is nog niet afgeleverd Er is een fout opgetreden bij de aflevering van het bericht Wanneer er een foutsituatie is opgetreden, wordt één van de volgende waarden gebruikt: 10 aflevering is niet gelukt 11 aflevering is niet toegestaan of niet mogelijk 12 bestemming is uitgeschakeld 13 bestemming reageert niet 14 er is een fout opgetreden bij de bestemming 16 het geheugen is vol bij de bestemming 17 de bestemming is onbekend 18 aflevering is niet gelukt binnen de gestelde periode 19 het bericht kon niet worden afgeleverd 21 afleverperiode verstreken 22 onbekende fout Dit zijn foutcodes die SMS Via doorgegeven krijgt van de verschillende providers. Mocht u hierover vragen hebben, neem dan contact op met de SMS Via helpdesk. Aanleveren van te verzenden SMS V1.3 8

9 6. BIJLAGE 1: Voorbeeld PHP-scripting HTTP-request <?php function rawurlencode_callback($value, $key) { return "$key=". rawurlencode($value); } function send_sms($msisdn, $message, $license_key, $client_id) { $variables = array( 'msisdn'=>urlencode($msisdn), 'message'=>urlencode($message), 'license_key'=>urlencode($license_key), 'client_id'=>urlencode($client_id)); $encodedvariables = array_map ( 'rawurlencode_callback', $variables, array_keys($variables) ); $postcontent = join('&', $encodedvariables); $postcontentlen = strlen($postcontent); $ctx = stream_context_create ( array ( 'http' => array ( 'method' => 'POST', 'content' => $postcontent, 'header' => "Content-Type: application/x-www-form-urlencoded". "\r\n". "Content-Length: $postcontentlen". "\r\n" ) ) ); $url = ' $fp = fopen($url, 'r', false, $ctx); if($fp!== false) { stream_set_timeout($fp, 20); # stream uitvoeren $response = trim(stream_get_contents($fp)); $meta_data = stream_get_meta_data($fp); fclose($fp); return $response; } return ('error'); } $return = send_sms('<316 >','testbericht','<licentie-sleutel>','<klantnummer'); echo $return; Aanleveren van te verzenden SMS V1.3 9

10 7. BIJLAGE 2: Voorbeeld PHP-scripting XML-request <?php function do_post_request($url, $data) { $params = array('http' => array( 'method' => 'POST', 'content' => $data )); # stream openen $ctx = stream_context_create($params); $url = ' $fp = fopen($url, 'r', false, $ctx); if($fp!== false) { stream_set_timeout($fp, 20); # stream uitvoeren $response = trim(stream_get_contents($fp)); $meta_data = stream_get_meta_data($fp); fclose($fp); return $response; } return ('error'); } $request = '<?xml version="1.0" encoding="iso "?> <smss_list> <sms_list> <client_id>[klantnummer]</client_id> <batch_name>test</batch_name> <message>testbericht</message> <license_key>[licentie-sleutel]</license_key> <title>[bedrijfsnaam]</title> <sms> <name>[ontvanger]</name> <msisdn>[316...]</msisdn> </sms> </sms_list> </smss_list>'; $return = do_post_request($url, $request); echo ($return); Aanleveren van te verzenden SMS V1.3 10