Logo Site EngageLab Mark Colored TransparentDocumentation
Rechercher

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
              
              POST /v1/template-configs  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

{ "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 } }
              
              {
    "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
    }
}

            
Afficher ce bloc de code dans la fenêtre flottante

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" }
              
              {
    "code": 0,
    "message": "success"
}

            
Afficher ce bloc de code dans la fenêtre flottante

Réponse en cas d'échec

{ "code": 3003, "message": "not contains any channel config" }
              
              {
    "code": 3003,
    "message": "not contains any channel config"
}

            
Afficher ce bloc de code dans la fenêtre flottante

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
              
              {{brand_name}} Code de vérification

            
Afficher ce bloc de code dans la fenêtre flottante

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

            
Afficher ce bloc de code dans la fenêtre flottante

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" }
              
              "pre_param_map": {
  "logo_url": "https://example.com/logo.png",
  "title": "Votre code de vérification",
  "support_email": "support@example.com"
}

            
Afficher ce bloc de code dans la fenêtre flottante

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" } } }
              
              {
  "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"
    }
  }
}

            
Afficher ce bloc de code dans la fenêtre flottante

Priorité de remplissage des variables

  1. La priorité est donnée aux valeurs de variables transmises via template.params dans l'interface d'envoi ;
  2. Si elles ne sont pas transmises, les valeurs par défaut définies dans le pre_param_map du modèle sont utilisées ;
  3. 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é
Icon Solid Transparent White Qiyu
Contactez-nous