DOCUMENTATION API BUZZ- EXPERT

Transcription

1 DOCUMENTATION API BUZZ- EXPERT BUZZ-EXPERT met à votre disposition un web services permettant d'agir depuis n'importe quelle plateforme pour gérer vos contacts, effectuer des push SMS... Avant de pouvoir communiquer avec notre web services, il faut au préalable ajouter l'ip depuis laquelle sera effectuée les actions sur votre profil utilisateur. Pour ce faire, rendez-vous sur la page et ajouter les IP de vos serveurs. ( ) Aujourd'hui, seules les IP statiques sont acceptées. Contenu 1. Intercommunication Code erreur Récupération du token Gestion de contacts Récupérer les listes de contacts Récupérer les contacts d'une liste Ajouter un contact à une liste Modifier un contact d'une liste Supprimer un contact d'une liste Ajouter un contact à la liste noire Supprimer un contact de la liste noire Effectuer un push Crédits restant Transmission des DLR, des réponses et des blacklists Transmissions d un DLR Transmissions d une réponse Transmissions des blacklists Codes DLR SMS MMS TELEMAQUE 1

2 1. Intercommunication Toutes les requêtes effectuées sur l'api buzz-expert se feront via le protocole HTTP/HTTPS en utilisant la méthode POST. La communication s'effectuera au travers un flux xml, encapsulé dans le champ request. L'URL à interroger est request=<?xml version="1.0" encoding="utf-8"?>... Toutes les réponses de l'api se présenteront sous la forme suivante En cas de succès: <?xml version="1.0" encoding="utf-8"?> <query>telepush:api_token</query> <time>0.0115</time> En cas d'erreur: <?xml version="1.0" encoding="utf-8"?> <query>telepush:api_token</query> <time>0.0115</time> <status>ko</status> <errno>403</errno> <error>authentification refusée</error> query: Requête effectuée time: Temps de réponse du web services result: Résultat de la requête result/status: Statut de la réponse, peut prendre la valeur ok ou ko result/errno: Code erreur result/error: Message erreur TELEMAQUE 2

3 1.1. Code erreur CODE MESSAGE 400 XML mal formaté 401 authentification requise 403 authentification refusée 404 requête inconnue 409 erreur personnalisée pour les paramètres 410 crédit insuffisant 500 erreur interne 1.2. Récupération du token Récupération du token permettant de communiquer et vous identifier au sein de l'api buzzexpert.fr URI: /api/token <login>mylogin</login> <password>mypassword</password> login: Correspond à votre identifiant utilisé lors de l'inscription sur la plate-forme web.buzzexpert.fr password: Correspond à votre mot de passe de la plate-forme <?xml version="1.0" encoding="utf-8"?> <query>telepush:api_token</query> <time>0.0115</time> TELEMAQUE 3

4 token: Token à utiliser pour effectuer des actions sur votre compte. Ce token expire après une heure sans utilisation (appel au web services). 2. Gestion de contacts 2.1. Récupérer les listes de contacts URI: /api/phone-list <?xml version="1.0" encoding="utf-8"?> <query>telepush:_api_phone_list</query> <time>0.0104</time> <phone_list> <node> <id>2</id> <name>telemaque</name> <dest>3421</dest> </node> <node> <id>12</id> <name>test</name> <dest>9836</dest> </node> </phone_list> TELEMAQUE 4

5 phone_list: Contient les listes de contact phone_list/node/id: Id de la liste phone_list/node/name: Nom de la liste phone_list/node/dest: Contient le nombre de contact appartenant à la liste 2.2. Récupérer les contacts d'une liste URI: /api/phone-list/detail <phone_list_id>2</phone_list_id> <page>1</page> <limit>200</limit> phone_list_id: Id de la liste à afficher page: Page à afficher limit: Nombre de résultats par page (1000 max) RESPONSE <query>telepush:_api_phone_list_detail</query> <time>0.0086</time> <phone_list> <header> <node>prenom</node> <node>nom</node> </header> <id>2</id> <phones> <node> <id>1</id> <num> </num> <blacklist>0</blacklist> <PRENOM>Guillaumes</PRENOM> <NOM>DIEVART</NOM> TELEMAQUE 5

6 </node> <node> <id>2</id> <num> </num> <blacklist>0</blacklist> <PRENOM>Guilhem</PRENOM> <NOM>OSTALIER</NOM> </node> </phones> </phone_list> phone_list/header: Variables appartenant à la liste phone_list/id: Identifiant de la liste phone_list/phones: Liste des numéros appartenant à la liste phone_list/phones/node/id: Identifiant du numéro phone_list/phones/node/num: Numéro phone_list/phones/node/blacklist: Numéro blacklisté ou non 2.3. Ajouter un contact à une liste URI: /api/phone-list/add-phone <phone_list_id>2</phone_list_id> <number> </number> <replace>1</replace> <variables> <PRENOM>Guillaume</PRENOM> <NOM>DIEVART</NOM> </variables> phone_list_id: Id de la liste dans laquelle ajouter le numéro number: Numéro de téléphone à ajouter replace: Si ce champ est présent avec pour valeur 1 et que l'utilisateur est déjà présent dans la TELEMAQUE 6

7 liste, il sera mis à jour variables/{$variable}: Liste des variables pour le numéro <query>telepush:_api_phone_list_add</query> <time>0.0286</time> 2.4. Modifier un contact d'une liste La modification d'un numéro de téléphone peut soit se faire via l'id interne, ou via le numéro directement. Ce qui implique que les champs number et phone_id sont exclusifs URI: /api/phone-list/update-phone <phone_list_id>2</phone_list_id> <number> </number> <variables> <PRENOM>Gérard</PRENOM> <NOM>Bichon</NOM> </variables> phone_list_id: Id de la liste dans laquelle ajouter le numéro number: Numéro de téléphone à modifier variables/{$variable}: Liste des variables pour le numéro <query>telepush:_api_phone_list_update</query> <time>0.0286</time> TELEMAQUE 7

8 2.5. Supprimer un contact d'une liste URI: /api/phone-list/delete-phone <phone_list_id>2</phone_list_id> <number> </number> phone_list_id: Id de la liste dans laquelle supprimer le numéro number: Numéro de téléphone à modifier <query>telepush:_api_phone_list_delete</query> <time>0.0286</time> 2.6. Ajouter un contact à la liste noire URI: /api/phone-list/add-phone-blacklist <number> </number> number: Numéro de téléphone à modifier TELEMAQUE 8

9 <query>telepush:_api_phone_list_add_bl</query> <time>0.0286</time> 2.7. Supprimer un contact de la liste noire URI: /api/phone-list/delete-phone-blacklist <number> </number> number: Numéro de téléphone à modifier <query>telepush:_api_phone_list_add_bl</query> <time>0.0286</time> 3. Effectuer un push Cette méthode permet de faire un push SMS/MMS/VOICE. URI: /api/push <type>sms</type> TELEMAQUE 9

10 <number> </number> <medias> <media>ceci est le message à envoyer</media> </medias> <options> <type>alerting</type> <oadc>telemaque</oadc> <label>telemaque</label> </options> type: Type de push à effectuer (SMS, MMS ou VOICE). number: Numéro du destinataire medias: Message à envoyer au destinaire. Dans le cas du SMS seul le premier champ media est pris en compte. options: Les options sont liés au type de push. Pour le SMS par exemple l'option type est obligatoire options/type: Type de push à effectuer. Deux valeur autorisées (ALERTING et TEASING). Les push de type ALERTING seront envoyés n'importe quel jour et à n'importe quelle heure, contrairement au type MARKETING qui respectent une plage horaire (9h - 21h) et du lundi au samedi hors jours fériés. OPTIONS SMS options/oadc: L'OADC correspond à l'expéditeur qui sera affiché sur le SMS (obligatoire si pas de label). options/label: Le label sera afficher en début de message sous la forme: LABEL: Mon message (obligatoire si pas d'oadc). OPTIONS MMS options/subject: Sujet du MMS (facultatif). OPTIONS VOICE options/caller_num: Numéro de l'appelant. options/token: Correspond au token d'un précédent push. Si token est renseigné l'envoi des fichiers ne sera donc plus nécessaire. <query>telepush:_api_push</query> <time>0.0205</time> TELEMAQUE 10

11 <tx_id> </tx_id> <credit>2</credit> <token>09ea750331d c87322be829c</token> tx_id: Id de la transaction du push. credit: Nombre de crédit consommé par le push. token: Uniquement présent dans le cas d'un push vocale. Ce token pour être réutilisé par la suite afin d'éviter de renvoyer le fichier à jouer de nouveau. Attention Pour les pushs SMS / MMS, le message doit comporter uniquement les caractères suivant : 0-9 a-z A-Z é è à,!? ' ( ) _ % / + = :. ; < > & *. Pour les pushs MMS, les médias suivants sont supportés : texte, image (gif, jpg, png), vidéo (3gp), son (mpeg), carte de visite vcard (vcf). 4. Crédits restant URI: /api/credit/remain <query>telepush:api_credit_remain</query> <time>0.0286</time> <credit>50.00</credit> TELEMAQUE 11

12 5. Transmission des DLR, des réponses et des blacklists Les DLR (accusés de réception) et les réponses peuvent être transmis directement par une requête HTTP sur une URL spécifiée par un utilisateur dans la section Profil / API Transmissions d un DLR Méthode HTTP: ''POST'' Variables : «tx_id» identifiant de la transaction (uniquement dans le cadre d'un push API) «cp_id» référence de la campagne (uniquement dans le cadre d'un push d'une campagne via l'interface web.buzz expert.fr) «status» statut du DLR (liste des codes DLR ci dessous) «response» détails concernant le DLR de l'opérateur «phone» destinataire de l'envoi 5.2. Transmissions d une réponse Méthode HTTP: ''POST'' Variables : «tx_id» identifiant de la transaction (uniquement dans le cadre d'un push API) «cp_id» référence de la campagne (uniquement dans le cadre d'un push d'une campagne via l'interface web.buzz expert.fr) «response» contenu de la réponse de l'opérateur «phone» destinataire de l'envoi 5.3. Transmissions des blacklists Méthode HTTP: ''POST'' Variables : «tx_id» Identifiant de la transaction (uniquement dans le cadre d'un push API) «cp_id» référence de la campagne (uniquement dans le cadre d'un push d'une campagne via l'interface web.buzz expert.fr) «response» contenu de la réponse de l'opérateur (qui commence donc par "stop") «msisdn» destinataire de l'envoi «blacklist_date» La date d'entrée dans la blacklist du destinataire 5.4. Codes DLR SMS La valeur d'un DLR peut être : 1: SMS Reçu 2: SMS Rejeté par le mobile 4: SMS Mis en attente coté opérateur 8: SMS Envoyé à l'opérateur 16: SMS Refusé par l'opérateur TELEMAQUE 12

13 MMS La valeur d'un DLR peut être : Forwarded (Transmis à l opérateur) Retrived (Téléchargé par le client) Error TELEMAQUE 13