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
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
}
}
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"
}
Fehlerantwort
{
"code": 3003,
"message": "not contains any channel config"
}
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
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>
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"
}
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"
}
}
}
Priorität bei der Variablenbefüllung
- Vorrang haben die in
template.paramsder Sende-Schnittstelle übergebenen Variablenwerte; - Werden diese nicht übergeben, werden die Standardwerte in
pre_param_mapder Vorlage verwendet; - 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 |










