Créer un modèle
Adresse d'appel
POST https://otp.api.engagelab.cc/v1/template-configs
Authentification
Veuillez consulter Authentification pour savoir comment effectuer l'authentification de l'API.
Requête
Paramètres de requête
Un objet de requête est exprimé au format JSON ; l'en-tête de requête doit donc inclure Content-Type: application/json.
| Paramètre | Type | Option | Description |
|---|---|---|---|
| template_id | String | Obligatoire | id de modèle personnalisé, unique, limité à 128 caractères |
| description | String | Facultatif | Description du modèle, limitée à 255 caractères |
| send_channel_strategy | String | Obligatoire | Stratégie du modèle ; pour un canal unique, les valeurs sont whatsapp/sms/email/voice ; pour plusieurs canaux, séparez-les par |, le renvoi se fait dans l'ordre ; email ne peut pas être combiné avec d'autres canaux pour former une stratégie |
| brand_name | String | Facultatif | Marque distinctive ; remplace la variable de signature de marque dans certains styles de modèle comportant une signature de marque, longueur limitée à 2-10 caractères |
| verify_code_config | Object | Obligatoire sous condition | Configuration du code de vérification, obligatoire lorsque le modèle inclut un type de code de vérification |
| verify_code_config.verify_code_type | Integer | Obligatoire | Type de code de vérification, plage de valeurs [1,7] ; 1 chiffre/2 lettre minuscule/4 lettre majuscule, combinables (par exemple, 3 signifie chiffre + lettre minuscule) |
| verify_code_config.verify_code_len | Integer | Obligatoire | Longueur du code de vérification, plage de valeurs [4,10] |
| verify_code_config.verify_code_ttl | Integer | Obligatoire | Durée de validité du code de vérification, en minutes, valeur [1,10] ; lorsque la stratégie inclut whatsapp, la valeur ne peut être que 1, 5 ou 10 |
| whatsapp_config | Object | Obligatoire sous condition | Configuration de la stratégie whatsapp, obligatoire lorsque la stratégie d'envoi inclut whatsapp |
| whatsapp_config.template_type | Integer | Obligatoire | Type de modèle whatsapp, seul le modèle par défaut est actuellement pris en charge, valeur fixe 1 |
| whatsapp_config.template_default_config | Object | Obligatoire sous condition | Configuration du modèle whatsapp par défaut, obligatoire lorsque le type de modèle whatsapp est le modèle par défaut |
| sms_config | Object | Obligatoire sous condition | Configuration de la stratégie sms, obligatoire lorsque la stratégie d'envoi inclut sms |
| sms_config.template_type | Integer | Obligatoire | Type de modèle sms, 1-modèle par défaut/2-modèle personnalisé |
| sms_config.template_default_config | Object | Obligatoire sous condition | Configuration du modèle sms par défaut, obligatoire lorsque le type de modèle sms est le modèle par défaut |
| sms_config.template_custom_config | Object | Obligatoire sous condition | Configuration du modèle sms personnalisé, obligatoire lorsque le type de modèle sms est le modèle personnalisé |
| sms_config.template_custom_config.custom_sub_type | String | Obligatoire | Type de modèle personnalisé, authentication-code de vérification/marketing-marketing/utility-notification |
| sms_config.template_custom_config.custom_content | String | Obligatoire | Contenu du modèle personnalisé, doit contenir la variable {{code}} lorsque le type est authentication |
| sms_config.template_custom_config.custom_country_codes | String | Facultatif | Codes des pays/régions cibles, séparés par des virgules, utilisés comme référence lors de la révision du modèle |
| voice_config | Object | Obligatoire sous condition | Configuration de la stratégie voice, obligatoire lorsque la stratégie d'envoi inclut voice |
| voice_config.template_type | Integer | Obligatoire | Type de modèle voice, seul le modèle par défaut est actuellement pris en charge, valeur fixe 1 |
| voice_config.template_default_config | Object | Obligatoire sous condition | Configuration du modèle voice par défaut, obligatoire lorsque le type de modèle voice est le modèle par défaut |
| email_config | Object | Obligatoire sous condition | Configuration de la stratégie email, obligatoire lorsque la stratégie d'envoi inclut email |
| email_config.template_name | String | Obligatoire | nom du modèle email |
| email_config.template_custom_configs | Array | Obligatoire sous condition | Configuration du modèle email personnalisé, obligatoire lorsque le type de modèle email est le modèle personnalisé, prend en charge la configuration multilingue |
| email_config.template_custom_configs.language | String | Obligatoire | Langue, default étant la valeur par défaut ; lors de l'envoi du message, différents contenus de modèle peuvent être associés selon le paramètre language |
| email_config.template_custom_configs.pre_from_name | String | Facultatif | Nom de l'expéditeur prédéfini |
| email_config.template_custom_configs.pre_from_mail | String | Obligatoire | Adresse e-mail de l'expéditeur prédéfini |
| email_config.template_custom_configs.pre_subject | String | Obligatoire | Objet de l'e-mail prédéfini |
| email_config.template_custom_configs.template_content | String | Obligatoire | Contenu de l'e-mail, prend en charge le html, les variables doivent être entourées de {{}} |
| email_config.template_custom_configs.pre_param_map | Object | Facultatif | Valeurs par défaut des variables du contenu de l'e-mail, déclarées sous forme de paires clé-valeur, la valeur devant être une chaîne de caractères |
| pwa_config | Object | Facultatif | Configuration relative au pwa, temporairement inutilisée |
| pwa_config.pwa_platform | String | Facultatif | Plateforme pwa utilisée, veuillez contacter le support technique pour connaître les valeurs précises |
| pwa_config.pwa_code | String | Facultatif | code dans la plateforme pwa utilisée |
Exemple de requête
En-tête de requête
POST /v1/template-configs HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
Corps de la requête
{
"template_id": "test-template-1", // id de modèle personnalisé, unique au sein de l'application
"description": "Modèle de test 1", // description explicative du modèle
"send_channel_strategy": "whatsapp|sms", // stratégie d'envoi du modèle, prend en charge les quatre types whatsapp/sms/voice/email ; pour une stratégie combinée, utilisez le caractère | pour indiquer le renvoi en cas d'échec
"brand_name": "Nom de la marque", // nom de la marque, utilisé dans la signature du contenu des modèles de certains pays/régions (par exemple, certains pays/régions exigent l'enregistrement d'une signature sur le canal SMS)
"verify_code_config": { // configuration du code de vérification, utilisée pour configurer le code de vérification généré automatiquement, obligatoire lorsque le modèle inclut un type de code de vérification
"verify_code_type": 1, // type de code de vérification, plage de valeurs [1,7]
"verify_code_len": 6, // longueur du code de vérification, plage de valeurs [4,10]
"verify_code_ttl": 1 // durée de validité du code de vérification, plage de valeurs [1,10] ; attention, lorsque la stratégie inclut whatsapp, la valeur ne peut être que 1, 5 ou 10
},
"whatsapp_config": { // configuration de la stratégie whatsapp, valable lorsque la stratégie d'envoi inclut whatsapp
"template_type": 1, // type de modèle whatsapp, seul le modèle par défaut est actuellement pris en charge, soit la valeur fixe 1
"template_default_config": { // configuration du modèle whatsapp par défaut, valable pour le type de modèle par défaut
"contain_security": false, // indique s'il faut ajouter un rappel de sécurité
"contain_expire": false // indique s'il faut ajouter le contenu relatif au délai d'expiration
}
},
"sms_config": { // configuration de la stratégie sms, valable lorsque la stratégie d'envoi inclut sms
"template_type": 2, // type de modèle sms, valeurs : 1-modèle par défaut/2-modèle personnalisé
"template_default_config": { // configuration du modèle sms par défaut, valable pour le type de modèle par défaut
"contain_security": false, // indique s'il faut ajouter un rappel de sécurité
"contain_expire": false // indique s'il faut ajouter le contenu relatif au délai d'expiration
},
"template_custom_config": { // configuration du modèle sms personnalisé, valable lorsque le type de modèle sms est un modèle personnalisé
"custom_sub_type": "authentication", // type de modèle personnalisé, valeurs : authentication-code de vérification/marketing-marketing/utility-notification
"custom_content": "xxx", // contenu du modèle personnalisé ; attention, si le sous-type est authentication (code de vérification), il doit contenir la variable {{code}}
"custom_country_codes": "HK,PH" // pays/régions cibles du modèle personnalisé, utilisés comme référence lors de la révision du modèle ; veuillez les renseigner conformément à la réalité, sous peine d'affecter l'envoi effectif
}
},
"voice_config": { // configuration de la stratégie voice, valable lorsque la stratégie d'envoi inclut voice
"template_type": 1, // type de modèle voice, seul le modèle par défaut est actuellement pris en charge, soit la valeur fixe 1
"template_default_config": { // configuration du modèle voice par défaut, valable pour le type de modèle par défaut
"contain_security": false, // indique s'il faut ajouter un rappel de sécurité
"contain_expire": false // indique s'il faut ajouter le contenu relatif au délai d'expiration
}
},
"email_config": { // configuration de la stratégie email, valable lorsque la stratégie d'envoi inclut email
"template_name": "nom du modèle email", // nom du modèle email
"template_custom_configs": [{ // configuration du modèle email personnalisé ; attention, il s'agit ici d'un tableau d'objets, principalement pour configurer plusieurs entrées distinguées par language
"language": "default", // langue, default étant la valeur par défaut ; lors de l'envoi du message, différents contenus de modèle peuvent être associés selon le paramètre language
"pre_from_name": "test", // nom de l'expéditeur prédéfini
"pre_from_mail": "test@test.com", // adresse e-mail de l'expéditeur prédéfini
"pre_subject": "test", // objet de l'e-mail prédéfini
"template_content": "Contenu prédéfini du modèle d'e-mail, obligatoire, variables personnalisées comme {{self}}, le code de vérification est {{code}}", // contenu de l'e-mail, prend en charge le html ; les variables doivent être entourées de doubles accolades {{}}
"pre_param_map": { // valeurs par défaut des variables du contenu de l'e-mail ; si aucune valeur n'est spécifiée lors de l'envoi, les valeurs par défaut ci-dessous remplacent les variables ; déclarées sous forme de paires clé-valeur, la valeur devant être une chaîne de caractères
"self": "Voici la valeur prédéfinie de la variable self"
}
}]
},
"pwa_config": { // configuration relative au pwa, temporairement inutilisée
"pwa_platform": "xx", // plateforme pwa utilisée, veuillez contacter le support technique pour déterminer les valeurs précises
"pwa_code": "xx" // code dans la plateforme pwa utilisée
}
}
Réponse
Paramètres de réponse
| Champ | Type | Option | Description |
|---|---|---|---|
| code | Integer | Obligatoire | Code d'erreur, 0 signifie succès, toute autre valeur signifie échec |
| message | String | Obligatoire | Message de réponse |
Exemple de réponse
Réponse en cas de succès
{
"code": 0,
"message": "success"
}
Réponse en cas d'échec
{
"code": 3003,
"message": "not contains any channel config"
}
Utilisation avancée des variables de modèle Email
Lorsque vous activez le canal Email dans la stratégie d'envoi, vous pouvez personnaliser de manière poussée l'objet et le contenu du corps de l'e-mail. Grâce aux espaces réservés de variables {{nom_variable}}, vous pouvez remplir automatiquement le code de vérification, les informations de marque, etc., pour offrir une expérience d'e-mail personnalisée et flexible.
Types de variables et utilisation
Des variables peuvent être intégrées à la fois dans le corps du modèle Email (template_content) et dans l'objet (pre_subject), au format {{nom_variable}}.
L'API d'envoi les transmet dynamiquement via le champ template.params, ou bien des valeurs par défaut sont définies lors de l'étape de création du modèle.
Variables prises en charge
Les variables ci-dessous ne s'appliquent qu'au canal Email.
| Nom de la variable | Type | Description | Méthode de remplissage |
|---|---|---|---|
{{logo_url}} |
Variable personnalisée | Adresse de l'image du logo de la marque | Transmise via template.params lors de l'envoi |
{{title}} |
Variable personnalisée | Texte du titre du corps de l'e-mail | Transmise via template.params lors de l'envoi |
{{support_email}} |
Variable personnalisée | Adresse e-mail du service client/support | Transmise via template.params lors de l'envoi |
{{subject}} |
Variable personnalisée | Remplacement dynamique de l'objet de l'e-mail | Transmise via template.params lors de l'envoi |
{{from_name}} |
Variable personnalisée | Remplacement dynamique du nom de l'expéditeur | Transmise via template.params lors de l'envoi |
{{from_mail}} |
Variable personnalisée | Remplacement dynamique de l'adresse e-mail de l'expéditeur | Transmise via template.params lors de l'envoi |
Remarque : les variables spéciales
{{subject}},{{from_name}}et{{from_mail}}ne sont pas insérées dans le code HTML du corps, mais remplacent directement les champs de métadonnées de l'e-mail.
Exemple d'objet d'e-mail
{{brand_name}} Code de vérification
Exemple de corps d'e-mail
<img src="{{logo_url}}" />
<strong>{{title}}</strong>
<p>Votre code de vérification est <strong>{{code}}</strong>, veuillez terminer la vérification dans un délai de {{ttl}} minutes.</p>
<p>Pour toute question, veuillez contacter <a href="mailto:{{support_email}}">{{support_email}}</a></p>
Définition des valeurs par défaut du modèle
Lors de la création d'un modèle, vous pouvez définir les valeurs par défaut des variables personnalisées dans le champ pre_param_map. Si aucune variable n'est transmise lors de l'envoi de l'e-mail, les valeurs par défaut sont utilisées automatiquement.
"pre_param_map": {
"logo_url": "https://example.com/logo.png",
"title": "Votre code de vérification",
"support_email": "support@example.com"
}
Description des paramètres d'envoi
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
to |
string | Oui | Adresse e-mail cible |
template.id |
string | Oui | ID du modèle d'e-mail |
template.language |
string | Non | Code de langue, par défaut default |
template.params |
object | Non | Affectation des variables du modèle (sans {{}}) |
Exemple de requête :
{
"to": "user@example.com",
"template": {
"id": "my_email_template",
"language": "default",
"params": {
"logo_url": "https://example.com/logo.png",
"title": "Votre code de vérification",
"support_email": "support@example.com"
}
}
}
Priorité de remplissage des variables
- La priorité est donnée aux valeurs de variables transmises via
template.paramsdans l'interface d'envoi ; - Si elles ne sont pas transmises, les valeurs par défaut définies dans le
pre_param_mapdu modèle sont utilisées ; - Si ni l'une ni l'autre n'est définie, les espaces réservés s'affichent tels quels dans le contenu de l'e-mail.
Foire aux questions
Q : Pourquoi mes variables ne sont-elles pas remplacées ?
R : Veuillez vérifier que le nom de la variable est écrit et formaté correctement (il faut {{nom_variable}}), et assurez-vous d'avoir fourni la valeur via template.params, ou que le modèle a défini une valeur par défaut.
Q : Comment définir dynamiquement l'objet de l'e-mail et l'expéditeur ?
R : Transmettez subject, from_name et from_mail dans le paramètre de requête template.params pour remplacer dynamiquement l'objet et les informations d'expéditeur prédéfinis du modèle.
Codes d'erreur
| Code d'erreur | http code | Description |
|---|---|---|
| 1000 | 500 | Erreur interne |
| 2001 | 401 | Échec de l'authentification, le token correct n'a pas été fourni |
| 2002 | 401 | Échec de l'authentification, le token a expiré ou a été désactivé |
| 2004 | 403 | Aucune autorisation pour appeler cette API |
| 3001 | 400 | Format des paramètres de requête invalide, veuillez vérifier que le contenu JSON est conforme au format des paramètres |
| 3002 | 400 | Paramètres de requête incorrects, veuillez vérifier que les paramètres de requête respectent les exigences |
| 3003 | 400 | Erreur de paramètre au niveau métier, veuillez consulter la description du champ message renvoyé |










