Crear plantilla
Dirección de la llamada
POST https://otp.api.engagelab.cc/v1/template-configs
Autenticación de llamadas
Consulte Autenticación de llamadas para saber cómo autenticar la API.
Solicitud
Parámetros de la solicitud
Un objeto de solicitud se expresa en formato JSON, por lo que el encabezado de la solicitud debe incluir Content-Type: application/json.
| Parámetro | Tipo | Opción | Descripción |
|---|---|---|---|
| template_id | String | Obligatorio | ID de plantilla personalizado, único, limitado a 128 caracteres |
| description | String | Opcional | Descripción de la plantilla, limitada a 255 caracteres |
| send_channel_strategy | String | Obligatorio | Estrategia de la plantilla; para un único canal los valores son whatsapp/sms/email/voice, varios canales se separan con | y se reenvían en orden; email no puede combinarse con otros canales en una estrategia |
| brand_name | String | Opcional | Identificador de marca; en algunos estilos de plantilla con firma de marca se sustituye la variable de firma de marca; longitud limitada a entre 2 y 10 caracteres |
| verify_code_config | Object | Obligatorio condicional | Configuración del código de verificación; obligatorio cuando la plantilla incluye el tipo de código de verificación |
| verify_code_config.verify_code_type | Integer | Obligatorio | Tipo de código de verificación; rango de valores [1,7]; 1 números/2 letras minúsculas/4 letras mayúsculas, combinables (por ejemplo, 3 indica números + letras minúsculas) |
| verify_code_config.verify_code_len | Integer | Obligatorio | Longitud del código de verificación; rango de valores [4,10] |
| verify_code_config.verify_code_ttl | Integer | Obligatorio | Periodo de validez del código de verificación, en minutos; valores [1,10]; cuando la estrategia incluye whatsapp solo puede ser 1, 5 o 10 |
| whatsapp_config | Object | Obligatorio condicional | Configuración de la estrategia de whatsapp; obligatorio cuando la estrategia de envío incluye whatsapp |
| whatsapp_config.template_type | Integer | Obligatorio | Tipo de plantilla de whatsapp; actualmente solo se admite la plantilla predeterminada, fijo en 1 |
| whatsapp_config.template_default_config | Object | Obligatorio condicional | Configuración de la plantilla predeterminada de whatsapp; obligatorio cuando el tipo de plantilla de whatsapp es la predeterminada |
| sms_config | Object | Obligatorio condicional | Configuración de la estrategia de sms; obligatorio cuando la estrategia de envío incluye sms |
| sms_config.template_type | Integer | Obligatorio | Tipo de plantilla de sms; 1-plantilla predeterminada/2-plantilla personalizada |
| sms_config.template_default_config | Object | Obligatorio condicional | Configuración de la plantilla predeterminada de sms; obligatorio cuando el tipo de plantilla de sms es la predeterminada |
| sms_config.template_custom_config | Object | Obligatorio condicional | Configuración de la plantilla personalizada de sms; obligatorio cuando el tipo de plantilla de sms es la personalizada |
| sms_config.template_custom_config.custom_sub_type | String | Obligatorio | Tipo de plantilla personalizada; authentication-código de verificación/marketing-marketing/utility-notificación |
| sms_config.template_custom_config.custom_content | String | Obligatorio | Contenido de la plantilla personalizada; cuando es de tipo authentication debe incluir la variable {{code}} |
| sms_config.template_custom_config.custom_country_codes | String | Opcional | Códigos de los países o regiones de destino, separados por comas; se usan como referencia durante la revisión de la plantilla |
| voice_config | Object | Obligatorio condicional | Configuración de la estrategia de voice; obligatorio cuando la estrategia de envío incluye voice |
| voice_config.template_type | Integer | Obligatorio | Tipo de plantilla de voice; actualmente solo se admite la plantilla predeterminada, fijo en 1 |
| voice_config.template_default_config | Object | Obligatorio condicional | Configuración de la plantilla predeterminada de voice; obligatorio cuando el tipo de plantilla de voice es la predeterminada |
| email_config | Object | Obligatorio condicional | Configuración de la estrategia de email; obligatorio cuando la estrategia de envío incluye email |
| email_config.template_name | String | Obligatorio | Nombre de la plantilla de email |
| email_config.template_custom_configs | Array | Obligatorio condicional | Configuración de la plantilla personalizada de email; obligatorio cuando el tipo de plantilla de email es la personalizada; admite configuración multilingüe |
| email_config.template_custom_configs.language | String | Obligatorio | Idioma; default es el predeterminado; al enviar el mensaje se puede hacer coincidir distinto contenido de plantilla según el parámetro language |
| email_config.template_custom_configs.pre_from_name | String | Opcional | Nombre del remitente preestablecido |
| email_config.template_custom_configs.pre_from_mail | String | Obligatorio | Correo del remitente preestablecido |
| email_config.template_custom_configs.pre_subject | String | Obligatorio | Asunto del correo preestablecido |
| email_config.template_custom_configs.template_content | String | Obligatorio | Contenido del correo; admite HTML; las variables deben encerrarse entre {{}} |
| email_config.template_custom_configs.pre_param_map | Object | Opcional | Valores predeterminados de las variables del contenido del correo; se declaran como pares clave-valor, y el valor debe ser una cadena |
| pwa_config | Object | Opcional | Configuración relacionada con pwa; por el momento no es necesario usarla |
| pwa_config.pwa_platform | String | Opcional | Plataforma pwa utilizada; para conocer los valores concretos, póngase en contacto con el soporte técnico |
| pwa_config.pwa_code | String | Opcional | code de la plataforma pwa utilizada |
Ejemplo de solicitud
Encabezados de la solicitud
POST /v1/template-configs HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
Cuerpo de la solicitud
{
"template_id": "test-template-1", // ID de plantilla personalizado, único dentro de la aplicación
"description": "Plantilla de prueba 1", // Descripción de esta plantilla
"send_channel_strategy": "whatsapp|sms", // Estrategia de envío de la plantilla; admite whatsapp/sms/voice/email; una estrategia combinada usa el carácter | para indicar el reenvío en caso de fallo
"brand_name": "Nombre de marca", // Nombre de marca; se usa como firma en el contenido de las plantillas de algunos países o regiones (por ejemplo, en el canal SMS algunos países o regiones exigen registrar una firma)
"verify_code_config": { // Configuración del código de verificación; sirve para configurar el código de verificación generado automáticamente; obligatorio cuando la plantilla incluye el tipo de código de verificación
"verify_code_type": 1, // Tipo de código de verificación; rango de valores [1,7]
"verify_code_len": 6, // Longitud del código de verificación; rango de valores [4,10]
"verify_code_ttl": 1 // Periodo de validez del código de verificación; rango de valores [1,10]; cuando la estrategia incluye whatsapp el valor solo puede ser 1, 5 o 10
},
"whatsapp_config": { // Configuración de la estrategia de whatsapp; válida cuando la estrategia de envío incluye whatsapp
"template_type": 1, // Tipo de plantilla de whatsapp; actualmente solo se admite la plantilla predeterminada, es decir, valor fijo 1
"template_default_config": { // Configuración de la plantilla predeterminada de whatsapp; válida para el tipo de plantilla predeterminada
"contain_security": false, // Si se añade un aviso de seguridad
"contain_expire": false // Si se añade el contenido del tiempo de expiración
}
},
"sms_config": { // Configuración de la estrategia de sms; válida cuando la estrategia de envío incluye sms
"template_type": 2, // Tipo de plantilla de sms; valores: 1-plantilla predeterminada/2-plantilla personalizada
"template_default_config": { // Configuración de la plantilla predeterminada de sms; válida para el tipo de plantilla predeterminada
"contain_security": false, // Si se añade un aviso de seguridad
"contain_expire": false // Si se añade el contenido del tiempo de expiración
},
"template_custom_config": { // Configuración de la plantilla personalizada de sms; válida cuando el tipo de plantilla de sms es la personalizada
"custom_sub_type": "authentication", // Tipo de plantilla personalizada; valores: authentication-código de verificación/marketing-marketing/utility-notificación
"custom_content": "xxx", // Contenido de la plantilla personalizada; si el subtipo es authentication (código de verificación) debe incluir la variable {{code}}
"custom_country_codes": "HK,PH" // Países o regiones de destino de la plantilla personalizada; se usan como referencia durante la revisión de la plantilla; indíquelos según corresponda, de lo contrario podría afectar al envío real
}
},
"voice_config": { // Configuración de la estrategia de voice; válida cuando la estrategia de envío incluye voice
"template_type": 1, // Tipo de plantilla de voice; actualmente solo se admite la plantilla predeterminada, es decir, valor fijo 1
"template_default_config": { // Configuración de la plantilla predeterminada de voice; válida para el tipo de plantilla predeterminada
"contain_security": false, // Si se añade un aviso de seguridad
"contain_expire": false // Si se añade el contenido del tiempo de expiración
}
},
"email_config": { // Configuración de la estrategia de email; válida cuando la estrategia de envío incluye email
"template_name": "Nombre de la plantilla de email", // Nombre de la plantilla de email
"template_custom_configs": [{ // Configuración de la plantilla personalizada de email; tenga en cuenta que es un array de objetos, que se diferencian principalmente por language para configurar varias
"language": "default", // Idioma; default es el predeterminado; al enviar el mensaje se puede hacer coincidir distinto contenido de plantilla según el parámetro language
"pre_from_name": "test", // Nombre del remitente preestablecido
"pre_from_mail": "test@test.com", // Correo del remitente preestablecido
"pre_subject": "test", // Asunto del correo preestablecido
"template_content": "Contenido preestablecido de la plantilla de correo, obligatorio; variables personalizadas como {{self}}, el código de verificación es {{code}}", // Contenido del correo; admite HTML; las variables deben encerrarse entre dos llaves {{}}
"pre_param_map": { // Valores predeterminados de las variables del contenido del correo; es decir, si al enviar no se especifica el valor de una variable, se usa el valor predeterminado indicado a continuación para sustituirla; se declara como pares clave-valor, y el valor debe ser una cadena
"self": "Este es el valor preestablecido de la variable self"
}
}]
},
"pwa_config": { // Configuración relacionada con pwa; por el momento no es necesario usarla
"pwa_platform": "xx", // Plataforma pwa utilizada; para conocer los valores concretos, póngase en contacto con el soporte técnico
"pwa_code": "xx" // code de la plataforma pwa utilizada
}
}
Respuesta
Parámetros de la respuesta
| Campo | Tipo | Opción | Descripción |
|---|---|---|---|
| code | Integer | Obligatorio | Código de error; 0 indica éxito, los demás indican fallo |
| message | String | Obligatorio | Información de la respuesta |
Ejemplo de respuesta
Respuesta exitosa
{
"code": 0,
"message": "success"
}
Respuesta de error
{
"code": 3003,
"message": "not contains any channel config"
}
Uso avanzado de las variables de plantilla de Email
Cuando habilita el canal Email en la estrategia de envío, puede personalizar ampliamente el asunto y el contenido del correo. Mediante los marcadores de posición de variables {{variable}}, se pueden rellenar automáticamente el código de verificación, la información de marca y otros contenidos, lo que permite una experiencia de correo personalizada y flexible.
Tipos de variables y uso
Tanto el cuerpo de la plantilla de Email (template_content) como el asunto (pre_subject) pueden incluir variables con el formato {{variable}}.
La API de envío las pasa dinámicamente mediante el campo template.params, o bien se establecen valores predeterminados en la fase de creación de la plantilla.
Variables admitidas
Las siguientes variables solo se aplican al canal Email.
| Variable | Tipo | Descripción | Forma de relleno |
|---|---|---|---|
{{logo_url}} |
Variable personalizada | Dirección de la imagen del logotipo de marca | Se pasa al enviar mediante template.params |
{{title}} |
Variable personalizada | Texto del título del cuerpo del correo | Se pasa al enviar mediante template.params |
{{support_email}} |
Variable personalizada | Dirección de correo de atención al cliente/soporte | Se pasa al enviar mediante template.params |
{{subject}} |
Variable personalizada | Sobrescribe dinámicamente el asunto del correo | Se pasa al enviar mediante template.params |
{{from_name}} |
Variable personalizada | Sobrescribe dinámicamente el nombre del remitente | Se pasa al enviar mediante template.params |
{{from_mail}} |
Variable personalizada | Sobrescribe dinámicamente el correo del remitente | Se pasa al enviar mediante template.params |
Nota: las variables especiales
{{subject}},{{from_name}}y{{from_mail}}no se insertan en el HTML del cuerpo, sino que sobrescriben directamente los campos de metadatos del correo.
Ejemplo de asunto del correo
Código de verificación de {{brand_name}}
Ejemplo de cuerpo del correo
<img src="{{logo_url}}" />
<strong>{{title}}</strong>
<p>Su código de verificación es <strong>{{code}}</strong>; complete la verificación en un plazo de {{ttl}} minutos.</p>
<p>Si tiene alguna duda, póngase en contacto con <a href="mailto:{{support_email}}">{{support_email}}</a></p>
Configuración de valores predeterminados de la plantilla
Al crear la plantilla, puede establecer los valores predeterminados de las variables personalizadas en el campo pre_param_map. Si al enviar el correo no se pasa una variable, se usará automáticamente el valor predeterminado.
"pre_param_map": {
"logo_url": "https://example.com/logo.png",
"title": "Su código de verificación",
"support_email": "support@example.com"
}
Descripción de los parámetros de envío
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
to |
string | Sí | Dirección de correo de destino |
template.id |
string | Sí | ID de la plantilla de correo |
template.language |
string | No | Código de idioma; predeterminado default |
template.params |
object | No | Asignación de las variables de la plantilla (sin {{}}) |
Ejemplo de solicitud:
{
"to": "user@example.com",
"template": {
"id": "my_email_template",
"language": "default",
"params": {
"logo_url": "https://example.com/logo.png",
"title": "Su código de verificación",
"support_email": "support@example.com"
}
}
}
Prioridad de relleno de variables
- Tiene prioridad el valor de la variable pasado en
template.paramsde la interfaz de envío; - Si no se pasa, se usa el valor predeterminado de
pre_param_mapde la plantilla; - Si ninguno de los dos está establecido, el marcador de posición se muestra tal cual en el contenido del correo.
Preguntas frecuentes
P: ¿Por qué no se sustituye una variable?
R: Compruebe que el nombre y el formato de la variable son correctos (debe ser {{variable}}) y asegúrese de haber proporcionado el valor mediante template.params o de haber establecido un valor predeterminado en la plantilla.
P: ¿Cómo establecer dinámicamente el asunto del correo y el remitente?
R: Pase subject, from_name y from_mail dentro del parámetro de solicitud template.params para sobrescribir dinámicamente el asunto y la información del remitente preestablecidos en la plantilla.
Códigos de error
| Código de error | http code | Descripción |
|---|---|---|
| 1000 | 500 | Error interno |
| 2001 | 401 | Error de autenticación; no se incluyó un token correcto |
| 2002 | 401 | Error de autenticación; el token ha expirado o ha sido deshabilitado |
| 2004 | 403 | Sin permiso para llamar a esta API |
| 3001 | 400 | Formato de los parámetros de la solicitud no válido; compruebe que el contenido JSON cumple el formato de los parámetros |
| 3002 | 400 | Parámetros de la solicitud incorrectos; compruebe que los parámetros de la solicitud cumplen los requisitos |
| 3003 | 400 | Error de parámetros a nivel de negocio; consulte la descripción del campo message devuelto |










