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 : https://api.textinghouse.com.

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
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'
    }, 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'
  },
  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'
);
$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 https://api.textinghouse.com/, 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 » 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.
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.

 

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

 

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

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 sur une URL fournis par le client (callback URL).

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 : état du message (string) – liste des codes états : cf. Codage des statuts

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).

* 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"
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)
  • 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 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.
2 définitif Transmis à l’opérateur (envoi sans demande de statut uniquement)
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 Code 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é