Envoi automatisé de SMS par HTTP

Intégrez dans vos développements web l'envoi de SMS grâce à notre API HTTP !

Connectez-vous à nos serveurs d'envoi de SMS en utilisant notre API HTTP

Pour pouvoir utiliser l'API veuillez ouvrir un compte, vous connecter puis l'activer en vous rendant sur "SMS" > "Mon Api"

API HTTP POST : Envoi de données XML

URL de notre serveur SMS "PRO" : https://sms.capitolemobile.com/api/sendsms/xml_v2

Les paramètres constituant le SMS sont passés dans une variable nommée "XML" devant contenir la structure de données suivante :


<SMS>



<authentification>

<username></username>

<password></password>

</authentification>



<message>

<text></text>

<sender></sender>

<route></route>

<long></long>

<prog></prog>

<id></id>

</message>



<recipients>

<gsm></gsm>

<gsm></gsm>

<gsm></gsm>

</recipients>



</SMS>

Authentification

username : Votre identifiant de connexion (login)
password : Votre mot de passe API (disponible via "SMS" > "Mon API" > "Paramètres API")

Message

text : Message du SMS
sender : (Optionnel) par défaut n° court ou bien sender personnalisé (11 caractères max.)
long : (Optionnel) par défaut "no", si "yes" concaténation de SMS possibles (jusqu'à 4 SMS)
route * : (Optionnel) "M" (envoi "Marketing"), "N" (envoi "Notification") par défaut
prog * : (Optionnel) date pour un envoi planifié (ultérieur). La date doit obligatoirement être écrite au format "aaaa-mm-jj hh:mm:ss"
id : (Optionnel) ID de campagne personnalisé (10 caractères max.) récupérable dans vos rapports de délivrabilité (accusés de réception / n° invalide), voir ci-dessous. IMPORTANT : le caractère "-" ne doit impérativement pas être présent dans l'ID de campagne.

* Si vous utilisez une route Marketing "M" (trafic publicitaire), une mention "STOP" (" STOP au 36XXX", 14 caractères) est automatiquement ajoutée en fin de message (en France Métropolitaine seulement). Veillez à prendre en compte cet ajout dans votre décompte de caractères.

Recipients

gsm : Numéro de téléphone (si l'indicatif international n'est pas indiqué, le numéro est considéré comme provenant de France Métropolitaine).

Exemple d'intégration PHP


<?php

// CapitoleMobile POST URL

$postUrl = "https://sms.capitolemobile.com/api/sendsms/xml_v2";

//Structure de Données XML

$xmlString = '<SMS>


<authentification>

<username>xxxxxxxxxxx</username>

<password>xxxxxxxxxxx</password>

</authentification>


<message>

<text>Hello World #param1# #param2# !</text>

<sender>Ma Marque</sender>

</message>


<recipients>

<gsm>0611223344</gsm>

<gsm>34622334455</gsm>

<gsm>633445566</gsm>

</recipients>


</SMS>';

// insertion du nom de la variable POST "XML" avant les données au format XML en UTF-8

$fields = "XML=" . urlencode(utf8_encode($xmlString));

// dans cet exemple, la requête POST est realisée grâce à la librairie Curl

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $postUrl);

curl_setopt($ch, CURLOPT_POST, 1);

curl_setopt($ch, CURLOPT_POSTFIELDS, $fields);

// Réponse de la requête POST

$response = curl_exec($ch);

curl_close($ch);

// Ecriture de la réponse

echo $response;

?>

Réponse à la requête HTTP POST

Lorsqu'un envoi est réalisé avec succès, en réponse à votre appel HTTP vous recevez un code : SENDING_OK

Dans le cas contraire vous recevez l'un des codes "erreur" suivant :

AUTH_FAILED : Erreur d'authentification (identifiant / mot de passe) ou l'option "API" désactivée
NO_RECIPIENT : Manque destinataire
NOT_ENOUGH_CREDITS : Solde insuffisant pour procéder à l'envoi
EMPTY_MESSAGE : Message vide
TOO_LONG_MESSAGE : Le message est trop long pour être envoyé (voir option "long")
_IS_BLACKLISTED : le numéro du destinatiaire apparaît dans votre blacklist
_IS_INVALID : Le numéro du destinataire est invalide
TOO_LONG_SENDER : (Avertissement) Le nom d'émetteur sélectionné est trop long (plus de 11 caractères). Il est automatiquement remplacé par un n° court.

En plus du code réponse, vous recevez l'état du solde de votre compte (ex : SENDING_OK;9542)

Préproduction : URL de Tests

Dans le cadre de votre implémentation, nous vous recommandons de procéder dans un premier temps à des appels vers notre URL de préproduction : https://sms.capitolemobile.com/api/sendsms/xml_test

Cette URL vous permet de récupérer en echo l'IP de votre serveur (à nous transmettre éventuellement pour autorisation) ainsi que la valeur de variable "XML" (contenant les paramètres du SMS) telle que nous la recevons. Ainsi vous pourrez vérifier que nous recevons bien la trame de données et qu'elle ne comporte aucune erreur (structurelle ou d'encodage).

IMPORTANT : Aucun SMS n'est envoyé lorsque vous réalisez des appels vers l'URL de préproduction. Elle ne sert qu'à vos tests d'intégration API.

Récupération des rapports de délivrabilité (accusés de réception)

Vous pouvez récupérer les statuts de délivrabilité de vos envois en nous communicant votre URL de callback.

Ces rapports vous sont remontés de la façon suivante : URLdeCallback?id=123456&gsm=336XXXXXXXX&status=DELIVERED&network=Orange&date=2020-03-10 09:20:10

id : ID de campagne passé (éventuellement) dans la requête d'envoi. IMPORTANT : le caractère "-" ne doit impérativement pas être présent dans l'ID de campagne.
gsm : numéro de mobile avec indicatif international
status : DELIVERED (si accusé de réception) ou INVALID_DESTINATION_ADDRESS (si erreur permanente opérateur)
network : nom de l'opérateur
date : au format yyyy-mm-jj hh:mm:ss

Récupération des réponses "directes" et des "STOP"

Vous pouvez récupérer les réponses "directes" et des "STOP" issus de vos envois en nous communicant votre URL de callback.

Ces éléments vous sont remontés de la façon suivante : URLdeCallback?num=33610203040&message=Hello+World

num : numéro de mobile avec indicatif international
message : message envoyé par l'utilisateur

IMPORTANT : il n'est possible de récupérer les réponses "directes" au SMS que dans le cas d'envois réalisés à destination de n° mobiles français métropolitains, sans personnalisation de l'émetteur (n° court, ex : "De : 36XXX"), et ce, durant un intervalle d'environ 48 heures suivant la date d'envoi du SMS.