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
              
              POST /v1/template-configs  HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

            
Este bloque de código se muestra en una ventana flotante

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

            
Este bloque de código se muestra en una ventana flotante

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

            
Este bloque de código se muestra en una ventana flotante

Respuesta de error

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

            
Este bloque de código se muestra en una ventana flotante

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}}
              
              Código de verificación de {{brand_name}}

            
Este bloque de código se muestra en una ventana flotante

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

            
Este bloque de código se muestra en una ventana flotante

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" }
              
              "pre_param_map": {
  "logo_url": "https://example.com/logo.png",
  "title": "Su código de verificación",
  "support_email": "support@example.com"
}

            
Este bloque de código se muestra en una ventana flotante

Descripción de los parámetros de envío

Campo Tipo Obligatorio Descripción
to string Dirección de correo de destino
template.id string 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" } } }
              
              {
  "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"
    }
  }
}

            
Este bloque de código se muestra en una ventana flotante

Prioridad de relleno de variables

  1. Tiene prioridad el valor de la variable pasado en template.params de la interfaz de envío;
  2. Si no se pasa, se usa el valor predeterminado de pre_param_map de la plantilla;
  3. 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
Icon Solid Transparent White Qiyu
Contacto