Envoyer un SMS
Si vous souhaitez automatiser l'envoi de notifications et de SMS marketing, vous pouvez appeler cette API. Indiquez l'ID du modèle de SMS ainsi que les destinataires cibles, et le système enverra automatiquement les SMS selon le contenu du modèle.
Conseil de configuration de la plateforme Avant d'effectuer l'appel, vous devez réaliser les configurations suivantes dans la console EngageLab SMS :
- Paramétrage du modèle de SMS : avant d'appeler l'API, rendez-vous dans Gestion des modèles pour personnaliser et soumettre un modèle de SMS. Le modèle doit être validé avant que son ID puisse être utilisé.
- Configuration de la clé API : rendez-vous dans API Key pour créer une clé d'authentification API Basic.
Adresse d'appel
POST https://smsapi.engagelab.com/v1/messages
Authentification
Veuillez consulter Authentification pour savoir comment authentifier les requêtes API.
Exemple de requête
En-tête de la requête
POST /v1/messages HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
POST /v1/messages HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
Afficher ce bloc de code dans la fenêtre flottante
Corps de la requête
{
"to": [
"923700056581"
],
"template": {
"id": "1233",
"params": {
"content": "Verification code: 039487. This code will expire in 5 minutes. You are attempting to create your account."
}
}
}
{
"to": [
"923700056581"
],
"template": {
"id": "1233",
"params": {
"content": "Verification code: 039487. This code will expire in 5 minutes. You are attempting to create your account."
}
}
}
Afficher ce bloc de code dans la fenêtre flottante
Paramètres de requête
Un objet de requête est exprimé au format JSON ; l'en-tête de la requête doit donc inclure Content-Type: application/json.
| Paramètre | Type | Option | Description |
|---|---|---|---|
| to | Array[String] | Obligatoire | Liste des numéros de téléphone cibles, par exemple ["923700056581"] |
| plan_name | String | Facultatif | Nom du plan ; affiche « - » par défaut s'il n'est pas renseigné |
| schedule_time | Integer | Facultatif | Heure de l'envoi programmé. Ne transmettez pas ce paramètre pour un envoi non programmé. Horodatage Unix, exprimé en « secondes ». Règles de validation : doit être un nombre positif ; doit être strictement postérieur à l'heure actuelle d'au moins 3 minutes ; ne peut pas dépasser 30 jours à compter de l'heure actuelle. |
| template | JSON Object | Obligatoire | Informations du modèle ; voir ci-dessous pour les paramètres de second niveau |
| |_ id | String | Obligatoire | ID du modèle |
| |_ params | JSON Object | Obligatoire | Valeurs des clés de variables personnalisées du modèle Si vous avez défini des variables lors de la création du modèle, transmettez-leur ici leurs valeurs. Si elles ne sont pas transmises, elles seront envoyées telles quelles sous forme de clés de variable, par exemple {{var1}} |
| custom_args | JSON Object | Facultatif | Paramètres personnalisés |
À propos de params
Tous les champs de variable personnalisés présents dans le contenu du modèle au moment de sa création doivent recevoir une valeur via params. Par exemple, si le contenu du modèle est Hi {{name}}, welcome to EngageLab, vous devez alors affecter le paramètre params: {"name": "Bob"}.
Autres exemples de requête
1. Envoyer un contenu de notification personnalisé :
{
"to": ["+6591234567"],
"template": {
"id": "notification-template",
"params": {
"order": "123456"
}
}
}
{
"to": ["+6591234567"],
"template": {
"id": "notification-template",
"params": {
"order": "123456"
}
}
}
Afficher ce bloc de code dans la fenêtre flottante
2. Envoyer un contenu marketing personnalisé :
{
"to": ["+6591234567"],
"template": {
"id": "marketing-template",
"params": {
"name": "EngageLab",
"promotion": "30%"
}
}
}
{
"to": ["+6591234567"],
"template": {
"id": "marketing-template",
"params": {
"name": "EngageLab",
"promotion": "30%"
}
}
}
Afficher ce bloc de code dans la fenêtre flottante
Paramètres de réponse
Réponse en cas de succès
Le code de statut HTTP est 200 et le corps de la réponse contient les champs suivants :
| Champ | Type | Option | Description |
|---|---|---|---|
| plan_id | String | Obligatoire | ID du plan |
| total_count | Integer | Obligatoire | Nombre de cibles reçues |
| accepted_count | Integer | Obligatoire | Nombre de cibles valides reçues |
| message_id | String | Facultatif | Renvoyé lors d'un envoi unique, correspondant au message_id concerné |
| schedule_info | JSON Object | Facultatif | Informations relatives à la tâche programmée (renvoyées uniquement pour un envoi programmé) |
| |_ task_id | Integer | Obligatoire | ID de la tâche programmée |
Exemple de succès (cible unique)
{
"plan_id": "1972488990548348928",
"total_count": 1,
"accepted_count": 1,
"message_id": "1972488990804201472"
}
{
"plan_id": "1972488990548348928",
"total_count": 1,
"accepted_count": 1,
"message_id": "1972488990804201472"
}
Afficher ce bloc de code dans la fenêtre flottante
Exemple de succès (cibles multiples)
{
"plan_id": "1972484198153367552",
"total_count": 2,
"accepted_count": 2
}
{
"plan_id": "1972484198153367552",
"total_count": 2,
"accepted_count": 2
}
Afficher ce bloc de code dans la fenêtre flottante
Exemple de succès (tâche programmée)
{
"plan_id": "1972492618659033088",
"total_count": 1,
"accepted_count": 1,
"schedule_info": {
"task_id": 1972492621368553472
}
}
{
"plan_id": "1972492618659033088",
"total_count": 1,
"accepted_count": 1,
"schedule_info": {
"task_id": 1972492621368553472
}
}
Afficher ce bloc de code dans la fenêtre flottante
Réponse en cas d'échec
Le code de statut HTTP est 200 (dans certains cas d'erreur) ou 4xx/5xx, et le corps de la réponse contient les champs suivants :
| Champ | Type | Option | Description |
|---|---|---|---|
| plan_id | String | Obligatoire | ID du plan |
| total_count | Integer | Obligatoire | Nombre de cibles reçues |
| accepted_count | Integer | Obligatoire | Nombre de cibles valides reçues |
| code | Integer | Obligatoire | Code d'erreur ; voir la description des codes d'erreur |
| message | String | Obligatoire | Détails de l'erreur |
Exemple d'erreur
{
"plan_id": "1972490061974913024",
"total_count": 1,
"accepted_count": 1,
"message": "err xxxx",
"code": 1
}
{
"plan_id": "1972490061974913024",
"total_count": 1,
"accepted_count": 1,
"message": "err xxxx",
"code": 1
}
Afficher ce bloc de code dans la fenêtre flottante
Codes d'erreur
| Code d'erreur | http code | Description |
|---|---|---|
| 1000 | 500 | Erreur interne |
| 2001 | 401 | Échec de l'authentification, token incorrect fourni |
| 2002 | 401 | Échec de l'authentification, token expiré ou désactivé |
| 2004 | 403 | Aucune autorisation d'appeler cette API |
| 3001 | 400 | Format de paramètre de requête invalide ; veuillez vérifier la conformité au format JSON requis |
| 3002 | 400 | Paramètres de requête incorrects ; veuillez vérifier qu'ils respectent les exigences |
| 3003 | 400 | Paramètres de requête incorrects, échec de la validation métier associée ; consultez la description de l'erreur dans le champ message pour plus de détails |
| 3004 | 400 | Limite de fréquence dépassée : impossible de renvoyer un message au même utilisateur cible avec le même modèle pendant la période de validité du code de vérification |
| 4001 | 400 | Ressource associée inexistante, par exemple l'utilisation d'un modèle inexistant lors de l'envoi du message |
| 5001 | 400 | Échec de l'envoi du message ; consultez la description de l'erreur dans le champ message pour plus de détails |
