Documentation de l’API SMS PRO

Si vous avez un besoin spécifique, contactez-nous !

1. Introduction

L’API HTTP constitue le moyen le plus simple à mettre en œuvre pour utiliser le portail de communication SMS de TextingHouse.

Cette interface peut-être utilisée aussi bien sous la forme de HTTP POST que d’URL GET.
Nous recommandons l’utilisation de POST si le volume de données est important, en effet le GET est limité en taille.

Les réponses de TextingHouse à ces requêtes sont des textes simples (content-type: text/plain; charset=utf-8).
Par exemple l’ID du SMS créé, le code du statut du SMS, la valeur du crédit, un code d’erreur… Elles sont insérées directement dans le corps HTTP de la réponse, sans balise particulière.

La communication avec notre API se fait en HTTPS sur le port 443.
Tous les appels à l’API doivent être “URL-encoded”.

Note : Il est important que l’ensemble du document soit lu avant de contacter le support.

Tous les exemples montrés dans ce document utilisent HTTP GET.

2. Pré-requis

Afin d’utiliser l’API d’envoi de SMS il vous faut au préalable un compte client actif et ayant un crédit positif sur les systèmes TextingHouse.
Les identifiants seront remplacés par ‘XXXX‘ dans les exemples de code qui suivent.

Pour s’inscrire, c’est par ici : Inscription – API TextingHouse.

3. Exemples

Ci-dessous des exemples d’implémentation basique pour l’envoi d’un SMS via l’API TextingHouse.

Les paramètres sont sensibles à la casse.

Exemple de commande de base GET
GET :
https://api.textinghouse.com/http/v1/do?user=XXXX&pass=XXXX&cmd=sendsms&to=999&txt=XXXXX&iscom=N
Exemple de retour :ID:5d726149a129c829e8c23f7b
Exemple Javascript - jQuery
jQuery.post() :
$.post('https://api.textinghouse.com/http/v1/do',
    {
        user: 'XXXX',
        pass: 'XXXX',
        cmd: 'sendsms',
        to: '999',
        txt: 'Mon SMS de test',
        iscom: 'N'
    }, function(data) {
        alert(data);
    });
Exemple Javascript - axios
axios :
const axios = require('axios');    

axios({
  method: 'post',
  url: 'https://api.textinghouse.com/http/v1/do',
  data: {
    user: 'XXXX',
    pass: 'XXXX',
    cmd: 'sendsms',
    to: '999',
    txt: 'Mon SMS de test',
    iscom: 'N'
  },
  responseType: 'text'
})
.then((res) => {
  console.log(res.data)
})
.catch((error) => {
  console.error(error)
});
Exemple PHP - cURL
cURL :
$data = array(
    'user' => 'XXXX',
    'pass' => 'XXXX',
    'cmd' => 'sendsms',
    'to' => '999',
    'txt' => 'Mon SMS de test',
    'iscom' => 'N'
);
$url = 'https://api.textinghouse.com/http/v1/do';
$ch = curl_init($url);
$postString = http_build_query($data, '', '&');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $postString);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

4. Fonctionnement de l’API

4.1 Authentification

Une fois votre compte créé sur l’API TextingHouse, vos identifiants sont disponibles sur la page « Paramètres » :

  • user : l’identifiant qui vous a été fourni pour l’api http TextingHouse
  • pass : le mot de passe associé à l’identifiant

Une restriction sur l’adresse IP peut également être ajoutée via la page « Paramètres », onglet « Vérouillage sur IP » de l’interface afin de n’autoriser les envois que depuis une adresse IP spécifique : celle-ci est conseillée.

4.2 Commandes

Les commandes sont spécifiées via le paramètre « cmd ». Les valeurs possibles sont :

 

Valeur cmdParamètres supplémentairesDescription
sendsmsouiCommande utilisée pour l’envoi de SMS.
Cf. Envoi d’un message
getstatusouiPermet d’obtenir le statut d’un message via son ID.
Cf. Demande de statut
getcreditnonPermet d’obtenir le crédit du compte client.
Cf. Consultation du crédit

4.3 Envoi d’un message

L’envoi d’un message se fait en utilisant la commande « sendsms » :

&cmd=sendsms

 

Les paramètres de la commande « sendsms » sont les suivants :

 

ParamètreObligatoireDescription
toouiNuméro de téléphone du destinataire préfixé par l’indicatif international du pays
Ex : 33 pour la France
txtoui

Texte du message.
Le texte doit être « URL Encoded ».
Noter que certains caractères spéciaux peuvent êtres remplacés selon le réseau de destination du SMS.
Pattern JavaScript représentant les caractères autorisés :

/[ 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZÄäàÅåÆæßÇèéÉìÖöòØøÑñÜüù#¤%&()*+,\-./:;<>=§$!?£¿·@¡\'"\n\\[\]{}~^|]/

Cf. la norme GSM 03.38

climsgidnonId client du message
Défini par le client pour obtenir un suivi.
Jusqu’à 32 caractères.
fromnon

Permet de personnaliser l’émetteur du SMS.

La personnalisation du nom d’expéditeur est restreinte à un ensemble de noms autorisés pour votre compte. Les demandes se font via la page « Paramètres » de l’interface API.

Limité à 11 caractères non accentués (a-zA-Z0-9).

La personnalisation du nom d’expéditeur n’étant pas possible pour certaines destinations (restriction technique de certains opérateurs) TextingHouse se réserve le droit de remplacer l’émetteur choisi par le client au moment de l’envoi.

iscomoui

Indique s’il s’agit d’un message à caractère commercial ou non.

Valeur possible :

  • ‘Y’ pour : Oui, c’est un message à caractère commercial
  • ‘N’ pour : Non ce n’est pas un message commercial

 

Les messages à caractère commerciaux doivent obligatoirement être envoyés les jours ouvrés et en journée. Les créneaux autorisés (selon l’heure locale du destinataire) sont par conséquent les suivants :

  • du lundi au vendredi entre 8h et 20h,
  • le samedi entre 10h et 15h.

Les SMS à caractères commerciaux émis en dehors des plages horaires autorisées seront retenus et envoyés à la prochaine heure ouvrée sans que le client ne puisse émettre de réclamation ou annulation d’envois.

Chaque message à caractère commercial doit également obligatoirement :

  • préciser l’identité de l’annonceur,
  • proposer un moyen simple de s’opposer à la réception de nouvelles sollicitations. 

Voir détail ci-dessous : SMS à caractère commercial / marketing

 

Exemple d’envoi du SMS contenant le message « SMS accentué de test via TextingHouse » au numéro français 06 28 00 00 00 avec l’id client « FRS78913246 » :

https://api.textinghouse.com/http/v1/do?user=XXXX&pass=XXXXXX&cmd=sendsms&to=33628000000&txt=SMS%20accentu%C3%A9%20de%20test%20via%20TextingHouse&climsgid=FRS78913246&from=test&iscom=N

 

Réponse :

ID:<api_id> (ID fournit par TextingHouse)
Exemple :ID:5d726149a129c829e8c23f7b

Suite à un envoi, l’API fournit l’id du message, ce qui atteste de la bonne prise en charge du message. Cet ID vous sera nécessaire pour corréler la remontée des statuts et les messages envoyés.

 

Ou, en cas d’erreur :

ERR: <code_erreur> | description erreur
Exemple :ERR: 101 | Authentication failed

En cas d’erreur les codes suivant sont à prendre en considération :

Code erreurDescription
100Paramètre manquant
101Échec de l’authentification : nom d’utilisateur, mot de passe ou adresse IP invalide
104Crédit insuffisant
350Stop flooding.
Un seul message (même contenu même numéro de téléphone) par destinataire est autorisé par tranche de 10 secondes. Au-delà de cette limite, l’API renvoi cette erreur.

 

SMS à caractère commercial / marketing

Le paramètre « iscom » (obligatoire) de la commande « sendsms » vous permet d’indiquer si votre SMS est à caractère commercial (ou marketing), ou bien s’il s’agit d’un message de service.

 

Rappel des règles de la CNIL concernant les SMS à caractères commerciaux :

La publicité par SMS est possible en France à condition que les personnes aient explicitement donné leur accord pour être démarchées, au moment de la collecte de leur numéro de téléphone portable.

Chaque message à caractère commercial doit obligatoirement :

  • préciser l’identité de l’annonceur,
  • proposer un moyen simple de s’opposer à la réception de nouvelles sollicitations (STOP SMS).

 

STOP SMS

TextingHouse vous permet de collecter automatiquement les STOP SMS via l’URL : sms-s.top

Pour permettre à vos destinataires de se désabonner de vos communications, ajouter par exemple à la fin du texte de votre SMS : STOP sms-s.top

 

Restrictions horaires :

Les règles en matière de prospection par SMS définissent que les messages à caractère commerciaux doivent obligatoirement être envoyés les jours ouvrés et en journée. Les créneaux autorisés par TextingHouse sont par conséquent les suivants :

  • du lundi au vendredi entre 8h et 20h
  • le samedi entre 10h et 15h

Les SMS à caractère commerciaux émis en dehors des plages horaires autorisées seront retenus et envoyés à la prochaine heure ouvrée sans que le client ne puisse émettre de réclamation ou annulation d’envois.

 

Coût des SMS

Chaque SMS transmis à l’API (sauf les SMS de tests envoyés au 999), est facturé selon le tarif en vigueur au moment de l’envoi. Si le SMS dépasse 160 caractères, chaque SMS supplémentaire sera décompté selon le découpage du SMS (cf. FAQ Longueur d’un SMS, quelle longueur de message puis-je envoyer par SMS ?).

4.4 Demande de statut

Nous recommandons l’utilisation de la remontée automatique des statuts via l’URL de callback : cf. Remontée des statuts.

Il est cependant possible de demander le statut d’un message en précisant son ID TextingHouse ou son ID client avec la commande « getstatus » :

&cmd=getstatus

Les paramètres sont les suivants :

ParamètreDescription
api_idId TextingHouse renvoyé par l’API lors de l’envoi
climsgidId client fournit lors de l’envoi

Si les deux paramètres sont renseignés, seul l’api_id sera pris en compte.

Exemple :

https://api.textinghouse.com/http/v1/do?user=XXXX&pass=XXXXXX&cmd=getstatus&api_id=1c97394eea5806c0741be3601d8fca0b

Ou

https://api.textinghouse.com/http/v1/do?user=XXXX&pass=XXXXXX&cmd=getstatus&climsgid=FRS78913246

Retour :

<code_statut>
Exemple :
3

Code états : cf. Codage des statuts

Code erreur :

Code erreurDescription
100Paramètre manquant
101Échec de l’authentification : nom d’utilisateur, mot de passe ou adresse IP invalide
201api_id inconnu
202climsgid inconnu

4.5 Remontée des statuts

L’API TextingHouse va remonter les statuts sous la forme d’un HTTP POST sur une URL fournis par le client (callback URL). La configuration de cette URL se fait sur l’interface API page « Paramètres », onglet « Callbacks DLR et MO ».

Par exemple si l’URL de callback renseignée est https://www.mondomaine.com/monscript.do. La requête effectuée par TextingHouse sera de la forme :

POST https://www.mondomaine.com/monscript.do
apimsgid: "5d726149a129c829e8c23f7b"
climsgid: "FR-6468446"
status: "3"

Avec les paramètres suivants :

  • apimsgid : ID fournis par l’api TextingHouse (string)
  • climsgid : ID éventuellement fournis par le client (string)
  • status : Code statut définitif (string) – Liste des codes statuts des SMS : cf. Codage des statuts

Seuls les status définitifs (cf. Codage des statuts) sont remontés. Les statuts temporaires ne sont pas envoyé via l’URL de callback. Ils sont cependant remontés lors d’une demande de statut classique via la commande « getstatus ».

Le script coté client doit répondre ‘ok’ dans le corps de la réponse HTML, sans autre balisage afin d’acquitter la prise en charge du statut reçu.

4.6 Remontée des réponses SMS (SMS MO)

L’API peut remonter les réponses au SMS* sous la forme d’un HTTP POST sur une URL fournie par le client (SMSMO callback URL). La configuration de cette URL se fait sur l’interface API page « Paramètres », onglet « Callbacks DLR et MO ».

* Selon les opérateurs et les pays d’envoi. Attention, lorsqu’un nom d’expéditeur est utilisé (paramètre from de la commande sendsms), les destinataires ne peuvent pas répondre aux SMS.

Par exemple, si l’URL de callback renseignée est https://www.mondomaine.com/monscript.do, la requête effectuée par TextingHouse sera de la forme :

POST https://www.mondomaine.com/monscript.do
apimsgid: "5d726149a129c829e8c23f7b"
climsgid: "FR-6468446"
from: "33600000000"
txt: "Texte du message"
date: "2020-06-01 14:49:05"

Avec les paramètres suivants :

  • apimsgid : ID fournis par l’api TextingHouse (string)
  • climsgid : ID éventuellement fournis par le client (string)
  • from : numéro de téléphone de l’émetteur du message (string)
  • txt : le message (string)
  • date : date UTC du message au format YYYY-MM-DD HH:mm:ss (string)

4.7 Consultation du crédit

La consultation du crédit se fait en utilisant la commande getcredit :

&cmd=getcredit
Exemple :
https://api.textinghouse.com/http/v1/do?user=XXXX&pass=XXXXXX&cmd=getcredit

Retour :

<valeur>
Exemple :
1423

4.8 SMS de test au 999

L’envoi d’un SMS sur le numéro 999 est un moyen simple de tester l’API que ce soit pour les développements comme pour le monitoring du service.

L’envoi d’un SMS à ce numéro est soumis à authentification comme pour l’envoi d’un SMS standard vers un destinataire « classique ». A noter que les SMS envoyés au 999 ne sont pas facturés.

L’API va prendre en charge ces tests de la même manière que les SMS standards (cf. paragraphes Envoi d’un message, Demande de statut et Remontée des statuts), cela implique notamment :

  • Le retour d’un id de message.
  • La prise en charge de vos id internes (facultatif).
  • La remontée d’un accusé réception en état « délivré ». A noter que cet accusé de réception virtuel est généré à des fin de test (le SMS n’étant pas remis à un opérateur) mais traduit néanmoins le bon fonctionnement de notre chaine d’envoi et notamment la communication entre les frontaux API et nos plateformes d’envois.
  • La réponse à interrogation de statut sur cet ID de message.

Le contenu du SMS de test est libre et non pris en compte.

5. Annexes

5.1 Codage des statuts

Code statutType statutDescription
0temporaireMessage pris en charge par l’API, traitement en cours.
1temporaireEn cours : SMS pris en charge, en attente d’un statut définitif.
3définitifDélivré
4définitifExpiré ou hors d’atteinte
5définitifNon abonné
6définitifNon délivrable
7définitifEnvoi impossible
20définitifEnvoi bloqué car crédit insuffisant

5.2 Code erreur

Code erreurDescription
100Paramètres manquants
101Échec de l’authentification : nom d’utilisateur, mot de passe ou adresse IP invalide
104Crédit insuffisant
201api_id inconnu
202climsgid inconnu
300Erreur de traitement de la requête
350

Flood détecté.

Un seul message (même contenu même numéro de téléphone) par destinataire est autorisé par tranche de 10 secondes. Au-delà de cette limite, l’API renvoi cette erreur.