Logo Site EngageLab Mark Colored TransparentDokumentation
Suchen

Vorlage erstellen

Anfrage-URL

POST https://otp.api.engagelab.cc/v1/template-configs

Authentifizierung

Bitte lesen Sie Authentifizierung, um zu erfahren, wie Sie die API-Authentifizierung durchführen.

Anfrage

Anfrageparameter

Ein Anfrageobjekt wird im JSON-Format ausgedrückt, daher muss der Anfrage-Header Content-Type: application/json enthalten.

Parameter Typ Option Beschreibung
template_id String Erforderlich Benutzerdefinierte Vorlagen-ID, muss eindeutig sein, auf 128 Zeichen begrenzt
description String Optional Beschreibung der Vorlage, auf 255 Zeichen begrenzt
send_channel_strategy String Erforderlich Vorlagenstrategie, Werte für einzelne Kanäle sind whatsapp/sms/email/voice, mehrere Kanäle werden durch | getrennt, Fallback in dieser Reihenfolge, email kann nicht mit anderen Kanälen kombiniert werden
brand_name String Optional Markenkennzeichen, ersetzt die Marken-Signaturvariable, wenn bestimmte Vorlagenstile eine Marken-Signatur haben, Länge auf 2-10 Zeichen begrenzt
verify_code_config Object Bedingt erforderlich Konfiguration des Verifizierungscodes, erforderlich, wenn die Vorlage einen Verifizierungscode-Typ enthält
verify_code_config.verify_code_type Integer Erforderlich Typ des Verifizierungscodes, Wertebereich [1,7], 1 Zahl/2 Kleinbuchstabe/4 Großbuchstabe, kann kombiniert werden (z. B. bedeutet 3 Zahl + Kleinbuchstabe)
verify_code_config.verify_code_len Integer Erforderlich Länge des Verifizierungscodes, Wertebereich [4,10]
verify_code_config.verify_code_ttl Integer Erforderlich Gültigkeitsdauer des Verifizierungscodes in Minuten, Wertebereich [1,10], wenn die Strategie whatsapp enthält, sind nur 1, 5, 10 möglich
whatsapp_config Object Bedingt erforderlich whatsapp-Strategiekonfiguration, erforderlich, wenn die Sendestrategie whatsapp enthält
whatsapp_config.template_type Integer Erforderlich whatsapp-Vorlagentyp, unterstützt derzeit nur die Standardvorlage, fest auf 1
whatsapp_config.template_default_config Object Bedingt erforderlich whatsapp-Standardvorlagenkonfiguration, erforderlich, wenn der whatsapp-Vorlagentyp die Standardvorlage ist
sms_config Object Bedingt erforderlich sms-Strategiekonfiguration, erforderlich, wenn die Sendestrategie sms enthält
sms_config.template_type Integer Erforderlich sms-Vorlagentyp, 1-Standardvorlage/2-benutzerdefinierte Vorlage
sms_config.template_default_config Object Bedingt erforderlich sms-Standardvorlagenkonfiguration, erforderlich, wenn der sms-Vorlagentyp die Standardvorlage ist
sms_config.template_custom_config Object Bedingt erforderlich sms-benutzerdefinierte Vorlagenkonfiguration, erforderlich, wenn der sms-Vorlagentyp die benutzerdefinierte Vorlage ist
sms_config.template_custom_config.custom_sub_type String Erforderlich Benutzerdefinierter Vorlagentyp, authentication/marketing/utility
sms_config.template_custom_config.custom_content String Erforderlich Benutzerdefinierter Vorlageninhalt, muss die Variable {{code}} enthalten, wenn der Typ authentication ist
sms_config.template_custom_config.custom_country_codes String Optional Ziel-Länder-/Regionscodes, durch Komma getrennt, dienen als Referenz bei der Vorlagenprüfung
voice_config Object Bedingt erforderlich voice-Strategiekonfiguration, erforderlich, wenn die Sendestrategie voice enthält
voice_config.template_type Integer Erforderlich voice-Vorlagentyp, unterstützt derzeit nur die Standardvorlage, fest auf 1
voice_config.template_default_config Object Bedingt erforderlich voice-Standardvorlagenkonfiguration, erforderlich, wenn der voice-Vorlagentyp die Standardvorlage ist
email_config Object Bedingt erforderlich email-Strategiekonfiguration, erforderlich, wenn die Sendestrategie email enthält
email_config.template_name String Erforderlich email-Vorlagenname
email_config.template_custom_configs Array Bedingt erforderlich email-benutzerdefinierte Vorlagenkonfiguration, erforderlich, wenn der email-Vorlagentyp die benutzerdefinierte Vorlage ist, unterstützt mehrsprachige Konfiguration
email_config.template_custom_configs.language String Erforderlich Sprache, Standard ist default, je nach dem language-Parameter kann beim Senden der Nachricht ein anderer Vorlageninhalt zugeordnet werden
email_config.template_custom_configs.pre_from_name String Optional Voreingestellter Absendername
email_config.template_custom_configs.pre_from_mail String Erforderlich Voreingestellte Absender-E-Mail
email_config.template_custom_configs.pre_subject String Erforderlich Voreingestellter E-Mail-Betreff
email_config.template_custom_configs.template_content String Erforderlich E-Mail-Inhalt, unterstützt HTML, Variablen müssen in {{}} eingeschlossen werden
email_config.template_custom_configs.pre_param_map Object Optional Standardwerte für Variablen im E-Mail-Inhalt, als Schlüssel-Wert-Paare deklariert, der Wert muss eine Zeichenfolge sein
pwa_config Object Optional pwa-bezogene Konfiguration, derzeit nicht verwendet
pwa_config.pwa_platform String Optional Verwendete pwa-Plattform, wenden Sie sich für konkrete Werte an den technischen Support
pwa_config.pwa_code String Optional Code in der verwendeten pwa-Plattform

Anfragebeispiel

Anfrage-Header

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

            
Diesen Codeblock im schwebenden Fenster anzeigen

Anfragetext

{ "template_id": "test-template-1", // Custom template id, unique within the application "description": "Test template 1", // Description of the template "send_channel_strategy": "whatsapp|sms",// Template delivery strategy, supports whatsapp/sms/voice/email. Combined strategies use the | character to indicate fallback on failure "brand_name": "Brand Name", // Brand name, used for signatures in template content in some countries/regions (e.g., some countries require registered signatures in the SMS channel) "verify_code_config": { // Verification code configuration, used to configure automatically generated verification codes, required when the template contains a verification code type "verify_code_type": 1, // Verification code type, value range [1,7] "verify_code_len": 6, // Verification code length, value range [4,10] "verify_code_ttl": 1 // Verification code validity period, value range [1,10], note that when the strategy includes whatsapp, the value can only be 1, 5, 10 }, "whatsapp_config": { // whatsapp strategy configuration, valid when the delivery strategy includes whatsapp "template_type": 1, // whatsapp template type, currently only supports default template, fixed value is 1 "template_default_config": { // whatsapp default template configuration, valid for default template type "contain_security": false, // Whether to add security reminder "contain_expire": false // Whether to add expiration time content } }, "sms_config": { // sms strategy configuration, valid when the delivery strategy includes sms "template_type": 2, // sms template type, values: 1-default template/2-custom template "template_default_config": { // sms default template configuration, valid for default template type "contain_security": false, // Whether to add security reminder "contain_expire": false // Whether to add expiration time content }, "template_custom_config": { // sms custom template configuration, valid when sms template type is custom template "custom_sub_type": "authentication", // Custom template type, values: authentication/marketing/utility "custom_content": "xxx", // Custom template content, note that if the sub-type is authentication, it must contain the {{code}} variable "custom_country_codes": "HK,PH" // Target country/region for custom template, used for reference during template audit, please fill in according to actual situation, otherwise it may affect actual delivery } }, "voice_config": { // voice strategy configuration, valid when the delivery strategy includes voice "template_type": 1, // voice template type, currently only supports default template, fixed value is 1 "template_default_config": { // voice default template configuration, valid for default template type "contain_security": false, // Whether to add security reminder "contain_expire": false // Whether to add expiration time content } }, "email_config": { // email strategy configuration, valid when the delivery strategy includes email "template_name": "email template name", // email template name "template_custom_configs": [{ // email custom template configuration, note this is an object array, mainly used to configure multiple languages via language "language": "default", // Language, default is default, different template content can be matched according to the language parameter during message delivery "pre_from_name": "test", // Preset sender name "pre_from_mail": "test@test.com",// Preset sender email "pre_subject": "test", // Preset email subject "template_content": "Preset email template content, required, custom variables like {{self}}, verification code is {{code}}", // Email content, supports html, variables need to be enclosed in double braces {{}} "pre_param_map": { // Default values for variables in email content, i.e., if variable values are not specified during delivery, the following default values will be used to replace variables, declared as key-value pairs, value needs to be a string "self": "Here is the preset value for the self variable" } }] }, "pwa_config": { // pwa related configuration, temporarily not used "pwa_platform": "xx", // pwa platform used, please contact technical support for specific values "pwa_code": "xx" // code in the pwa platform used } }
              
              {
    "template_id": "test-template-1",       // Custom template id, unique within the application
    "description": "Test template 1",       // Description of the template
    "send_channel_strategy": "whatsapp|sms",// Template delivery strategy, supports whatsapp/sms/voice/email. Combined strategies use the | character to indicate fallback on failure
    "brand_name": "Brand Name",             // Brand name, used for signatures in template content in some countries/regions (e.g., some countries require registered signatures in the SMS channel)
    "verify_code_config": {                 // Verification code configuration, used to configure automatically generated verification codes, required when the template contains a verification code type
        "verify_code_type": 1,              // Verification code type, value range [1,7]
        "verify_code_len": 6,               // Verification code length, value range [4,10]
        "verify_code_ttl": 1                // Verification code validity period, value range [1,10], note that when the strategy includes whatsapp, the value can only be 1, 5, 10
    },
    "whatsapp_config": {                    // whatsapp strategy configuration, valid when the delivery strategy includes whatsapp
        "template_type": 1,                 // whatsapp template type, currently only supports default template, fixed value is 1
        "template_default_config": {        // whatsapp default template configuration, valid for default template type
            "contain_security": false,      // Whether to add security reminder
            "contain_expire": false         // Whether to add expiration time content
        }
    },
    "sms_config": {                         // sms strategy configuration, valid when the delivery strategy includes sms
        "template_type": 2,                 // sms template type, values: 1-default template/2-custom template
        "template_default_config": {        // sms default template configuration, valid for default template type
            "contain_security": false,      // Whether to add security reminder
            "contain_expire": false         // Whether to add expiration time content
        },
        "template_custom_config": {         // sms custom template configuration, valid when sms template type is custom template
            "custom_sub_type": "authentication", // Custom template type, values: authentication/marketing/utility
            "custom_content": "xxx",        // Custom template content, note that if the sub-type is authentication, it must contain the {{code}} variable
            "custom_country_codes": "HK,PH" // Target country/region for custom template, used for reference during template audit, please fill in according to actual situation, otherwise it may affect actual delivery
        }
    },
    "voice_config": {                       // voice strategy configuration, valid when the delivery strategy includes voice
        "template_type": 1,                 // voice template type, currently only supports default template, fixed value is 1
        "template_default_config": {        // voice default template configuration, valid for default template type
            "contain_security": false,      // Whether to add security reminder
            "contain_expire": false         // Whether to add expiration time content
        }
    },
    "email_config": {                       // email strategy configuration, valid when the delivery strategy includes email
        "template_name": "email template name", // email template name
        "template_custom_configs": [{       // email custom template configuration, note this is an object array, mainly used to configure multiple languages via language
            "language": "default",          // Language, default is default, different template content can be matched according to the language parameter during message delivery
            "pre_from_name": "test",        // Preset sender name
            "pre_from_mail": "test@test.com",// Preset sender email
            "pre_subject": "test",          // Preset email subject
            "template_content": "Preset email template content, required, custom variables like {{self}}, verification code is {{code}}", // Email content, supports html, variables need to be enclosed in double braces {{}}
            "pre_param_map": {              // Default values for variables in email content, i.e., if variable values are not specified during delivery, the following default values will be used to replace variables, declared as key-value pairs, value needs to be a string
                "self": "Here is the preset value for the self variable"
            }
        }]
    },
    "pwa_config": {                         // pwa related configuration, temporarily not used
        "pwa_platform": "xx",               // pwa platform used, please contact technical support for specific values
        "pwa_code": "xx"                    // code in the pwa platform used
    }
}

            
Diesen Codeblock im schwebenden Fenster anzeigen

Antwort

Antwortparameter

Feld Typ Option Beschreibung
code Integer Erforderlich Fehlercode, 0 bedeutet Erfolg, andere bedeuten Fehlschlag
message String Erforderlich Antwortnachricht

Antwortbeispiel

Erfolgsantwort

{ "code": 0, "message": "success" }
              
              {
    "code": 0,
    "message": "success"
}

            
Diesen Codeblock im schwebenden Fenster anzeigen

Fehlerantwort

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

            
Diesen Codeblock im schwebenden Fenster anzeigen

Erweiterte Verwendung von E-Mail-Vorlagenvariablen

Wenn Sie den Kanal Email in der Sendestrategie aktivieren, werden hochgradig anpassbare E-Mail-Betreffzeilen und -Inhalte unterstützt. Über Variablenplatzhalter {{variable_name}} können Sie automatisch Verifizierungscodes, Markeninformationen usw. einfügen, um ein flexibles und personalisiertes E-Mail-Erlebnis zu schaffen.

Variablentypen und Verwendung

Variablen können sowohl in den Text der E-Mail-Vorlage (template_content) als auch in den Betreff (pre_subject) eingebettet werden, im Format {{variable_name}}.

Die Sende-API übergibt sie dynamisch über das Feld template.params oder es werden in der Phase der Vorlagenerstellung Standardwerte festgelegt.

Unterstützte Variablen

Die folgenden Variablen gelten nur für den Email-Kanal.

Variablenname Typ Beschreibung Befüllungsmethode
{{logo_url}} Benutzerdefinierte Variable Bild-URL des Marken-Logos Beim Senden über template.params übergeben
{{title}} Benutzerdefinierte Variable Titeltext des E-Mail-Texts Beim Senden über template.params übergeben
{{support_email}} Benutzerdefinierte Variable Kundenservice-/Support-E-Mail Beim Senden über template.params übergeben
{{subject}} Benutzerdefinierte Variable E-Mail-Betreff dynamisch überschreiben Beim Senden über template.params übergeben
{{from_name}} Benutzerdefinierte Variable Absendername dynamisch überschreiben Beim Senden über template.params übergeben
{{from_mail}} Benutzerdefinierte Variable Absender-E-Mail dynamisch überschreiben Beim Senden über template.params übergeben

Hinweis: Die speziellen Variablen {{subject}}, {{from_name}} und {{from_mail}} werden nicht in das HTML des E-Mail-Texts eingefügt, sondern überschreiben direkt die Metadatenfelder der E-Mail.

Beispiel für einen E-Mail-Betreff

{{brand_name}} Verification Code
              
              {{brand_name}} Verification Code

            
Diesen Codeblock im schwebenden Fenster anzeigen

Beispiel für einen E-Mail-Text

<img src="{{logo_url}}" /> <strong>{{title}}</strong> <p>Your verification code is <strong>{{code}}</strong>, please complete verification within {{ttl}} minutes.</p> <p>If you have any questions, please contact <a href="mailto:{{support_email}}">{{support_email}}</a></p>
              
              <img src="{{logo_url}}" />
<strong>{{title}}</strong>
<p>Your verification code is <strong>{{code}}</strong>, please complete verification within {{ttl}} minutes.</p>
<p>If you have any questions, please contact <a href="mailto:{{support_email}}">{{support_email}}</a></p>

            
Diesen Codeblock im schwebenden Fenster anzeigen

Festlegen von Standardwerten in der Vorlage

Beim Erstellen einer Vorlage können Sie im Feld pre_param_map Standardwerte für benutzerdefinierte Variablen festlegen. Wenn beim Senden der E-Mail keine Variablen übergeben werden, werden automatisch die Standardwerte verwendet.

"pre_param_map": { "logo_url": "https://example.com/logo.png", "title": "Your Verification Code", "support_email": "support@example.com" }
              
              "pre_param_map": {
  "logo_url": "https://example.com/logo.png",
  "title": "Your Verification Code",
  "support_email": "support@example.com"
}

            
Diesen Codeblock im schwebenden Fenster anzeigen

Beschreibung der Sendeparameter

Feld Typ Erforderlich Beschreibung
to string Ja Ziel-E-Mail-Adresse
template.id string Ja E-Mail-Vorlagen-ID
template.language string Nein Sprachcode, Standard default
template.params object Nein Zuweisung von Vorlagenvariablen (ohne {{}})

Beispielanfrage:

{ "to": "user@example.com", "template": { "id": "my_email_template", "language": "default", "params": { "logo_url": "https://example.com/logo.png", "title": "Your Verification Code", "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": "Your Verification Code",
      "support_email": "support@example.com"
    }
  }
}

            
Diesen Codeblock im schwebenden Fenster anzeigen

Priorität bei der Variablenbefüllung

  1. Vorrang haben die in template.params der Sende-Schnittstelle übergebenen Variablenwerte;
  2. Werden diese nicht übergeben, werden die Standardwerte in pre_param_map der Vorlage verwendet;
  3. Ist keines von beiden festgelegt, werden die Platzhalter unverändert im E-Mail-Inhalt angezeigt.

Häufig gestellte Fragen

F: Warum werden die Variablen nicht ersetzt?
A: Bitte prüfen Sie, ob der Variablenname korrekt geschrieben und formatiert ist (erfordert {{variable_name}}), und stellen Sie sicher, dass der Wert über template.params bereitgestellt wurde oder die Vorlage einen Standardwert festgelegt hat.

F: Wie lege ich E-Mail-Betreff und Absender dynamisch fest?
A: Übergeben Sie subject, from_name und from_mail im Anfrageparameter template.params, um den voreingestellten Betreff und die Absenderinformationen der Vorlage dynamisch zu überschreiben.

Fehlercodes

Fehlercode HTTP-Code Beschreibung
1000 500 Interner Fehler
2001 401 Authentifizierung fehlgeschlagen, falsches Token übermittelt
2002 401 Authentifizierung fehlgeschlagen, Token ist abgelaufen oder deaktiviert
2004 403 Keine Berechtigung zum Aufruf dieser API
3001 400 Ungültiges Format des Anfrageparameters, bitte prüfen Sie, ob der JSON-Inhalt dem Parameterformat entspricht
3002 400 Fehlerhafte Anfrageparameter, bitte prüfen Sie, ob die Anfrageparameter die Anforderungen erfüllen
3003 400 Fehler auf Geschäftsebene bei den Parametern, bitte prüfen Sie die Beschreibung im zurückgegebenen Feld message
Icon Solid Transparent White Qiyu
Vertrieb kontaktieren