Aanleveren van te verzenden sms berichten aan SMS Via

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 email; 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. HTTP request Het HTTP request betreft een POST met de volgende parameters:

client_id license_key msisdn message

Het klantnummer, dat onder “Uw gegevens” te vinden is De licentiesleutel, die aan u is toegewezen Het telefoonnummer van de ontvanger De te verzenden boodschap

Het telefoonnummer van de ontvanger moet een geldig telefoonnummer zijn, van het volgende format (voorbeeld) “31623232323”. Hierbij geldt het volgende:

31

623 232323

is het landnummer van Nederland; uiteraard is een ander landnummer ook mogelijk is het netnummer of het begin van het 06-nummer (zonder 0 dus) is het toestelnummer

Dit request stuurt u naar de URL https://client.sms-via.nl/upload/http_sms_request.php Op de volgende wijze kan met CURL een POST-request worden doorgegeven (alles op 1 regel): curl --data "client_id=…&license_key=…&msisdn=…&message=…" https://client.sms-via.nl/upload/http_sms_request.php

Terugkoppeling U krijgt van SMS Via het antwoord “OK”, wanneer het request goed is ontvangen en zal worden verzonden of het antwoord “ERROR ”, 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


2

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.


3

3. XML request In een XML request kunnen meerdere sms berichten tegelijk worden opgenomen. De XML heeft het volgende format: <smss_list> <sms_list> <message> <sms> <msisdn> <message> <sms> <msisdn> <message> … …

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 license-key batch-name via-type

title message msisdn

name

Het klantnummer, dat onder “Uw gegevens” te vinden is De licentiesleutel, die aan u is toegewezen Uw identificatie voor deze batch Het type bericht; dit is voor latere uitbreidingen van de SMS Via diensten en hoeft nog niet te worden meegegeven De naam van de afzender De te verzenden boodschap Het telefoonnummer van de ontvanger (zie paragraaf 2 voor het format) De naam van de ontvanger


4

De te verzenden boodschap kan één boodschap voor alle nummers zijn, buiten de <sms> tags of een boodschap per nummer, binnen de <sms> tags. Wanneer de boodschap per nummer niet wordt opgenomen, wordt de boodschap buiten de <sms> tags gekozen.

Dit request stuurt u naar de URL https://client.sms-via.nl/upload/xml_sms_request.php 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: <smss_result_list> <sms_result_list> <message> <sms> <msisdn> <message> <sms> <msisdn> <message> …

Er wordt dus per “<sms_list>” een algemeen resultaat teruggegeven (“”) en per telefoonnummer een resultaat (“”); In de bijlagen vind u een scripting-voorbeeld hoe dit request te sturen vanuit PHP.


5

4. Email Sms kan via email 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.

4.1.

Email eenvoudig format

Met het eenvoudige format kan slechts één sms tegelijkertijd worden verzonden. SMS Via verwacht de volgende informatie in een email: Van: Aan: Onderwerp: Tekst:

Geef in dit veld de afzender van de sms aan. De tekst voor de ‘@’ mag maximaal 11 karakters zijn Geef in dit veld het telefoonnummer aan van de ontvanger van het sms bericht, met als domein ‘@sms-via-email.nl’ Plaats hier de tekst van de sms Plaats hierin je client-id en license-key, gescheiden door een puntkomma (;)

Dat ziet er bijvoorbeeld zo uit:

Van: Aan: Onderwerp: Tekst:

[email protected] [email protected] Testbericht van mij 1111;AAAAA-BBBBB-CCCCC-DDDDD-EEEEE

De sms wordt dan verstuurd aan het nummer 06-23232323 met als afzender ‘Uwnaam’. Let op dat de tekst van de email niet als HTML is opgemaakt, want dat wordt door de SMS Via server niet geaccepteerd! Wanneer er geen correcte informatie wordt doorgegeven in de email, wordt de sms niet verstuurd. Neem bij vragen contact op met onze support afdeling: [email protected].


6

4.2.

Email XML format

Met het email 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 email: Van: Aan: Onderwerp: Tekst:

Deze informatie wordt niet gebruikt Geef in dit veld het telefoonnummer aan van de ontvanger van het sms bericht, met als domein ‘@sms-via-email.nl’. Let op, het telefoonnummer dient ook in de XML opgenomen te zijn. Deze informatie wordt niet gebruikt Plaats hier de XML

Het is ook mogelijk om de XML door te geven in een bijlage (attachment) bij de email. Let op dat de tekst van de email 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 email, wordt de sms niet verstuurd. Neem bij vragen contact op met onze support afdeling: [email protected].


7

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 batch

status error

Het telefoonnummer van de ontvanger De identificatie van het bericht. Dit is uw batchname of de datum/tijd waarop is aangeleverd De status van het bericht 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.


8

6. BIJLAGE 1: Voorbeeld PHP-scripting HTTP-request

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 = 'https://client.sms-via.nl/upload/http_sms_request.php'; $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','','

9

7. BIJLAGE 2: Voorbeeld PHP-scripting XML-request array( 'method' => 'POST', 'content' => $data )); # stream openen $ctx = stream_context_create($params); $url = 'https://client.sms-via.nl/upload/xml_sms_request.php'; $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 = ' <smss_list> <sms_list> [klantnummer] test <message>testbericht [licentie-sleutel] [bedrijfsnaam] <sms> [ontvanger] <msisdn>[316...] '; $return = do_post_request($url, $request); echo ($return);


10

Aanleveren van te verzenden sms berichten aan SMS Via

Recommend Documents