Documentation de l’API SMS PRO

Tester l'API

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

Versions

Num Modifications Date d’application
1.0.0 Version initiale
1.1.0
  • Les messages commerciaux doivent obligatoirement comporter la mention ‘STOP sms-s.top’.
  • Ajout du code d’erreur 400 – Mention STOP manquante
 16/12/2021
1.1.1 11/07/2022

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
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 cmd Paramètres supplémentaires Description
sendsms oui Commande utilisée pour l’envoi de SMS.
Cf. Envoi d’un message
getstatus oui Permet d’obtenir le statut d’un message via son ID.
Cf. Demande de statut
getcredit non Permet 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ètre Obligatoire Description
to oui Numéro de téléphone du destinataire préfixé par l’indicatif international du pays
Ex : 33 pour la France
txt oui 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.
Cf. 5.3 Caractères autorisés dans les SMS
climsgid non Id client du message
Défini par le client pour obtenir un suivi.
Jusqu’à 32 caractères.
from non

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.
iscom oui

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 envois commerciaux le dimanche et les jours fériés ne sont pas autorisés.

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,
  • comporter la mention ‘STOP sms-s.top’. 

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>

api_id est l’ID unique 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 erreur Description
100 Paramètre manquant
101 Échec de l’authentification : nom d’utilisateur, mot de passe ou adresse IP invalide
104 Crédit insuffisant
350 Stop 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.
400

Mention STOP manquante

Le message est commercial mais la mention `STOP sms-s.top` est absente.

 

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 (une mention de STOP),
  • n’être envoyé que les jours ouvrés et en journée.

 

STOP SMS

Tous les SMS commerciaux (iscom=Y) doivent comporter la mention ‘STOP sms-s.top’ à la fin du texte de votre message.

TextingHouse collectera alors automatiquement les STOP de vos destinataires pour leur permettre de se désabonner de vos communications.

Si un SMS commercial ne comporte pas la mention ‘STOP sms-s.top’, il sera refusé (erreur 400).

 

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 envois commerciaux ne sont pas autorisés le dimanche ni les jours fériés.

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ètre Description
api_id Id TextingHouse renvoyé par l’API lors de l’envoi
climsgid Id 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 erreur Description
100 Paramètre manquant
101 Échec de l’authentification : nom d’utilisateur, mot de passe ou adresse IP invalide
201 api_id inconnu
202 climsgid inconnu

4.5 Remontée des statuts

L’API TextingHouse va remonter les statuts sous la forme d’un HTTP POST contenant le statut au format JSON 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 HTTP/1.1
Content-Type: application/json

{
  "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 par un statut HTML du type 2XX. Le corps de la réponse n’est pas traité par TextingHouse.

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 contenant la réponse SMS au format JSON 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 HTTP/1.1
Content-Type: application/json

{
  "apimsgid": "5d726149a129c829e8c23f7b",
  "climsgid": "FR-6468446",
  "from": "33600000000",
  "txt": "Texte du message",
  "date": "2019-04-01T13:09:16Z"
}

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 ISO 8601 : ‘YYYY-MM-DDTHH:mm:ssZ’ (string)

Le script coté client doit répondre par un statut HTML du type 2XX. Le corps de la réponse n’est pas traité par TextingHouse.

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 Codes des statuts

Code statut Type statut Description
0 temporaire Message pris en charge par l’API, traitement en cours.
1 temporaire En cours : SMS pris en charge, en attente d’un statut définitif.
3 définitif Délivré
4 définitif Expiré ou hors d’atteinte
5 définitif Non abonné
6 définitif Non délivrable
7 définitif Envoi impossible
20 définitif Envoi bloqué car crédit insuffisant

5.2 Codes d’erreur

Code erreur Description
100 Paramètres manquants
101 Échec de l’authentification : nom d’utilisateur, mot de passe ou adresse IP invalide
104 Crédit insuffisant
201 api_id inconnu
202 climsgid inconnu
300 Erreur 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.
400

Mention STOP manquante

Le message est commercial mais la mention `STOP sms-s.top` est absente.

 

5.3 Caractères autorisés dans les SMS

Pattern JavaScript représentant les caractères autorisés :

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

Cf. la norme GSM 03.38