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.4.docx

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> <send_after> <message> <sms> <msisdn> <send_after> <message> <sms> <msisdn> <send_after> <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 send_after



via_type

 

title message

Het klantnummer, dat onder “Uw gegevens” te vinden is De licentiesleutel, die aan u is toegewezen Uw identificatie voor deze batch Geeft aan dat batch na een bepaalde tijd verzonden moet worden; wanneer direct te verzenden is dit niet nodig Geef een datum tijd in format ‘YYYY-MM-DD HH:MM:SS’, dus bijvoorbeeld ‘2013-05-09 14:05:30’ 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


4



msisdn



name

Het telefoonnummer van de ontvanger (zie paragraaf 2 voor het format) De naam van de ontvanger

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 Een email kan met twee verschillende formats worden aangeleverd. In de navolgende paragrafen 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

In dit format kan slechts één sms tegelijk worden verzonden. SMS Via verwacht de volgende informatie in een email:  Van:  Aan:  Onderwerp:  Tekst:

Dit wordt gebruikt de afzender van de sms; de tekst voor de ‘@’ mag maximaal 11 karakters zijn Hierin moet het telefoonnummer worden vermeld van de ontvanger, met als domein ‘@sms-via-email.nl’ Dit bevat de tekst van de sms Hierin worden client-id en license-key doorgegeven, gescheiden door een puntkomma (;), ter identificatie van de klant

Bijvoorbeeld:    

Van: Aan: Onderwerp: Tekst:

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

De sms zal dan worden gestuurd aan het nummer 06-23232323 met als afzender ‘Uwnaam’. Let op dat de tekst van de email niet als HTML mag worden opgemaakt, want dit wordt door de SMS Via server niet herkend! Wanneer geen correcte informatie wordt doorgegeven in de email, wordt de sms niet verstuurd. Wilt u weten of/welk problemen optreden, neem dan contact op met onze support afdeling: [email protected].


6

4.2.

Email XML format

In een email met XML kunnen meerdere sms berichten tegelijk worden opgenomen. De XML heeft het hetzelfde format als voor het XML request (zie paragraaf 3). SMS Via verwacht de volgende informatie in deze email:  Van:  Aan:  Onderwerp:  Tekst:

Wordt niet gebruikt voor de sms Hierin wordt een telefoonnummer verwacht, met domein ‘@sms-viaemail.nl. Dit wordt echter momenteel niet gebruikt voor de sms. Het telefoonnummer dient dan ook in de XML opgenomen te zijn. Wordt niet gebruikt voor de sms Hierin wordt de XML doorgegeven

Het is ook mogelijk om de XML door te geven in een bijlage (attachment) bij de email. Let ook hier op dat de tekst van de email niet als HTML mag worden opgemaakt, want dit wordt door de SMS Via server niet herkend! Wanneer geen correcte informatie wordt doorgegeven in de email, wordt de sms niet verstuurd. Wilt u weten of/welk problemen optreden, neem dan 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 <send_after>2013-12-01 17:00:00 <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