SMS siuntimas

PAKETAIS

Partnerio sistema HTTP užklausą siunčia adresu
http://smscomm.vero.lt/partner/sms_packet.php.

Parametrai turi būti URL-encoded ir koduojami UTF-8 formatu.
Duomenys pateikiami GET metodu:

Pavadinimas	Aprašymas	Pavyzdys
username	Prisijungimo vardas	demo
password	Prisijungimo slaptažodis	demo
action	Vykdomas veiksmas, galimos reikšmės: • validate_packet – masinės žinutės klaidų patikrinimas, siuntimas nebus vykdomas; • send_packet – masinės žinutės išsiuntimas; • get_packet – masinės žinutės siuntimo, pristatymo statistika; • validate_edit –neišsiųstų žinučių redagavimo klaidų patikrinimas; • edit – redaguoti neišsiųstas žinutes; • stop – sustabdyti žinučių siuntimą; • delete – panaikinti neišsiųstas žinutes;	send_packet
HTTP POST	Veiksmo detalūs parametrai, plačiau apie jų reikšmes skaitykite prie konkretaus veiksmo aprašymo. Parametrų struktūra užkoduojama JSON formatu ir paduodama HTTP POST metodu.	array ( 'ident' => 1323202186, 'sender' => 'VeroDemo', 'sms' => 'Demo SMS API message', 'messages' => array ( 1 => array ( 'phone' => '37065659515', ), 2 => array ( 'phone' => '37060042751', 'sms' => 'Dear John. Demo SMS API message', ), ), )

Įvykdžius HTTP užklausą, iš MBS gaunamas JSON formato atsakymas, suformatuotas pagal JSEND specifikaciją (plačiau http://labs.omniti.com/labs/jsend/wiki). Ji griežtai apibrėžia 3 atsakymo tipus:
* success – sėkmės;
* fail – nesėkmės (pvz. klaidingi duomenys);
* error – klaidos (buvo mesta išimtis, DB klaida, ...);

Vienos iš HTTP užklausų pavyzdys:

http://smscomm.vero.lt/partner/sms_packet.php?username=demo&password=demo&action=send_packet

HTTP POST pavyzdys:

{"ident":1323203033,"type":"SMS","sender":"VeroDemo","sms":"Demo SMS API message",
"messages":{"1":{"phone":"37065659515"},"2":{"phone":"37060042751",
"sms":"Dear John. Demo SMS API message"}}}

HTTP atsakymo pavyzdys (sėkmė):

{"status":"success","data":{"sent":{"1":11021391,"2":11021392},"errors":[]}}

HTTP atsakymo pavyzdys (nesėkmė):

{"status":"fail","data":{"sent":[],"errors":{"1":{"field":"phone",
"field_error":"Wrong MSISDN format"}}}}

validate_packet, send_packet

Veiksmas validate_packet skirtas masinės žinutės klaidų patikrinimui, siuntimas nebus vykdomas. Veiksmas send_packet - masinės žinutės išsiuntimas.

Užklausos parametrai:

Pavadinimas	Aprašymas	Pavyzdys
messages	Gavėjų sąrašas - asociatyvus masyvas, kuriame pateikiamos raktas-reikšmė poros: • reikšmėje būtinai nurodomas privalomas parametras „phone“ - gavėjo telefono numeris (MSISDN), tarptautiniu formatu „370xxxyyyyy“; • rakte nurodomas gavėjo unikalus identifikatorus sąraše. Poto naudojamas susieti su paketo klaidomos • reikšmėje galima nurodyti asmeninius to gavėjo žinutės parametrus, tokius pat kaip siunčiant vieną žinutę. Pvz., nurodžius „sms“ parametrą, konkrečiam gavėjui galima suformuoti kitą žinutės tekstą;	array( '1' => array( 'phone' => '37065659515', ), '2' => array( 'phone' => ' 37060042751', 'sms' => ' Dear John. Demo SMS API message ));
skip_errors	(nebūtina) Kaip traktuoti paketo klaidingas žinutes (galimas tik send_packet veiksme): 0 – jei pakete rasta klaidų, siuntimas nevykdomas (reikšmė pagal nutylėjimą); 1 - bet kuriuo atveju siųsti žinutes, praleidžiant tas kuriose rasta klaidų;	0
sender	(nebūtina) Siuntėjo telefono numeris. Galimybė įjungiama atskiru susitarimu, nurodant kokios reikšmės bus naudojamos	VeroDemo
sms	nebūtina) Siunčiamo SMS tekstas (jei WapPush, nuorodos antraštė - tekstas)	Demo SMS API message
ident	(nebūtina) Išorinės sistemos identifikatorius, pvz., masinės žinutės identifikatorius	news-reminder-12345
...	(nebūtina) Galimi visi kiti parametrai, naudojami siunčiant vieną žinutę

Atsakymo parametrai:

Statusas	Aprašymas	Pavyzdys
success	Žinutės arba dalis jų sėkmingai išsiųstos. Grąžinama: • sent – sėkmingai priimtos žinutės ir joms suteikti unikalūs identifikatoriai MBS sistemoje - SMS_ID; • errors – Nepriimtos žinutės, ir jose įvykusios klaidos (jei naudojamas parametras skip_errors=1);	array( 'status' => 'success', 'data' => array( 'sent' => array( '1' => 12345, '2' => 12346, ), 'errors' => array() ))
fail	Žinutės neišsiųstos, dėl neteisingai nurodytų duomenų. Grąžinama: • errors – Nepriimtos žinutės, ir jose įvykusios klaidos; • field – kuriame lauke įvyko klaida; • field_error – klaidos aprašymas;	array( 'status' => 'success', 'data' => array( 'sent' => array(), 'errors' => array( '3' => array( 'field' => 'phone', 'field_error' => 'Wrong msisdn format') ) ))
error	Kritinė arba nenumatyta susijungimo klaida	array( 'status' => 'error', 'message' => 'Fatal DB error', )

get_packet

Veiksmas get_packet skirtas patikrinti masinės žinutės siuntimo, pristatymo statistiką.

Užklausos parametrai:

Pavadinimas	Aprašymas	Pavyzdys
ident	Nurodyti, kurios žinutės tikrinamos, pagal išorinės sistemos identifikatorių	news-reminder-12345

Atsakymo parametrai:

Statusas	Aprašymas	Pavyzdys
success	Grąžinama masinės žinutės informacija: • ident – žinučių išorinės sistemos identifikatorius; • stats_overal – visų žinučių kiekis; • stats_sent – kiek žinučių jau išsiųsta; • stats_delivered – kiek žinučių pristatyta vartotojams; • stats_length – kiek paketų, kuriuos reikės apmokėti (vieną paketą sudaro 160 simbolių);	array( 'status' => 'success', 'data' => array( 'ident' => 'news-reminder-12345', 'stats_overal' => '100', 'stats_sent' => '100', 'stats_delivered' => '87', 'stats_length' => '87', ))
error	Kritinė arba nenumatyta susijungimo klaida	array( 'status' => 'error', 'message' => 'Fatal DB error', )

validate_edit, edit

Veiksmas validate_edit redaguojamų žinučių klaidų patikrinimui, realus redagavimas nebus įvykdytas. Veiksmas edit skirtas redaguoti dar neišsiųstas žinutes (vieną žinutę arba visą paketą).

Atminkite, redagavimo veiksmai (edit, stop, delete) vykdomi tik dar neišsiųstoms žinutėms. Išsiųstos žinutės neliečiamos.

Užklausos parametrai:

Pavadinimas	Aprašymas	Pavyzdys
ident	Nurodyti, kurias žinutes redaguoti, pagal išorinės sistemos identifikatorių	news-reminder-12345
message_id	(nebūtina) Nurodyti, kurias žinutes redaguoti, pagal žinutės unikalų MBS identifikatorių arba jų masyvą	array(12345, 12346, 12347)
sender	(nebūtina) Jei norite redaguoti siuntėjo telefono numerį	VeroDemo
sms	(nebūtina) Jei norime redaguoti siunčiamo SMS tekstą (jei WapPush, nuorodos antraštę - tekstą)	Demo SMS API message
new_ident	(nebūtina) Jei norite redaguoti išorinės sistemos identifikatorių, pvz., galima paredaguotas žinutes suformuoti į naują paketą	news-reminder-12346
...	(nebūtina) Redaguoti galima visus kitus parametrus, naudojamus siunčiant vieną žinutę

Atsakymo parametrai:

Statusas	Aprašymas	Pavyzdys
success	Žinutės sėkmingai paredaguotos. Grąžinama: • edited – paredaguotų žinučių kiekis;	array( 'status' => 'success', 'data' => array( 'edited' => 125, ))
fail	Žinutės neredaguojamos, dėl neteisingai nurodytų duomenų. Grąžinama: • field – kuriame lauke įvyko klaida; • field_error – klaidos aprašymas;	array( 'status' => 'fail', 'data' => array( 'field' => 'message', 'field_error' => 'Empty sending text', ))
error	Kritinė arba nenumatyta susijungimo klaida	array( 'status' => 'error', 'message' => 'Fatal DB error', )

stop

Veiksmas stop skirtas sustabdyti dar neišsiųstų žinučių siuntimą neribotam laikui (vieną arba visą paketą).

Atminkite, redagavimo veiksmai (edit, stop, delete) vykdomi tik dar neišsiųstoms žinutėms. Išsiųstos žinutės neliečiamos.

Užklausos parametrai:

Pavadinimas	Aprašymas	Pavyzdys
ident	Nurodyti, kurias žinutės stabdyti, pagal išorinės sistemos identifikatorių	news-reminder-12345
message_id	(nebūtina) Nurodyti, kurias žinutes stabdyti, pagal žinutės unikalų MBS identifikatorių arba jų masyvą	array(12345, 12346, 12347)
new_ident	(nebūtina) Jei stabdant norite redaguoti išorinės sistemos identifikatorių, pvz., galima sustabdytas žinutes suformuoti į naują paketą	news-reminder-12346

Atsakymo parametrai:

Statusas	Aprašymas	Pavyzdys
succes	Žinutės sėkmingai sustabdytos. Grąžinama: • edited – sustabdytų žinučių kiekis;	array( 'status' => 'success', 'data' => array( 'edited' => 125, ))
error	Kritinė arba nenumatyta susijungimo klaida	array( 'status' => 'error', 'message' => 'Fatal DB error', )

delete

Veiksmas delete skirtas negrįžtamai panaikinti dar neišsiųstas žinutes (vieną arba visą paketą).

Atminkite, redagavimo veiksmai (edit, stop, delete) vykdomi tik dar neišsiųstoms žinutėms. Išsiųstos žinutės neliečiamos.

Užklausos parametrai:

Pavadinimas	Aprašymas	Pavyzdys
ident	Nurodyti, kurias žinutes naikinti, pagal išorinės sistemos identifikatorių	news-reminder-12345
message_id	(nebūtina) Nurodyti, kurias žinutes naikinti, pagal žinutės unikalų MBS identifikatorių arba jų masyvą	array(12345, 12346, 12347)

Atsakymo parametrai:

Statusas	Aprašymas	Pavyzdys
success	Žinutės sėkmingai ištrintos. Grąžinama: • deleted – ištrintų žinučių kiekis;	array( 'status' => 'success', 'data' => array( 'deleted' => 125, ))
error	Kritinė arba nenumatyta susijungimo klaida	array( 'status' => 'error', 'message' => 'Fatal DB error', )

PAVYZDYS

Atliekamas masinės žinutės siuntimas keliems vartotojams, o rezultatas atspausdinamas į ekraną.

Jei naudojate PHP programavimo kalbą, galite naudoti MBS PHP bibliotekos klasę SMSComm

Jei nenorite naudoti MBS PHP bibliotekos, reikėtų persirašyti kai kurias jūsų patogumui pateikiamas funkcijas, pvz., sendPacket(), _callPacketAction(), _sendRequest()

< !--?php
/**
 * Raw mass SMS sending example
 *
 * @see MBSLib/examples/simple/send_sms_packet.php
 *
 * @package RawExamples
 * @author Valdas Petrulis 
 */

include_once(dirname(__FILE__).'/../../lib/SMSComm.class.php');

try {
    // Init SMS API client with wanted configuration
    define('SMSCOMM_USERNAME', 'demo');
    define('SMSCOMM_PASSWORD', 'demo');
    $client = new SMSComm(SMSCOMM_USERNAME, SMSCOMM_PASSWORD);
    $client->setDebug(true);

    // Send mass SMS
    $ident = time();
    $messages = array(
        1 => array('phone' => '37065659515'),
        2 => array('phone' => '37060042751', 'sms' => 'Dear John. Demo SMS API message'),
    );
    $result = $client->sendPacket($messages, false, 'VeroDemo', 'Demo SMS API message', null, $ident);
    if ($result['status']=='success') {
        echo 'Sent '. count($result['data']['sent']) .' SMS messages, '. count($result['data']['errors']) .' errors';
    } else {
        echo 'Errors in SMS messages: '.var_export($result['data']['errors'], true);
    }

    // Watch sending/delivery statistics
    $stats = $client->getPacket($ident);
    echo 'Packet information: '. var_export($stats, true);
} catch(Exception $e) {
    echo "Error in SMS API: " . $e;
}

?>