API pour envoyer des push vocaux

Nota : Les balises ou attributs suivants sont sont optionnels :

• login="demo" password="demo"
• <voice_config sender_id="0102030405">
• ref_target="uniq-id-for-report"
• <messaging_config sender_id="0102030405">

Notre API Transactionnelle s’articule principalement autour d’un fichier XML (très simple de compréhension) qu’il faut poster en HTTPS ou en HTTP sur nos serveurs. La réponse (elle aussi en XML) fournie un ensemble de références (des id numériques en général) permettant de connaître l’avancement de vos envois.

Le XML doit être posté à l’adresse suivante :

Plusieurs méthodes de POST sont possibles :

• POST direct du XML (méthode REST ; présentée dans nos exemples de POST SMS) ;
• POST d’un formulaire du type « application/x-www-form-urlencoded » qui doit contenir entre autre, un <input name="xml" type="text" /> contenant le XML ;
• POST du type « multipart/form-data » contenant un <input name="xml" type="file" />
  Ce dernier type de POST revient à placer un bouton sur votre page et à sélectionner sur votre disque dur le fichier XML préalablement généré.

Lors de l’envoi de votre requête POST vers la page « api.ashx », vous devez systématiquement transmettre vos identifiants de compte AUDIO Express-Mailing.

Pour ce faire, nous proposons 4 méthodes :

• L’authentification HTTP Basic grâce au header HTTP_AUTHORIZATION ;
• Le passage des paramètres login et password dans le « Query String » ;
• Le passage des paramètres login et password comme éléments du POST ;
• Ou l’ajout des attributs login et password dans la racine <request> du XML (solution présentée dans nos exemples ci-dessous).

La racine <request> :

Le POST de requête permet de transmettre une ou plusieurs demandes successives à notre API. L’élément racine est <request> avec deux attributs optionnels qui sont login et password pour l’authentification. Chaque nœud enfant constituera une demande auprès de l’API.

L’envoi d’un <push> audio :

La balise <push> s’ajoute comme nœud enfant de la racine , et introduit une demande d’appel audio. Le <push> permet de contrôler le type d’envoi (audio unitaire ou audio mailing) ainsi que la date d’envoi.
À l’intérieur du <push> se trouvent divers paramètres optionnels de configuration ainsi que la liste des destinataires audio.

Structure d’un <push> audio :

• media :
  • « voice » : permet l’envoi d’un message audio soit pré-enregistré (wav) soit en synthèse vocale, vers des téléphones fixes ou mobiles. La diffusion du son s’effectuera au décrochage du téléphone.
  • « messaging » (Dépose message) : permet de déposer un message audio sur la messagerie mobile de vos contacts sans faire sonner leur téléphone.
• type : peut prendre 2 valeurs :
  • « on_demand » : on parlera alors d’un envoi audio transactionnel ; Tous les envois transactionnels sont stockés dans un groupe qui restera actif pendant 1 semaine. Vous pouvez agréger plusieurs push audios dans un même groupe hebdomadaire en utilisant la même propriété « name ».
    Le rapport statistique de chaque groupe sera envoyé le dimanche à minuit.
  • « campaign » : on parlera ici de campagne marketing ; Une campagne peut contenir des milliers de destinataires, mais ne permet pas d’agréger/ajouter de nouveaux destinataires une fois le push créé. Par contre le rapport statistique sera envoyé aussitôt le dernier « recipient/destinataire » traité (en général dans la journée même).
• name : permet de nommer un envoi ou un ensemble d’envoi (on parlera alors de groupe). Ce nom permet de retrouver facilement vos envois dans notre plateforme audio et d’effectuer des opérations non possibles via l’API (annulation d’un envoi, mise en pause, renvoi d’un rapport, effectuer des relances, etc.).
  Il peut s’agir d’une clé unique dans votre système (une référence de mailing), mais tout simplement du nom d’un client ou bien d’une étape commerciale (colis livré, livraison retardée, rappel comptable, etc.).
  Pour les envois audio « on_demand », le paramètre « name » permet de grouper hebdomadairement tous les envois portant le même nom. Le dimanche à minuit, les rapports statistiques de tous les groupes sont envoyés par email puis le ou les push correspondants sont archivés. La semaine suivante, si vous continuez d’utiliser le même nom, un nouveau groupe portant ce nom sera alors créé.
  Attention un envoi créé en toute fin de mois pourra se retrouver dans les archives statistiques du mois suivant, de même il pourra n’apparaître que sur votre facture du mois suivant.
• start_date : Optionnel ; Si vous omettez ce paramètre, les envois seront placés immédiatement dans notre pool d’envoi audio et seront traités au plus vite (au plus vite signifiant « dans la limite des capacités de notre plateforme audio et de son taux d’utilisation à un instant T »).
  Si elle et fournie, la date doit être au format GMT +01:00 (Fuseau Bruxelles, Copenhague, Madrid, Paris) sous la forme suivante « dd/mm/yyyy hh:nn:ss » (14 chiffres avec les zéros initiaux).
• message : permet de transmettre à l’API le document audio à diffuser sous forme d’une chaîne encodée en BASE64, l’attribut « type » indiquera l’extension du fichier (valeurs supportées « wav » ou « text »).
  Pour les médias « voice » et « messaging » le fichier wav devra être au format 128 Kpbs / 8Khz / 16 bits / Mono.
  Le type « text » correspond à un synthétiseur vocal qui va lire votre message par une voix de synthèse de bonne qualité et dont les sonorités sont très proches de la voix humaine… n’hésitez pas à écrire en phonétique pour un meilleur rendu.
• voice_config ou messaging_config : Optionnel ; Actuellement ces balises ne contiennent qu’une seule propriété « sender_id » permettant de forcer le numéro de l’appelant lorsque la connexion téléphonique sera établie. Sans « sender_id » l’appel apparaitra comme appel masqué.
• recipients : permet de fournir la liste des numéros de téléphone destinataires du push.
  Chaque destinataire est ajouté par un élément . Si la cible est un numéro, celui-ci devra être fourni au format (+33 [espace] numéro).
  Plus généralement le format est [+Indicatif pays] [un espace] [suivi du numéro du destinataire sans le zéro initial].
  Exceptionnellement l’API acceptera le format audio 10 chiffres (01xxxxxxxx) pour des envois vers la France Métropolitaine uniquement.L’attribut optionnel ref_target permet de fournir pour chaque destinataire une référence unique et personnelle qui sera re-communiquée lors de la récupération des notifications.

Une fois le push déposé en HTTP ou HTTPS sur nos serveurs, l’API vous fournira en retour un XML de confirmation très simple :

Le status="ok" est l’accusé de réception que devra analyser votre propre système. Si le status est différent de « ok », nous vous invitons à faire une pause dans votre script de 10 secondes puis de renouveler l’envoi de votre push audio.

L’analyse en temps réel de vos envois audio se fait ensuite via des notifications (ci-dessous).

La balise <notifications> permet de récupérer les statistiques d’avancement de vos appels audio.
Cette balise comme celle du <push> s’ajoute comme noeud enfant de la racine <request>. Vous pouvez ajouter une balise <notifications> sans faire de <push> et vice et versa, mais pouvez également utiliser une balise <notifications> et un <push> dans le même POST.

Les notifications sont fournies dans l’ordre de traitement par nos serveurs ; L’ordre peut donc être très différent de celui des contacts fournis dans la balise <recipients>. Chaque notification possède un identificateur séquentiel pour la différencier des autres.

Nota : Les attributs suivants sont optionnels :

• <login="demo" password="demo">
• <seek="id-notification">
• <max="100">

• media : « voice » ou « messaging » pour récupérer les notifications de vos push téléphoniques.
• seek : Optionnel ; S’il n’est pas fourni, le seek fera automatiquement référence à la première notification « non lue ». Sur le principe d’une Pile FIFO, tout élément lu ne réapparaîtra pas dans les lectures suivantes.Toutefois, si votre système de reporting venait à perdre un bloc de notification, seek vous permet de repositionner le pointeur à n’importe quel endroit dans la pile, et ainsi retrouver d’anciennes valeurs. Ce repositionnement permet par exemple de gérer 2 compteurs : un compteur temps réel et un autre compteur de vérification le soir à minuit.Le seek est l’id d’une notification ou « 0 » pour reprendre au tout début (attention les notifications ne sont conservées que 15 jours donc la valeur 0 signifie : reprendre l’analyse maximum 15 jours en arrière).
  Une fois le curseur repositionné, vous pouvez à nouveau omettre le seek lors des lectures suivantes afin de récupérer bloc par bloc les notifications.
• max : Optionnel ; Nombre de notifications à récupérer à chaque appel.

Exemple de notifications :

• target : numéro de téléphone ou mobile du destinataire.
• ref_target : est en rapport avec le « ref_target » unique passé dans chaque balise <add target>.
  ASTUCE : si votre <push> contient des « ref_target » uniques, vous pourrez alors facilement mettre à jour l’état de chacun de vos envois dans votre propre base de données !
• ref_group : est en rapport avec la propriété « name » du <push>.
• status : (4 valeurs possibles) : PROGRESS, SUCCESS, CANCEL et ERROR
  • SUCCESS correspond à une notification finale indiquant un envoi abouti/délivré
  • ERROR correspond à une notification finale indiquant un échec de l’envoi
  • CANCEL correspond à une notification finale indiquant un envoi non facturé (liste noire, liste anti-publicité, target mal formaté, etc.)
  • PROGRESS est une information temporaire sur l’avancée d’un envoi
    Par exemple : page 1 sur 5 d’un fax envoyée, page 2 sur 5 d’un fax envoyée, sms déposé chez l’opérateur mobile, numéro occupé, etc.
    Un envoi peu générer plusieurs notifications PROGRESS, mais donnera systématiquement lieu à une notification SUCCESS ou ERROR à la fin du traitement.

La balise <personnal_redlist> permet d’ajouter ou de retirer des numéros de fixes ou mobiles de votre liste rouge. La liste rouge permet de mémoriser tous les destinataires à qui notre plateforme audio n’enverra plus de communication même si [par erreur] vous ajoutiez ces destinataires dans un push marketing.

• media : « sms » pour mettre sur liste rouge un téléphone fixe ou un mobile.
  Notez que les listes rouges « voice » et « messaging » sont identiques (alias sur le nom).
• add : permet l’ajout d’un fax sur la liste rouge.
• remove : permet le retrait d’un fax de la liste rouge.
• target : numéro du téléphone (fixe ou mobile) à ajouter ou à supprimer de la liste rouge.
• comment : Optionnel ; Commentaire libre.