Utiliser l’API HTTP¶

À quoi ça sert ?¶

L’API HTTP de RaspiSMS vous permet d’intégrer facilement les fonctionnalitées d’envoi et de récéption de SMS de RaspiSMS au sein d’une autre application. Vous pouvez par exemple utiliser l’API de RaspiSMS afin d’envoyer des SMS de confirmation ou d’alerte depuis une application tierce.

Organisation de l’API¶

Fonctionnalités¶

L’API de RaspiSMS est découpée en trois principales fonctionnalités, chacune d’entre elle correspondant à un verbe HTTP dédié :

Lister des ressources (sms envoyés, reçus et programmés, contacts, etc.), verbe HTTP GET.
Créer une ressource (sms programmé, téléphone), verbe HTTP POST.
Supprimer une ressource (sms programmé, téléphone), verbe HTTP DELETE.

Note

Actuellement seul les SMS programmés et les téléphones peuvent être créés et supprimés via l’API.

Format des réponses¶

Toutes les réponses des API sont un tableau associatif au format JSON. Les réponses respectent toutes le format ci-dessous.

Format des réponses¶
Clé	Description
error	Code d’erreur, `0` si pas d’erreur.
message	Message décrivant l’erreur si une erreur est survenue. Sinon `NULL`.
response	Réponse de la requête, différent pour chaque requête.
next	Lien vers la page suivante s’il reste des résultats à affichées pour la requête. Sinon `NULL`.
prev	Lien vers la page précédente si la requête actuelle utilise la pagination. Sinon `NULL`.

Codes d’erreurs¶

L’API utilise les codes d’erreurs suivants.

Format des réponses¶
Code	Description
0	Pas d’erreur.
1	Identifiant invalide (vous devez fournir une clé API valide).
2	Un paramètre non valide a été fourni.
4	Un paramètre manquant n’a pas été fourni.
8	Impossible de créer la ressource demandée.
16	Le compte lié à la clé API est suspendu.
32	Impossible de supprimer la ressource indiquée.

Pagination¶

Pour les requêtes susceptibles d’employer de la pagination (c’est-à-dire les requêtes de type liste), les résultats sont renvoyés par groupe de 25. Si des résultats supplémentaires sont disponibles un champ next avec l’URL à intérroger pour obtenir les résultats suivants est indiqué dans la réponse. Sinon le champ est défini à NULL.

Obtenir et utiliser une clé API¶

Pour effectuer une requête sur l’API, vous devez fournir une clé unique permettant de vous authentifier.

Avertissement

Votre clé API est un identifiant à part entière, vous ne devez en aucun cas la rendre publique !

Si cette clé a été rendue publique vous devriez l’invalider et en générer une nouvelle via le bouton « Générer une nouvelle clef API » dans la partie « Mon profil » de RaspiSMS.

Trouver la clé API¶

Vous pouvez trouver votre clé API dans la partie « Mon profil » de RaspiSMS, dans l’encadré « Mes données ».

Transmettre la clé API¶

Vous devez transmettre votre clé API avec chaque requête sans quoi celle-ci sera rejetée. Pour cela il vous suffit de renseigner votre clé API sous la forme d’un paramètre de GET ou POST nommé api_key, ou bien d’un header HTTP nommé X-Api-Key.

Lister des ressources – `GET`¶

Endpoints :

/api/list/{entry_type}/
/api/list/{entry_type}/{page}/

Arguments :

entry_type (str) – Le type de ressource à lister (sended, received, scheduled, contact, group, conditional_group, phone, phone_group ou media).
page (int), optional – Numéro de page à utiliser, si non défini 0.

Réponse :

Une collection JSON des ressources demandées.

HTTP Code :

Success : 200
Error : 404

Obtenir le nombre de SMS envoyés – `GET`¶

Endpoints :

/api/usage

Arguments :

start (str), optional – La date à patir de laquelle lire le nombre de SMS envoyés, au format Y-m-d H:i:s. Si non défini pas de date de début.
end (str), optional – La date jusqu’à laquelle lire le nombre de SMS envoyés, au format Y-m-d H:i:s. Si non défini pas de date de fin.
tag (str), optional – Filtre les SMS pour garder uniquement les SMS envoyés avec un tag correspondant. Le tag sera comparé via une requête SQL LIKE. Vous pouvez donc cherchez des tags partiels en utilisant les caractères % et _. Si non défini tous les tags seront conservés.

Réponse :

Un objet JSON avec le nombre total de SMS et le nombre de SMS par téléphone avec en clé l’ID du téléphone.

HTTP Code :

Success : 200
Error : 404

Exemple de requête CURL¶

On va récupérer le nombre de SMS envoyés entre le 1 février 2023 et le 28 février 2023, avec un tag commençant par campaign.

curl 'https://app.raspisms.fr/api/usage/?start=2023-02-01+00:00:00&end=2023-02-28+00:00:00&tag=campaign%' -H 'X-Api-Key: ac122e8d46faac0615c181b93d07612d'

{
    "error" : 0,
    "message" : null,
    "next" : null,
    "prev" : null,
    "response" : {
       "phones_volumes" : {
          "1" : 3,
          "43" : 1,
          "46" : 1,
          "50" : 0
       },
       "total" : 5
    }
 }

Supprimer un SMS programmé – `DELETE`¶

Endpoints :

/api/scheduled/{id}/

Arguments :

id (str) – L’identifiant unique du SMS programmé à supprimer.

Réponse :

True on success.

HTTP Code :

Success : 204
Error : 400

Exemple de requête CURL¶

On va supprimer le SMS programmé avec l’id 13.

curl -X DELETE https://app.raspisms.fr/api/scheduled/13 -H 'X-Api-Key: ac122e8d46faac0615c181b93d07612d'

Créer un SMS programmé – `POST`¶

Endpoints :

/api/scheduled/

Arguments :

text (str) – Le texte du SMS à envoyer.
numbers (array | str), optional – Un numéro de téléphone au format international auquel envoyer le SMS ou un tableau de numéros. Pour chaque numéro il est possible de passer à la place un tableau avec les clés number et data, où number est le numéro cible, et data une chaine JSON de données au format clé => valeur (voir contacts enrichies <extended_contacts>) à utiliser au sein du message via le templating <templating>.
contacts (array | int), optional – L’ID du contact auquel envoyer le SMS ou un tableau d’IDs.
groups (array | int), optional – L’ID du groupe auquel envoyer le SMS ou un tableau d’IDs.
conditional_groups (array | int), optional – L’ID du groupe conditionnel auquel envoyer le SMS ou un tableau d’IDs.
at (str), optional – Date à laquelle envoyer le SMS au format Y-m-d H:i:s. Si non défini utilise la date actuelle.
id_phone (str), optional – Identifiant du téléphone avec lequel envoyer le SMS. Si non défini et que id_phone_group est aussi non défini, utilise un téléphone au hasard.
id_phone_group (str), optional – Identifiant du groupe de téléphone avec lequel envoyer le SMS.Si non défini et que id_phone est aussi non défini, utilise un téléphone au hasard.
flash (bool), optional – TRUE s’il s’agit d’un SMS flash. Si non défini FALSE.
mms (bool), optional – TRUE si le message est un MMS. Si non défini FALSE.
tag (string), optional – Un tag qui sera associé à tous les SMS. Utile pour associer une campagne à un identifiant unique de votre système. Si non défini NULL.
medias (multipart-form file array | multipart-form file) optional – Un ou plusieurs fichiers à inclure dans le MMS. Toute requête contenant des medias doit être au format multipart/form-data. Les medias ne seront utilisés que si le paramètre mms est défini à TRUE. Pour envoyer plusieurs fichiers, utilisez une série de paramètres medias[].
numbers_csv (multipart-form file) optional – Un fichier CSV de numéros de téléphones qui auxquels seront envoyer le SMS. Le fichier doit respecter le format décrit dans la page sur l’envoi de SMS à un fichier CSV <sms_csv>

Note

Les arguments numbers, contacts, groups et conditional_groups sont tous optionnels individuellement, mais vous devez nécessairement renseigner au moins un de ces arguments.

Tous ces arguments peuvent être transmis avec une seule valeur ou comme un tableau de valeurs.

Réponse :

L’ID du SMS programmé créé.

HTTP Code :

Success : 200
Error : 400

Exemple de requêtes CURL¶

Exemple 1¶

Création d’un SMS « Mon SMS d’exemple » envoyé immédiatement au numéro « +33612345678 ».

curl -X POST https://app.raspisms.fr/api/scheduled/ -H 'X-Api-Key: ac122e8d46faac0615c181b93d07612d' -d 'text=Mon%20SMS%20d%27exemple' -d 'numbers=%2B33612345678'

{
   "error":0,
   "message":null,
   "response":60,
   "next":null,
   "prev":null
}

Exemple 2¶

Création d’un SMS « Mon SMS d’exemple » à envoyer le « Jeudi 17 juin 2020 à 15 heures, 30 minutes, 25 secondes », aux contacts avec l’ID 11 et 12, avec le téléphone avec l’ID 3.

curl -X POST https://app.raspisms.fr/api/scheduled/ -H 'X-Api-Key: ac122e8d46faac0615c181b93d07612d' -d 'text=Mon%20SMS%20d%27exemple' -d contacts[]=11' -d 'contacts[]=12' -d 'id_phone=3' -d 'at=2020-06-17 17:30:25'

{
   "error":0,
   "message":null,
   "response":62,
   "next":null,
   "prev":null
}

Exemple 3¶

Création d’un MMS « Mon MMS d’exemple » à envoyer immédiatement au « +33612345678 » avec les fichiers « example1.png » et « example2.png ».

curl https://app.raspisms.fr/api/scheduled/ -H 'X-Api-Key: ac122e8d46faac0615c181b93d07612d' -F "text=Mon SMS d'exemple" -F 'numbers=+33612345678' -F 'mms=1' -F 'medias[]=@example1.png' -F 'medias[]=@example2.png'

{
   "error" : 0,
   "message" : null,
   "next" : null,
   "prev" : null,
   "response" : 39
}

Exemple 4¶

Création d’un SMS à envoyer immédiatement aux numéros listés dans le fichier CSV « sms_csv.csv » ci-dessous.

0,lastname,firstname,birthdate,gender,vip
"+33612345678",Doe,John,1990-10-22,male,1
"+33612345679",Doe,Jane,1992-08-15,female,0

curl -X POST https://app.raspisms.fr/api/scheduled/ -H 'X-Api-Key: ac122e8d46faac0615c181b93d07612d' -F 'text=Bonjour {{contact.firstname}}' -F 'numbers_csv=@sms_csv.csv'

{
   "error" : 0,
   "message" : null,
   "next" : null,
   "prev" : null,
   "response" : 98
}

Exemple 5¶

Création d’un SMS « Bonjour {{contact.firstname}} » envoyé immédiatement aux numéro « +33612345678 » et « +33612345679 » ou {{contact.firstname}} sera remplacé par les données liées aux numéros, à savoir John et Jane.

curl -X POST https://app.raspisms.fr/api/scheduled/ -H 'X-Api-Key: ac122e8d46faac0615c181b93d07612d' -d 'text=Bonjour {{contact.firstname}}' -d 'numbers[0][number]=%2B33612345678' -d 'numbers[0][data]={"firstname":"John", "lastname":"Doe"}' -d 'numbers[1][number]=%2B33612345679' -d 'numbers[1][data]={"firstname":"Jane", "lastname":"Doe"}'

{
   "error" : 0,
   "message" : null,
   "next" : null,
   "prev" : null,
   "response" : 101
}

Supprimer un téléphone – `DELETE`¶

Endpoints :

/api/phone/{id}/

Arguments :

id (str) – L’identifiant unique du téléphone à supprimer.

Réponse :

True on success.

HTTP Code :

Success : 204
Error : 400

Exemple de requête CURL¶

On va supprimer le téléphone avec l’id 42.

curl -X DELETE https://app.raspisms.fr/api/phone/42 -H 'X-Api-Key: ac122e8d46faac0615c181b93d07612d'

Créer un téléphone – `POST`¶

Endpoints :

/api/phone/

Arguments :

name (str) – Le nom du téléphone (doit être unique).
adapter (str) – Le nom de l’adaptateur logiciel du téléphone. C’est la classe PHP de l’adaptateur, avec son espace de nom.
priority (int), optional – La priorité d’utilisation du téléphone (voir). Si non défini 0.
limits (array), optional – Les limites d’envois pour le téléphone (voir). Si non défini []. C’est un tableau de limites, ou chaque limite est représentée par un tableau avec les clés :
- volume (int) – Le nombre de SMS max sur la période.
- startpoint (str) – Une chaine de caractère représentant une date relative PHP qui sera utilisée comme date de début à partir de laquelle calculer le nombre de SMS envoyés par rapport à la limite (valeures conseillées : today, -24 hours, this week midnight, -7 days, this week midnight -1 week, -14 days, this month midnight, -1 month, -28 days, -30 days, -31 days).
adapter_data (array), optional – Les données de configuration nécessaires pour le téléphone (clés API, fichier de conf, etc.). Le contenu change selon l’adaptateur logiciel du téléphone (voir la fonction meta_data_fields <developpers_adapters_overview>).

Note

Pour voir les données adapter_data à fournir, le plus simple est de lire le code de la méthode meta_data_fields de l’adaptateur logiciel pour lequel vous souhaitez créer un téléphone.

Réponse :

L’ID du téléphone créé.

HTTP Code :

Success : 200
Error : 400

Exemple de requêtes CURL¶

Exemple 1¶

Création d’un téléphone « Test phone » avec l’adaptateur Test. Aucune configuration supplémentaire n’est nécessaire pour ce type d’adaptateur.

curl -X POST https://app.raspisms.fr/api/phone/ -H 'X-Api-Key: ac122e8d46faac0615c181b93d07612d' -d 'name=Test phone' -d 'adapter=adapters\TestAdapter'

{
   "error":0,
   "message":null,
   "response":19,
   "next":null,
   "prev":null
}

Exemple 2¶

Création d’un téléphone « My Octopush Phone » » avec l’adaptateur « `Octopush Shortcode <users_adapters_octopush_shortcode>` ». Cet adaptateur nécessite de configurer le login et l”api_key du compte Octopush à utiliser.

curl -X POST http://127.0.0.1/raspisms/api/phone/ -H 'X-Api-Key: ac122e8d46faac0615c181b93d07612d' -d 'name=My Octopush Phone' -d 'adapter=adapters\OctopushShortcodeAdapter' -d 'adapter_data[login]=mail@example.com' -d 'adapter_data[api_key]=4Vnc9rDqFcJxp6ywBMtIydtFEsQ0J13RXG8Ms96F'

{
   "error":0,
   "message":null,
   "response":20,
   "next":null,
   "prev":null
}

Exemple 3¶

Création d’un téléphone « Test phone » avec l’adaptateur Test, une priorité de 2, une limite de 100 sms par jour et une deuxième limite de 500 sms dans la semaine.

curl -X POST https://app.raspisms.fr/api/phone/ -H 'X-Api-Key: ac122e8d46faac0615c181b93d07612d' -d 'name=Test phone' -d 'adapter=adapters\TestAdapter' -d "priority=2" -d 'limits[0][volume]=100' -d 'limits[0][startpoint]=today' -d 'limits[1][volume]=500' -d 'limits[1][startpoint]=this week midnight'

{
   "error":0,
   "message":null,
   "response":21,
   "next":null,
   "prev":null
}

Mettre à jour le status d’un téléphone – `POST`¶

Cette requête un peu particulière vous permet de forcer la vérification et la mise à jour du status d’un téléphone.

Endpoints :

/api/phone/{id}/status/

Arguments :

id (int) – L’identifiant du téléphone dont on veut mettre à jour le status.

Réponse :

Le nouveau status du téléphone parmis available, unavailable, no_credit, limit_reached.

HTTP Code :

Success : 200
Error : 400

Exemple de requêtes CURL¶

Mise à jour du status du téléphone avec l’id 50.

curl -X POST https://app.raspisms.fr/api/phone/50/status -H 'X-Api-Key: ac122e8d46faac0615c181b93d07612d'

{
    "error" : 0,
    "message" : null,
    "next" : null,
    "prev" : null,
    "response" : "available"
}

Utiliser l’API HTTP¶

À quoi ça sert ?¶

Organisation de l’API¶

Fonctionnalités¶

Format des réponses¶

Codes d’erreurs¶

Pagination¶

Obtenir et utiliser une clé API¶

Trouver la clé API¶

Transmettre la clé API¶

Lister des ressources – GET¶

Obtenir le nombre de SMS envoyés – GET¶

Exemple de requête CURL¶

Supprimer un SMS programmé – DELETE¶

Exemple de requête CURL¶

Créer un SMS programmé – POST¶

Exemple de requêtes CURL¶

Exemple 1¶

Exemple 2¶

Exemple 3¶

Exemple 4¶

Exemple 5¶

Supprimer un téléphone – DELETE¶

Exemple de requête CURL¶

Créer un téléphone – POST¶

Exemple de requêtes CURL¶

Exemple 1¶

Exemple 2¶

Exemple 3¶

Mettre à jour le status d’un téléphone – POST¶

Exemple de requêtes CURL¶

Lister des ressources – `GET`¶

Obtenir le nombre de SMS envoyés – `GET`¶

Supprimer un SMS programmé – `DELETE`¶

Créer un SMS programmé – `POST`¶

Supprimer un téléphone – `DELETE`¶

Créer un téléphone – `POST`¶

Mettre à jour le status d’un téléphone – `POST`¶