MasterPush Documentation

Transcription

1 MasterPush Documentation Version [ Dalenys ] mars 16, 2017

2

3 Presentation 1 Prérequis Installer Curl S authentifier Envoyer/Retrouver des messages Recupérer la liste des messages Retrouver un message Envoyer un message Envoi multiple Statuts des messages Statistiques Général Par heure Par jour Par mois Filtrer les statistiques i

4 ii

5 Masterpush est un service d envoi de masse dédié au SMS. Il permet à nos clients d envoyer des campagnes de marketing via SMS. Le but de cette documentation et de permettre à un utilisateur de l API Masterpush d implémenter rapidement un module d envoi de sms sur son application. Documentation pour PHP : Afin d utiliser l API, vous devez pouvoir envoyer des requêtes HTTP à nos serveurs. Cela peut être fait via l extension php Curl. Presentation 1

6 2 Presentation

7 CHAPITRE 1 Prérequis Installer Curl Sur ubuntu $> apt-get install php5-curl $> service apache2 restart Si vous utilisez php-fpm : $> service php5-fpm restart S authentifier Afin de vous identifier sur l API, il vous sera demandé d ajouter un token (clé) d authentification à chaque requête. Celui-çi vous sera communiqué par un de nos account Managers ou commercial, il peut être révoqué à tout moment. Pour cela, il suffit de demander la génération d un nouveau token. La clé doit être ajoutée dans les headers des requêtes. Voici comment procéder avec Curl : setopt($ch, CURLOPT_HTTPHEADER, array('x-masterpush-apikey: '. $token)); Un code http 403 sera retourné avec le message Authentication Failed si l authentification échoue. 3

8 4 Chapitre 1. Prérequis

9 CHAPITRE 2 Envoyer/Retrouver des messages Recupérer la liste des messages Pour avoir la liste des messages, il vous suffit d envoyer une requête GET vers la route /messages curl_setopt($ch, CURLOPT_URL, ' print $server_output; Le code ci-dessus devrait retourner un object JSON correspondant au template ci-dessous : [ ] { } "id": 0, "phone": "+33xxxxxxxxx", "content": "La vie l'univers et tout le reste", "status": "ok", "date": " :42:42" Si aucun message n a été envoyé via cette configuration, le tableau sera vide. 5

10 Filtrer les résultats Il est possible de filtrer les résultats d une requête. Pour cela, il faut ajouter les filtres dans l url. Il y a six filtres disponibles sur cette ressource : phonenumber : Limite la recherche au numéro status : Limite la recherche statut des messages, il peut être ok ko error waiting queued toqueued processing from : Limite la recherche aux messages envoyés après cette date, le format de date est Y-m-d H :i :s to : Limite la recherche aux messages envoyés jusqu à cette date, le format de date est Y-m-d H :i :s limit : Limite le nombre de resultats (100 max) offset : Saute les x premiers resultats. Voici un exemple pour avoir les messages envoyés au +33xxxxxxxxx qui sont ko : curl_setopt($ch, CURLOPT_URL, ' urlencode('+33xxxxxxxxx'). '&status=ko'); print $server_output ; Retrouver un message Vous pouvez retrouver un message a partir de son ID. Pour faire ça, il suffit d envoyer une requête GET vers la route /messages/{id} où {ID} doit être remplacé par l ID du message en question. Le code ci-dessous retournera les informations du message a l id 42sh (il n existe pas). curl_setopt($ch, CURLOPT_URL, ' 6 Chapitre 2. Envoyer/Retrouver des messages

11 print $server_output ; Le code ci-dessus devrait retourner un object JSON correspondant au template ci-dessous : { } "id": 0, "phone": "+33xxxxxxxxx", "content": "La vie l'univers et tout le reste", "status": "ok", "date": " :42:42" Envoyer un message Pour envoyer un message via notre API, il suffit d envoyer une requête POST vers la route /messages Cette route demande un object JSON dans le body contenant au moins les champs : phonenumber content Le champ oadc est optionnel et changera le sender affiché sur le téléphone du destinataire. Le code ci-dessous va envoyé un sms au numéro +336xxxxxxxx avec le l OADC masterpush. curl_setopt($ch, CURLOPT_URL, ' curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, '{"phonenumber": "+336xxxxxxx", "content": "La vie l\'univers et tout le reste", "oadc": "masterpush"}' ); print $server_output; La route /messages retourne un object json représentant le message, il contient l id du message, le numéro du destinataire, le status, et la date d envoi. Exemple de retour avec un code http 201 : { "id": 0, "phone": "+33xxxxxxxxx", "content": "La vie l'univers et tout le reste", "status": "waiting", 2.3. Envoyer un message 7

12 } "date": " :42:42" Plusieurs retours sont possibles : Cas Code http de Body de la réponse (exemple) la réponse Envoi accepté 201 { id :0, phonenumber : +336xxxxxxx, content : Contenu, status : waiting, date : T08 :55 : } Requête/json 400 { error : Messages JSON object not found or not valid } malformée Champ manquant 400 { errors :{ test : This field was not expected. }} ou non attendu Non autorisé pour l international 403 { error : Sending messages to international phone numbers is not allowed } Cas d erreur spécifique 4XX ou 5XX { error : Message d erreur spécifique } Ce tableau n est pas exhaustif. Dans certains cas spécifiques, un code de retour http 4XX ou 5XX peut-être retourné avec un body json { error : Message d erreur } Envoi multiple Vous pouvez envoyer plusieur message en une requête. Pour cela il suffit d envoyer une requête POST vers la route /messages/multiple. Cette route prend pour argument une array de message. L exemple ci-dessous envera deux messages. curl_setopt($ch, CURLOPT_URL, ' curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, '[ {"phonenumber": "+336xxxxxxx", "content": "La vie l\'univers et tout le reste", "oadc": "masterpush"}, {"phonenumber": "+336xxxxxxx", "content": "un autre message", "oadc": "masterpush"} ]' ); print $server_output; La route /messages/multiple retourne un object json représentant une array de messages. [{ "id": 0, "phone": "+33xxxxxxxxx", 8 Chapitre 2. Envoyer/Retrouver des messages

13 "content": "La vie l'univers et tout le reste", "status": "waiting", "date": " :42:42" },{ "id": 42, "phone": "+33xxxxxxxxx", "content": "un autre message", "status": "waiting", "date": " :42:42" }] Comme pour l envoi simple, plusieurs retours sont possibles : Cas Code http de la Body de la réponse (exemple) réponse Envoi multiple accepté 201 Tableau json représentant la liste des messages Requête/json malformée 400 { error : Message collection not found } Champ manquant ou non attendu 400 { errors :[{ test : mavaleur This field was not expected. }]} Cas d erreur spécifique 4XX ou 5XX { error : Message d erreur spécifique } Il est important de noter que même si l envoi multiple est accepté, certains messages peuvent ne pas être envoyés pour diverses raisons. Il est donc conseillé de vérifier le champ status de chaque message dans la liste retournée. Statuts des messages Le champ status représente l état du message. Valeur du champ status Signification waiting Le message est en cours d envoi (en attente de l accusé de réception par l opérateur) ok Le message a été remis au destinataire ko Le message n a pas été remis au destinataire (échec) error Une erreur est survenue lors du traitement du message queued Le message est dans la file d attente toqueued Le message va être mis dans la file d attente processing Le message est en cours de traitement dans la file d attente 2.5. Statuts des messages 9

14 10 Chapitre 2. Envoyer/Retrouver des messages

15 CHAPITRE 3 Statistiques L api masterpush vous permet de retrouver vos statistiques en choisissant la granularitée. Général Vous pouvez retrouver vos statistiques depuis la création de la configuration en envoyant une requête GET vers la route /statistics. Le code ci-dessous va recupèrer les statistics du compte. curl_setopt($ch, CURLOPT_URL, ' print $server_output ; Cette route retourne un objet JSON comme celui-dessous : Par heure Pour avoir les statistics du compte par heure, il suffit d envoyer une requête GET vers la route /statistics/hourly comme ci-dessous : 11

16 curl_setopt($ch, CURLOPT_URL, ' print $server_output ; Le retour de cette route est un objet JSON comme si dessous : [ { "date" => " :00:00", "mt" => 1, "operators" => [ ["name" => "sfr", "mt" => 42], {...} ], "status" => [ {"status" => "ok", "mt" => 42}, {...} ] }, {...} ] [ { "mt" => 1, "operators" => [ ["name" => "sfr", "mt" => 42], {...} ], "status" => [ {"status" => "ok", "mt" => 42}, {...} ] }, {...} ] Par jour Pour avoir les statistics du compte par jour, il suffit d envoyer une requête GET vers la route /statistics/daily comme ci-dessous : 12 Chapitre 3. Statistiques

17 curl_setopt($ch, CURLOPT_URL, ' print $server_output ; Le retour de cette route est un objet JSON comme si dessous : [ { "date" => " :00:00", "mt" => 1, "operators" => [ ["name" => "sfr", "mt" => 42], {...} ], "status" => [ {"status" => "ok", "mt" => 42}, {...} ] }, {...} ] Par mois Pour avoir les statistics du compte par mois, il suffit d envoyer une requête GET vers la route /statistics/monthly comme ci-dessous : curl_setopt($ch, CURLOPT_URL, ' print $server_output ; Le retour de cette route est un objet JSON comme si dessous : [ { "date" => " :00:00", "mt" => 1, "operators" => [ 3.4. Par mois 13

18 ] ["name" => "sfr", "mt" => 42], {...} ], "status" => [ {"status" => "ok", "mt" => 42}, {...} ] }, {...} Filtrer les statistiques Toutes les statistiques peuvent être filtrer par date. Pour cela, il suffit d ajouter a l url les paramètres from et to. Ils doivents être formaté comme la date ci dessous (année-mois-jour heure :minute :seconde) : :42 :42 Le code ci-dessous donne un exemple : curl_setopt($ch, CURLOPT_URL, ' urlencode(' :42:42').'&to='.urlencode(' :42:42')); print $server_output ; 14 Chapitre 3. Statistiques