API de gestión de plantillas

Visión general

Con la API de gestión de plantillas puedes crear, eliminar, modificar y consultar las plantillas de una WABA, además de agrupar plantillas mediante etiquetas personalizadas. Este documento incluye dos grupos de endpoints:

Endpoints de plantillas: Obtener plantillas, Consultar información de una plantilla, Subir archivo multimedia de ejemplo, Crear plantilla, Actualizar plantilla, Eliminar plantilla.
Endpoints de etiquetas: Obtener lista de etiquetas, Crear etiqueta, Modificar etiqueta, Eliminar etiqueta, Asignar etiquetas a una plantilla. Las etiquetas se aplican dentro de la WABA a la que pertenece la clave de API actual. Se usan únicamente para la gestión de plantillas en el lado de EngageLab: no modifican el contenido de las plantillas de WhatsApp ni provocan una nueva revisión por parte de Meta.

Validación de la llamada

EngageLab REST API utiliza la autenticación básica HTTP como método de verificación: añade el encabezado HTTP Authorization:

Authorization: Basic ${base64_auth_string}

              
              Authorization: Basic ${base64_auth_string}

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

El algoritmo de generación de base64_auth_string es el siguiente: base64(dev_key:dev_secret)

El nombre del encabezado es "Authorization" y el valor es un par "username:password" convertido a base64 (con dos puntos en medio).
En el escenario de la API de WhatsApp, el nombre de usuario es DevKey y la contraseña es DevSecret. Puedes obtenerlos en la consola, en Gestión de configuración – clave de API.

Obtener plantillas

Dirección de llamada

GET https://wa.api.engagelab.cc/v1/templates

Parámetros de la solicitud

Parámetro	Tipo	Opción	Descripción
name	String	Opcional	Nombre de la plantilla. Ten en cuenta que este campo usa coincidencia parcial.
language_code	String	Opcional	Idioma de la plantilla, consulta Códigos de idioma.
category	String	Opcional	Categoría de la plantilla. ● AUTHENTICATION: código de verificación ● MARKETING: marketing ● UTILITY: notificación de servicio
status	String	Opcional	Estado de la plantilla: APPROVED - aprobada PENDING - en revisión REJECTED - rechazada PENDING_DELETION - en proceso de eliminación DELETED - eliminada DISABLED - deshabilitada (bloqueada) IN_APPEAL - en apelación PAUSED - pausada Los desarrolladores deben prestar atención principalmente a APPROVED/PENDING/REJECTED/DISABLED.
tag_id	String	Opcional	ID de etiqueta, para filtrar plantillas por etiqueta. Valores admitidos: Omitido o cadena vacía - no filtrar por etiqueta Un ID de etiqueta - devolver solo las plantillas que tengan esa etiqueta `ungrouped` - devolver solo las plantillas sin ninguna etiqueta; no distingue mayúsculas y minúsculas

tag_id tiene una relación AND con el resto de condiciones de búsqueda, como name, language_code, category y status. Actualmente no se admite enviar varias etiquetas a la vez. Si el formato de tag_id no es válido, se devuelve el código de error 3002; si la etiqueta no existe o no pertenece a la WABA actual, se devuelve el código de error 4001.

Nota: Si en la WABA existe una etiqueta llamada "ungrouped" (o su equivalente traducido), para filtrar por ella debes enviar su ID numérico. Enviar ungrouped directamente se interpreta siempre como "filtrar las plantillas sin ninguna etiqueta".

Ejemplo de solicitud

Filtrar por etiqueta:

GET https://wa.api.engagelab.cc/v1/templates?tag_id=101

              
              GET https://wa.api.engagelab.cc/v1/templates?tag_id=101

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

Filtrar las plantillas sin ninguna etiqueta:

GET https://wa.api.engagelab.cc/v1/templates?tag_id=ungrouped

              
              GET https://wa.api.engagelab.cc/v1/templates?tag_id=ungrouped

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

Parámetros de la respuesta

Parámetro	Tipo	Opción	Descripción
id	String	Obligatorio	ID de la plantilla
name	String	Obligatorio	Nombre de la plantilla
language	String	Obligatorio	Idioma de la plantilla, consulta Códigos de idioma.
category	String	Obligatorio	Categoría de la plantilla. AUTHENTICATION MARKETING UTILITY
components	Object Array	Obligatorio	Componentes del contenido de la plantilla, consulta el objeto components en Crear plantilla.
status	String	Obligatorio	Estado de la plantilla: APPROVED - aprobada PENDING - en revisión REJECTED - rechazada PENDING_DELETION - en proceso de eliminación DELETED - eliminada DISABLED - deshabilitada (bloqueada) IN_APPEAL - en apelación PAUSED - pausada Los desarrolladores deben prestar atención principalmente a APPROVED/PENDING/REJECTED/DISABLED.
tags	Object Array	Obligatorio	Etiquetas asignadas actualmente a la plantilla. Devuelve un array vacío si no hay ninguna. tags[].id - String, ID de la etiqueta tags[].name - String, nombre de la etiqueta

Ejemplo de respuesta

// Un array JSON en el que cada objeto contiene la información de una plantilla [ { "id": "406979728071589", // ID de la plantilla "name": "code", // nombre de la plantilla "language": "zh_CN", // idioma de la plantilla "status": "APPROVED", // estado; APPROVED significa aprobada y disponible "category": "OTP", // categoría; actualmente se admiten OTP/TRANSACTIONAL/MARKETING "components": [ // contenido de la plantilla; puede incluir HEADER/BODY/FOOTER/BUTTON { "type": "HEADER", "format": "text", // formato; se admiten text/image/location/video/document, TEXT por defecto "text": "Código de registro" // contenido de texto; obligatorio cuando format es text }, { "type": "BODY", "text": "Tu código de verificación es {{1}}. Introdúcelo en un plazo de 5 minutos." // el texto entre llaves dobles {{}} es una variable de plantilla } ], "tags": [ // etiquetas asignadas a esta plantilla; array vacío si no hay ninguna { "id": "101", "name": "Notificación de envío" } ] }, ...... ]

              
              // Un array JSON en el que cada objeto contiene la información de una plantilla
[
    {
        "id": "406979728071589", // ID de la plantilla
        "name": "code", // nombre de la plantilla
        "language": "zh_CN", // idioma de la plantilla
        "status": "APPROVED", // estado; APPROVED significa aprobada y disponible
        "category": "OTP", // categoría; actualmente se admiten OTP/TRANSACTIONAL/MARKETING
        "components": [ // contenido de la plantilla; puede incluir HEADER/BODY/FOOTER/BUTTON
            {
                "type": "HEADER",
                "format": "text", // formato; se admiten text/image/location/video/document, TEXT por defecto
                "text": "Código de registro" // contenido de texto; obligatorio cuando format es text
            },
            {
                "type": "BODY",
                "text": "Tu código de verificación es {{1}}. Introdúcelo en un plazo de 5 minutos." // el texto entre llaves dobles {{}} es una variable de plantilla
            }
        ],
        "tags": [ // etiquetas asignadas a esta plantilla; array vacío si no hay ninguna
            {
                "id": "101",
                "name": "Notificación de envío"
            }
        ]
    },
    ......
]

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

Consultar información de una plantilla

Dirección de llamada

GET https://wa.api.engagelab.cc/v1/templates/{template_id}

Donde {template_id} es el ID de la plantilla que quieres consultar.

Parámetros de la solicitud

NULL

Ejemplo de solicitud

GET https://wa.api.engagelab.cc/v1/templates/406979728071589

              
              GET https://wa.api.engagelab.cc/v1/templates/406979728071589

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

Parámetros de la respuesta

Parámetro	Tipo	Opción	Descripción
id	String	Obligatorio	ID de la plantilla
name	String	Obligatorio	Nombre de la plantilla
language	String	Obligatorio	Idioma de la plantilla, consulta Códigos de idioma.
category	String	Obligatorio	Categoría de la plantilla. OTP: contraseña de un solo uso MARKETING: marketing TRANSACTIONAL: transaccional Nota: las categorías de plantilla se actualizaron, a más tardar el 1 de mayo de 2023, a: AUTHENTICATION MARKETING UTILITY
components	Object Array	Obligatorio	Componentes del contenido de la plantilla, consulta el objeto components en Crear plantilla.
status	String	Obligatorio	Estado de la plantilla: APPROVED, IN_APPEAL, PENDING, REJECTED, PENDING_DELETION, DELETED, DISABLED, PAUSED, LIMIT_EXCEEDED
tags	Object Array	Obligatorio	Etiquetas asignadas actualmente a la plantilla. Devuelve un array vacío si no hay ninguna. tags[].id - String, ID de la etiqueta tags[].name - String, nombre de la etiqueta

Ejemplo de respuesta

{ "id": "406979728071589", // ID de la plantilla "name": "code", // nombre de la plantilla "language": "zh_CN", // idioma de la plantilla "status": "APPROVED", // estado; APPROVED significa aprobada y disponible "category": "OTP", // categoría; actualmente se admiten OTP/TRANSACTIONAL/MARKETING "components": [ // contenido de la plantilla; puede incluir HEADER/BODY/FOOTER/BUTTON { "type": "HEADER", "format": "text", // formato; se admiten text/image/location/video/document, TEXT por defecto "text": "Código de registro" // contenido de texto; obligatorio cuando format es text }, { "type": "BODY", "text": "Tu código de verificación es {{1}}. Introdúcelo en un plazo de 5 minutos." // el texto entre llaves dobles {{}} es una variable de plantilla } ], "tags": [ // etiquetas asignadas a esta plantilla; array vacío si no hay ninguna { "id": "101", "name": "Notificación de envío" } ] }

              
              {
    "id": "406979728071589", // ID de la plantilla
    "name": "code", // nombre de la plantilla
    "language": "zh_CN", // idioma de la plantilla
    "status": "APPROVED", // estado; APPROVED significa aprobada y disponible
    "category": "OTP", // categoría; actualmente se admiten OTP/TRANSACTIONAL/MARKETING
    "components": [ // contenido de la plantilla; puede incluir HEADER/BODY/FOOTER/BUTTON
        {
            "type": "HEADER",
            "format": "text", // formato; se admiten text/image/location/video/document, TEXT por defecto
            "text": "Código de registro" // contenido de texto; obligatorio cuando format es text
        },
        {
            "type": "BODY",
            "text": "Tu código de verificación es {{1}}. Introdúcelo en un plazo de 5 minutos." // el texto entre llaves dobles {{}} es una variable de plantilla
        }
    ],
    "tags": [ // etiquetas asignadas a esta plantilla; array vacío si no hay ninguna
        {
            "id": "101",
            "name": "Notificación de envío"
        }
    ]
}

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

Subir archivo multimedia de ejemplo

Al crear o editar una plantilla con encabezado multimedia (image, video, document), Meta exige que el archivo se suba antes a sus servidores. Esta API sube el archivo de ejemplo de la plantilla y devuelve un handle_id, que debes indicar en el campo header_handle del endpoint de creación o edición de plantillas.

Dirección de llamada

POST https://wa.api.engagelab.cc/v1/media/handles

Parámetros de la solicitud

Content-Type: multipart/form-data

Parámetro	Tipo	Opción	Descripción
file	file	Obligatorio	Archivo multimedia de ejemplo. Tamaño máximo 20 MB. Consulta los requisitos de formato en Requisitos de formato de los mensajes multimedia.

Ejemplo de solicitud

POST '/v1/media/handles' --header 'Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0' --form 'file=@"/Users/demo/files/demopic.jpeg"'

              
              POST '/v1/media/handles' 
--header 'Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0' 
--form 'file=@"/Users/demo/files/demopic.jpeg"'

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

Parámetros de la respuesta

Respuesta correcta

Campo	Tipo	Opción	Descripción
handle_id	String	Obligatorio	Identificador de archivo devuelto por Meta, que debes indicar en el campo `example.header_handle` al crear o editar una plantilla.

Ejemplo de respuesta:

{ "handle_id": "4::aW1hZ2UvanBlZw==:ARb2JGd8LbvJbfmpMASFAlczcn4hxLC6tkwjasjD4WL6_i34tIisq0IdWNFFFj1KwJMRXPU4xwygHSJd4DHu1f19LcBBl2qeb8EuEcgnIUPYIQ:e:1682169041:4985146461608173:100084026087657:ARazr9kxfzKshJE4WpY" }

              
              {
    "handle_id": "4::aW1hZ2UvanBlZw==:ARb2JGd8LbvJbfmpMASFAlczcn4hxLC6tkwjasjD4WL6_i34tIisq0IdWNFFFj1KwJMRXPU4xwygHSJd4DHu1f19LcBBl2qeb8EuEcgnIUPYIQ:e:1682169041:4985146461608173:100084026087657:ARazr9kxfzKshJE4WpY"
}

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

Respuesta de error

El código de estado HTTP es 4xx o 5xx y el cuerpo de la respuesta contiene los siguientes campos:

Campo	Tipo	Opción	Descripción
code	int	Obligatorio	Código de error
message	String	Obligatorio	Detalle del error

Ejemplo de respuesta:

{ "code": 3002, "message": "whatsapp.template field must be set correctly when type is template" }

              
              {
    "code": 3002,
    "message": "whatsapp.template field must be set correctly when type is template"
}

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

Crear plantilla

Dirección de llamada

POST https://wa.api.engagelab.cc/v1/templates

Ejemplo de llamada

{ "name": "template_name", // nombre de la plantilla; se permiten nombres repetidos; solo se admiten letras minúsculas, dígitos y guiones bajos "language": "zh_CN", // idioma de la plantilla; dos plantillas con el mismo nombre no pueden usar el mismo idioma "category": "OTP", // categoría; actualmente se admiten OTP/TRANSACTIONAL/MARKETING "components": [ { // contenido de la plantilla "type": "BODY", // bloque de contenido; actualmente se admiten HEADER/BODY/FOOTER/BUTTONS "text": "define var as {{1}}" // el texto en sí; el campo format no es necesario cuando el body es texto "example": { "body_text": [ [ "var1" ] ] } }, { "type": "HEADER", "format": "image", // tipo de contenido; se admiten text/image/video/document/location "example": { "header_handle": [ "https://jiguang.cn/demopic.jpg" ] } }, { "type": "FOOTER", "text": "footer only support text without variable" }, { "type": "BUTTONS", "buttons": [ { "type": "PHONE_NUMBER", // tipo de botón; se admiten PHONE_NUMBER/URL/QUICK_REPLY "text": "this is a phone number", "phone_number": "8613800138000" } ] } ] }

              
              {
    "name": "template_name", // nombre de la plantilla; se permiten nombres repetidos; solo se admiten letras minúsculas, dígitos y guiones bajos
    "language": "zh_CN", // idioma de la plantilla; dos plantillas con el mismo nombre no pueden usar el mismo idioma
    "category": "OTP", // categoría; actualmente se admiten OTP/TRANSACTIONAL/MARKETING
    "components": [
        { // contenido de la plantilla
            "type": "BODY", // bloque de contenido; actualmente se admiten HEADER/BODY/FOOTER/BUTTONS
            "text": "define var as {{1}}" // el texto en sí; el campo format no es necesario cuando el body es texto
          "example": {
                "body_text": [
                    [
                        "var1"
                    ]
                ]
            }
        },
        {
            "type": "HEADER",
            "format": "image", // tipo de contenido; se admiten text/image/video/document/location
            "example": {
                "header_handle": [
                    "https://jiguang.cn/demopic.jpg"
                ]
            }
        },
        {
            "type": "FOOTER",
            "text": "footer only support text without variable"
        },
        {
            "type": "BUTTONS",
            "buttons": [
                {
                    "type": "PHONE_NUMBER", // tipo de botón; se admiten PHONE_NUMBER/URL/QUICK_REPLY              
                    "text": "this is a phone number",
                    "phone_number": "8613800138000"
                }
            ]
        }
    ]
}

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

Parámetros de la solicitud

Parámetro	Tipo	Opción	Descripción
name	String	Obligatorio	Nombre de la plantilla. Solo se admiten letras minúsculas, dígitos y guiones bajos, con un máximo de 512 caracteres.
language	String	Obligatorio	Idioma de la plantilla, consulta Códigos de idioma.
category	String	Obligatorio	Categoría de la plantilla. OTP: contraseña de un solo uso MARKETING: marketing TRANSACTIONAL: transaccional Nota: las categorías de plantilla se actualizaron, a más tardar el 1 de mayo de 2023, a: AUTHENTICATION MARKETING UTILITY
components	Object Array	Obligatorio	Componentes que describen el contenido de la plantilla, consulta el objeto components. Ten en cuenta que debe incluirse un componente con type=BODY.

Objeto components

Este objeto describe el contenido de la plantilla. Una plantilla se compone de los componentes «encabezado HEADER», «cuerpo BODY», «pie FOOTER» y «botones BUTTONS», que se indican con type. Cada tipo de componente admite parámetros distintos:

Componente header

El componente header es opcional en su conjunto. Si no necesitas encabezado, no incluyas este componente.

Parámetro	Tipo	Opción	Descripción
type	String	Obligatorio	Tipo de componente, valor HEADER
format	String	Obligatorio	Formato del encabezado, valores: text, image, video, document, que corresponden a texto, imagen, vídeo y archivo.
text	String	Opcional	Contenido de texto del encabezado. Debes definir este campo cuando format=text. El texto del encabezado puede incluir una variable, pero solo se admite 1, representada como {{1}}.
example	JSON Object	Opcional	Ejemplo del encabezado. Es obligatorio cuando text contiene una variable o format es un tipo multimedia. Consulta la descripción del objeto example.

Descripción del objeto example

Parámetro	Tipo	Opción	Descripción
header_handle	String Array	Opcional	Obligatorio cuando format es image, video o document. Este campo ya no admite una URL multimedia; debes enviar el handle_id obtenido mediante la API para subir archivos multimedia de ejemplo.
header_text	String Array	Opcional	Cuando format es text y contiene una variable, envía en este campo el valor de sustitución de esa variable. Por ejemplo: "header_text": ["var1"]

Componente body

El componente body es obligatorio; debes definir el contenido del cuerpo.

Parámetro	Tipo	Opción	Descripción
type	String	Obligatorio	Tipo de componente, valor BODY
text	String	Obligatorio	Contenido del cuerpo, con un máximo de 1024 caracteres. Admite varias variables. Una variable se compone de llaves dobles más el número de la variable; la numeración debe empezar en 1 y ser creciente, por ejemplo {{1}} y {{2}}.
example	JSON Object	Opcional	Ejemplo del cuerpo. Los revisores de Meta valoran a partir del ejemplo si tu mensaje cumple las normas. Consulta la descripción del objeto example. Es obligatorio cuando text contiene variables.

Descripción del objeto example

Parámetro	Tipo	Opción	Descripción
body_text	String Array	Opcional	Cuando text contiene variables, envía en este campo los valores de sustitución de todas las variables, en el orden de su numeración. Por ejemplo: "body_text": [["var1","var2","var3"]]

El componente footer es opcional en su conjunto. Si no necesitas pie, no incluyas este componente.

Parámetro	Tipo	Opción	Descripción
type	String	Obligatorio	Tipo de componente, valor FOOTER
text	String	Obligatorio	Contenido del pie. Solo texto plano; no se pueden definir variables.

Componente buttons

El componente buttons es opcional en su conjunto. Si no necesitas botones, no incluyas este componente.

Parámetro	Tipo	Opción	Descripción
type	String	Obligatorio	Tipo de componente, valor BUTTONS
buttons	Object Array	Obligatorio	Información de los botones, consulta la descripción del objeto buttons.

Descripción del objeto buttons

Parámetro	Tipo	Opción	Descripción
type	String	Obligatorio	Tipo de botón, valores: QUICK_REPLY, URL, PHONE_NUMBER, que corresponden a respuesta rápida, visitar sitio web y llamar por teléfono.
text	String	Obligatorio	El texto que se muestra en el botón. No puede contener variables; solo texto plano, con un máximo de 25 caracteres.
url	String	Opcional	Obligatorio cuando type=URL. Puedes añadir una variable al final de la URL, pero solo se admite 1, representada como {{1}}.
phone_number	String	Opcional	Obligatorio cuando type=PHONE_NUMBER. No puede contener variables. El valor es un número de teléfono con prefijo internacional.
example	String Array	Opcional	Obligatorio cuando type=QUICK_REPLY y type=URL. Por ejemplo: "example": ["`https://www.website.com/dynamic-url-example`"]

Consideraciones especiales sobre las plantillas de autenticación

Aspectos a tener en cuenta

Para las plantillas de la categoría de autenticación (es decir, AUTHENTICATION):

No incluyas un componente HEADER en Components.
El texto del contenido de la plantilla se localiza automáticamente según el campo language de la plantilla.
En el modo ONE_TAP, que abre una aplicación, actualmente solo se admiten aplicaciones Android y debes implementar el correspondiente handshake en tu aplicación. Para conocer los detalles, consulta la documentación oficial: plantillas de autenticación.
Los campos que se envían al crear la plantilla no coinciden con los campos que WhatsApp registra tras la creación: en esencia, WhatsApp sustituye BODY, FOOTER y BUTTONS en las plantillas de esta categoría. Por eso, presta especial atención al enviar mensajes de plantilla: debes añadir la variable del botón. Para más detalles, consulta la documentación de la API de envío de mensajes.

Ejemplo de COPY_CODE

Datos enviados:

{ "name": "copycodetmpl", "language": "zh_CN", "category": "AUTHENTICATION", "components": [ { // body es obligatorio "type": "BODY", "add_security_recommendation": true // si se añade el texto de recomendación de seguridad }, { // footer es opcional "type": "FOOTER", "code_expiration_minutes": 2 // añade la indicación del tiempo de caducidad, rango [1,90]; omite el campo si no lo necesitas }, { "type": "BUTTONS", "buttons": [ { "type": "OTP", "otp_type": "copy_code", "text": "copy it" // límite de 25 caracteres } ] } ] }

              
              {
    "name": "copycodetmpl",
    "language": "zh_CN",
    "category": "AUTHENTICATION",
    "components": [
        {
            // body es obligatorio
            "type": "BODY",
            "add_security_recommendation": true  // si se añade el texto de recomendación de seguridad
            
        },
        {
            // footer es opcional
            "type": "FOOTER",		
            "code_expiration_minutes": 2    // añade la indicación del tiempo de caducidad, rango [1,90]; omite el campo si no lo necesitas
        },
        {
            "type": "BUTTONS",          
            "buttons": [
                {
                    "type": "OTP",
                    "otp_type": "copy_code",
                    "text": "copy it"      // límite de 25 caracteres
                }
            ]
        }
    ]
}

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

Contenido de la plantilla que WhatsApp registra realmente tras la creación:

{ "name": "copycodetmpl", "language": "zh_CN", "category": "AUTHENTICATION", "components": [ { "type": "BODY", "text": "*{{1}}* es tu código de verificación. Por tu seguridad, no compartas este código.", "example": { "body_text": [ ["123456"] ] } }, { "type": "FOOTER", "text": "Este código caduca en 2 minutos." }, { "type": "BUTTONS", "buttons": [{ "type": "URL", "text": "Copy code", "url": "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp{{1}}", "example": [ "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp123456" ] }] } ] }

              
              {
    "name": "copycodetmpl",
    "language": "zh_CN",
    "category": "AUTHENTICATION",
    "components": [
        {
            "type": "BODY",
            "text": "*{{1}}* es tu código de verificación. Por tu seguridad, no compartas este código.",
            "example": {
                "body_text": [
                    ["123456"]
                ]
            }
        },
        {
            "type": "FOOTER",
            "text": "Este código caduca en 2 minutos."
        },
        {
            "type": "BUTTONS",
            "buttons": [{
              "type": "URL",
              "text": "Copy code",
              "url": "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp{{1}}",
              "example": [
                  "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp123456"
              ]
          }]
        }
    ]
}

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

Ejemplo de ONE_TAP

Datos enviados:

{ "name": "copycodetmpl", "language": "zh_CN", "category": "AUTHENTICATION", "components": [ { // body es obligatorio "type": "BODY", "add_security_recommendation": true // si se añade el texto de recomendación de seguridad }, { // footer es opcional "type": "FOOTER", "code_expiration_minutes": 2 // añade la indicación del tiempo de caducidad, rango [1,90]; omite el campo si no lo necesitas }, { "type": "BUTTONS", "buttons": [ { "type": "OTP", "otp_type": "one_tap", "text": "auto1", // límite de 25 caracteres "autofill_text": "auto1", // límite de 25 caracteres "package_name": "ppssd", "signature_hash": "asds" } ] } ] }

              
              {
    "name": "copycodetmpl",
    "language": "zh_CN",
    "category": "AUTHENTICATION",
    "components": [
        {
            // body es obligatorio
            "type": "BODY",
            "add_security_recommendation": true  // si se añade el texto de recomendación de seguridad
            
        },
        {
            // footer es opcional
            "type": "FOOTER",		
            "code_expiration_minutes": 2    // añade la indicación del tiempo de caducidad, rango [1,90]; omite el campo si no lo necesitas
        },
        {
            "type": "BUTTONS",          
            "buttons": [
                {
                    "type": "OTP",
                    "otp_type": "one_tap",
                    "text": "auto1",      // límite de 25 caracteres
                    "autofill_text": "auto1",      // límite de 25 caracteres
                    "package_name": "ppssd",    
                    "signature_hash": "asds"  
                }
            ]
        }
    ]
}

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

Contenido de la plantilla que WhatsApp registra realmente tras la creación:

{ "name": "copycodetmpl", "language": "zh_CN", "category": "AUTHENTICATION", "components": [ { "type": "BODY", "text": "*{{1}}* es tu código de verificación. Por tu seguridad, no compartas este código.", "example": { "body_text": [ ["123456"] ] } }, { "type": "FOOTER", "text": "Este código caduca en 2 minutos." }, { "type": "BUTTONS", "buttons": [{ "type": "URL", "text": "copy1", "url": "https://www.whatsapp.com/otp/code/?otp_type=ONE_TAP&cta_display_name=auto1&package_name=ppssd&signature_hash=asds&code=otp{{1}}", "example": ["https://www.whatsapp.com/otp/code/?otp_type=ONE_TAP&cta_display_name=auto1&package_name=ppssd&signature_hash=asds&code=otp123456"] }] } ] }

              
              {
    "name": "copycodetmpl",
    "language": "zh_CN",
    "category": "AUTHENTICATION",
    "components": [
        {
            "type": "BODY",
            "text": "*{{1}}* es tu código de verificación. Por tu seguridad, no compartas este código.",
            "example": {
                "body_text": [
                    ["123456"]
                ]
            }
        },
        {
            "type": "FOOTER",
            "text": "Este código caduca en 2 minutos."
        },
        {
            "type": "BUTTONS",
            "buttons": [{
                "type": "URL",
                "text": "copy1",
                "url": "https://www.whatsapp.com/otp/code/?otp_type=ONE_TAP&cta_display_name=auto1&package_name=ppssd&signature_hash=asds&code=otp{{1}}",
                "example": ["https://www.whatsapp.com/otp/code/?otp_type=ONE_TAP&cta_display_name=auto1&package_name=ppssd&signature_hash=asds&code=otp123456"]
            }]
        }
    ]
}

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

Parámetros de la respuesta

Respuesta correcta

Parámetro	Tipo	Opción	Descripción
template_id	String	Obligatorio	ID de la plantilla, se devuelve cuando la operación tiene éxito

{ "template_id": "1275172986566180" // ID de la plantilla }

              
              {
    "template_id": "1275172986566180"		// ID de la plantilla
}

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

Respuesta de error

Parámetro	Tipo	Opción	Descripción
code	int	Obligatorio	Código de error, se devuelve en caso de fallo
message	String	Obligatorio	Mensaje de error, se devuelve en caso de fallo

{ "code": 5002, "message": "Invalid parameter. code:100:2388042" }

              
              {
    "code": 5002,
    "message": "Invalid parameter. code:100:2388042"
}

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

Actualizar plantilla

Dirección de llamada

PUT https://wa.api.engagelab.cc/v1/templates/{templateId}

Ejemplo de llamada

{ "components": [{ // contenido de la plantilla "type": "BODY", // bloque de contenido "text": "define var as {{1}}", "example": { "body_text": [["var1"]] } },{ "type": "HEADER", "format": "image", // tipo de contenido: image/video/document "example": { // Nota: aquí debes indicar el handle_id devuelto por el endpoint de subida; ya no se admite una URL de imagen "header_handle": ["4::aW1hZ2UvanBlZw==:ARb2JGd8LbvJbfmpMASFAlcz..."] } },{ "type": "FOOTER", "text": "footer only support text without variable" },{ "type": "BUTTONS", "buttons": [{ "type": "PHONE_NUMBER", "text": "this is a phone number", "phone_number": "8613800138000" }] }] }

              
              {
    "components": [{                        // contenido de la plantilla
        "type": "BODY",                     // bloque de contenido
        "text": "define var as {{1}}", 
        "example": {
            "body_text": [["var1"]]
        }
    },{
        "type": "HEADER",
        "format": "image",                  // tipo de contenido: image/video/document
        "example": {
            // Nota: aquí debes indicar el handle_id devuelto por el endpoint de subida; ya no se admite una URL de imagen
            "header_handle": ["4::aW1hZ2UvanBlZw==:ARb2JGd8LbvJbfmpMASFAlcz..."]
        }
    },{
        "type": "FOOTER",
        "text": "footer only support text without variable"
    },{
        "type": "BUTTONS",
        "buttons": [{                                     
            "type": "PHONE_NUMBER",              
            "text": "this is a phone number",              
            "phone_number": "8613800138000"
        }]
    }]
}

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

Parámetros de la solicitud

Iguales que los parámetros de la solicitud del endpoint de creación de plantillas.

Parámetros de la respuesta

Respuesta correcta

Parámetro	Tipo	Opción	Descripción
code	int	Obligatorio	Código de respuesta, siempre 0
message	String	Obligatorio	Mensaje de respuesta, siempre success

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

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

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

Respuesta de error

Parámetro	Tipo	Opción	Descripción
code	int	Obligatorio	Código de error, se devuelve en caso de fallo
message	String	Obligatorio	Mensaje de error, se devuelve en caso de fallo

{ "code": 5002, "message": "Invalid parameter. code:100:2593002" }

              
              {
    "code": 5002,
    "message": "Invalid parameter. code:100:2593002"
}

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

Eliminar plantilla

Dirección de llamada

DELETE https://wa.api.engagelab.cc/v1/templates/{template_name}
Nota: aquí se envía el nombre de la plantilla, no su ID. Se eliminarán todas las versiones de idioma de la plantilla con ese nombre.

Parámetros de la respuesta

Respuesta correcta

Parámetro	Tipo	Opción	Descripción
code	int	Obligatorio	Código de respuesta, siempre 0
message	String	Obligatorio	Mensaje de respuesta, siempre success

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

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

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

Respuesta de error

Parámetro	Tipo	Opción	Descripción
code	int	Obligatorio	Código de error, se devuelve en caso de fallo
message	String	Obligatorio	Mensaje de error, se devuelve en caso de fallo

{ "code": 2004, "message": "something error" }

              
              {
    "code": 2004,
    "message": "something error"
}

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

Obtener lista de etiquetas

Devuelve todas las etiquetas de la WABA a la que pertenece la clave de API actual, sin paginación.

Dirección de llamada

GET https://wa.api.engagelab.cc/v1/template-tags

Parámetros de la solicitud

NULL

Ejemplo de solicitud

GET https://wa.api.engagelab.cc/v1/template-tags

              
              GET https://wa.api.engagelab.cc/v1/template-tags

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

Parámetros de la respuesta

Parámetro	Tipo	Opción	Descripción
id	String	Obligatorio	ID de la etiqueta
name	String	Obligatorio	Nombre de la etiqueta
template_count	Integer	Obligatorio	Número de plantillas de la WABA actual que tienen esta etiqueta. Las plantillas con el mismo nombre en distintos idiomas se cuentan por separado según su ID.

Ejemplo de respuesta

[ { "id": "101", "name": "Notificación de envío", "template_count": 3 }, { "id": "102", "name": "Atención posventa", "template_count": 0 } ]

              
              [
    {
        "id": "101",
        "name": "Notificación de envío",
        "template_count": 3
    },
    {
        "id": "102",
        "name": "Atención posventa",
        "template_count": 0
    }
]

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

Si la WABA no tiene etiquetas, se devuelve un array vacío [].

Crear etiqueta

Dirección de llamada

POST https://wa.api.engagelab.cc/v1/template-tags

Parámetros de la solicitud

Parámetro	Tipo	Opción	Descripción
name	String	Obligatorio	Nombre de la etiqueta, de 1 a 64 caracteres. Consulta los requisitos en Reglas de nomenclatura de etiquetas.

Ejemplo de solicitud

{ "name": "Notificación de envío" }

              
              {
    "name": "Notificación de envío"
}

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

Parámetros de la respuesta

Respuesta correcta

Parámetro	Tipo	Opción	Descripción
id	String	Obligatorio	ID de la etiqueta
name	String	Obligatorio	Nombre de la etiqueta ya normalizado

{ "id": "101", "name": "Notificación de envío" }

              
              {
    "id": "101",
    "name": "Notificación de envío"
}

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

Respuesta de error

Parámetro	Tipo	Opción	Descripción
code	int	Obligatorio	Código de error, se devuelve en caso de fallo
message	String	Obligatorio	Mensaje de error, se devuelve en caso de fallo

{ "code": 3003, "message": "template tag name already exists" }

              
              {
    "code": 3003,
    "message": "template tag name already exists"
}

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

Modificar etiqueta

Dirección de llamada

PUT https://wa.api.engagelab.cc/v1/template-tags/{tag_id}

Donde {tag_id} es el ID de la etiqueta que quieres modificar.

Parámetros de la solicitud

Parámetro	Tipo	Opción	Descripción
name	String	Obligatorio	El nuevo nombre de la etiqueta, de 1 a 64 caracteres. Consulta los requisitos en Reglas de nomenclatura de etiquetas.

Ejemplo de solicitud

{ "name": "Atención posventa" }

              
              {
    "name": "Atención posventa"
}

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

Parámetros de la respuesta

Respuesta correcta

Parámetro	Tipo	Opción	Descripción
id	String	Obligatorio	ID de la etiqueta
name	String	Obligatorio	El nombre de la etiqueta ya modificado

{ "id": "101", "name": "Atención posventa" }

              
              {
    "id": "101",
    "name": "Atención posventa"
}

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

Respuesta de error

Parámetro	Tipo	Opción	Descripción
code	int	Obligatorio	Código de error, se devuelve en caso de fallo
message	String	Obligatorio	Mensaje de error, se devuelve en caso de fallo

{ "code": 4001, "message": "template tag not found" }

              
              {
    "code": 4001,
    "message": "template tag not found"
}

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

Eliminar etiqueta

Dirección de llamada

DELETE https://wa.api.engagelab.cc/v1/template-tags/{tag_id}
Nota: eliminar una etiqueta solo deshace la asociación entre las plantillas y esa etiqueta. No elimina las plantillas ni afecta al envío.

Donde {tag_id} es el ID de la etiqueta que quieres eliminar.

Parámetros de la solicitud

NULL

Ejemplo de solicitud

DELETE https://wa.api.engagelab.cc/v1/template-tags/101

              
              DELETE https://wa.api.engagelab.cc/v1/template-tags/101

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

Parámetros de la respuesta

Respuesta correcta

Parámetro	Tipo	Opción	Descripción
affected_template_count	Integer	Obligatorio	Número de plantillas desasociadas en esta operación. Las plantillas con el mismo nombre en distintos idiomas se cuentan por separado según su ID.

{ "affected_template_count": 3 }

              
              {
    "affected_template_count": 3
}

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

Respuesta de error

Parámetro	Tipo	Opción	Descripción
code	int	Obligatorio	Código de error, se devuelve en caso de fallo
message	String	Obligatorio	Mensaje de error, se devuelve en caso de fallo

{ "code": 4001, "message": "template tag not found" }

              
              {
    "code": 4001,
    "message": "template tag not found"
}

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

Asignar etiquetas a una plantilla

Dirección de llamada

PUT https://wa.api.engagelab.cc/v1/templates/{template_id}/tags
Nota: este endpoint sobrescribe por completo. tag_ids es el conjunto completo de etiquetas que tendrá la plantilla tras guardarse; cualquier etiqueta existente que no se incluya quedará desasociada.

Donde {template_id} es el ID de la plantilla a la que quieres asignar etiquetas.

Parámetros de la solicitud

Parámetro	Tipo	Opción	Descripción
tag_ids	String Array	Obligatorio	Conjunto completo de IDs de etiqueta que tendrá la plantilla tras guardarse. Debe enviarse de forma explícita y no puede ser `null`. Todos los IDs deben pertenecer a la WABA actual; los IDs duplicados se eliminan automáticamente.

Sobre el valor de tag_ids:

Enviar [] borra todas las etiquetas de la plantilla.
Si no se envía tag_ids o se envía null, la solicitud falla y no se borran las etiquetas existentes.
Si la solicitud falla, el conjunto de etiquetas de la plantilla no cambia, por lo que puedes reintentarlo directamente.
No hay límite en el número de etiquetas por plantilla; puedes enviar todas las etiquetas de la WABA actual.

Ejemplo de solicitud

{ "tag_ids": ["101", "102"] }

              
              {
    "tag_ids": ["101", "102"]
}

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

Parámetros de la respuesta

Respuesta correcta

Parámetro	Tipo	Opción	Descripción
code	int	Obligatorio	Código de respuesta, siempre 0
message	String	Obligatorio	Mensaje de respuesta, siempre success

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

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

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

Respuesta de error

Parámetro	Tipo	Opción	Descripción
code	int	Obligatorio	Código de error, se devuelve en caso de fallo
message	String	Obligatorio	Mensaje de error, se devuelve en caso de fallo

La plantilla no existe o no pertenece a la WABA actual:

{ "code": 4001, "message": "template not found" }

              
              {
    "code": 4001,
    "message": "template not found"
}

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

La etiqueta no existe o no pertenece a la WABA actual:

{ "code": 4001, "message": "template tag not found" }

              
              {
    "code": 4001,
    "message": "template tag not found"
}

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

No se ha enviado tag_ids o su valor es null:

{ "code": 3002, "message": "template tag IDs must be provided as an array" }

              
              {
    "code": 3002,
    "message": "template tag IDs must be provided as an array"
}

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

Códigos de error

En la tabla siguiente, «endpoints de etiquetas» hace referencia a los cinco endpoints de etiquetas enumerados en la Visión general, e incluye además el caso de filtrar por tag_id al obtener plantillas.

Código de error	Código HTTP	Endpoints afectados	Descripción
1000	500	Todos los endpoints	Error interno
2001	401	Todos los endpoints	Fallo de autenticación en EngageLab: no se ha enviado un token con un formato de datos válido
2002	401	Todos los endpoints	Fallo de autenticación en EngageLab: el token ha caducado o se ha deshabilitado
2003	400	Todos los endpoints	Fallo de autenticación en WhatsApp. Ponte en contacto con el servicio de atención al cliente de EngageLab.
2004	403	Todos los endpoints	Sin permiso para llamar a esta API, o la cuenta o la WABA correspondiente está deshabilitada
3001	400	Todos los endpoints	Formato de los parámetros de la solicitud no válido. Comprueba que se use formato JSON y que los tipos de los campos cumplan los requisitos.
3002	400	Todos los endpoints	Parámetros de la solicitud incorrectos. Comprueba que cumplan los requisitos.
3002	400	Endpoints de etiquetas	El nombre de la etiqueta está vacío
3002	400	Endpoints de etiquetas	El nombre de la etiqueta supera los 64 caracteres, consulta Reglas de nomenclatura de etiquetas
3002	400	Endpoints de etiquetas	El nombre de la etiqueta contiene caracteres no permitidos, consulta Reglas de nomenclatura de etiquetas
3002	400	Endpoints de etiquetas	Formato de ID de etiqueta no válido; debe ser una cadena de enteros positivos
3002	400	Endpoints de etiquetas	No se ha enviado tag_ids al asignar etiquetas a la plantilla, o su valor es null
3003	400	Todos los endpoints	Parámetros de la solicitud incorrectos: ha fallado la validación de negocio correspondiente
3003	400	Endpoints de etiquetas	Ya existe una etiqueta con el mismo nombre en la WABA. La comprobación de duplicados no distingue mayúsculas, minúsculas ni acentos.
3003	400	Endpoints de etiquetas	La WABA ha alcanzado el límite de 20 etiquetas
3003	400	Endpoints de etiquetas	Las operaciones con etiquetas están saturadas. Reinténtalo más tarde; reintentarlo no genera datos duplicados.
4001	400	Todos los endpoints	La plantilla no existe o no pertenece a la WABA actual
4001	400	Endpoints de etiquetas	La etiqueta no existe o no pertenece a la WABA actual
5002	400	Todos los endpoints	La solicitud de la plantilla ha fallado en Meta. Consulta la descripción del error en el campo message.

Notas

Requisitos de formato de los mensajes multimedia

Tipo de contenido multimedia	Content-Type admitido	Límite de tamaño
image	image/jpeg, image/png; no se admiten fondos transparentes	5 MB
video	video/mp4	16MB
document	Solo formato PDF	100 MB

Reglas de nomenclatura de etiquetas

Al crear y modificar etiquetas, el servidor normaliza primero el nombre y después valida su longitud y comprueba si está duplicado.

Normalización: se eliminan los espacios iniciales y finales, y los espacios consecutivos dentro del nombre se unifican en un solo espacio. Por ejemplo, si envías " Notificación de envío ", el nombre que realmente se guarda y se devuelve es "Notificación de envío".

Restricciones de caracteres: se permiten espacios, guiones bajos, guiones, caracteres visibles de cualquier idioma y emojis; no se permiten saltos de línea, tabulaciones, caracteres de control ni caracteres de formato invisibles.

Longitud: tras la normalización, el nombre debe tener entre 1 y 64 caracteres. La longitud se cuenta en puntos de código Unicode, y un emoji puede ocupar varios puntos de código.

Comprobación de duplicados: los nombres no pueden repetirse dentro de una misma WABA. La comprobación no distingue mayúsculas, minúsculas ni acentos: por ejemplo, Logistics, logistics y Logístics se consideran el mismo nombre. No hay palabras reservadas.

Límites de uso de las etiquetas

Cada WABA puede crear un máximo de 20 etiquetas.
No hay límite en el número de etiquetas por plantilla; puedes asignar todas las etiquetas existentes de la WABA actual, por lo que el límite efectivo es de 20.
Los IDs de etiqueta son cadenas tanto en las solicitudes como en las respuestas (por ejemplo, "101"). No los interpretes como valores numéricos.
Las plantillas con el mismo nombre en distintos idiomas reciben sus etiquetas de forma independiente según su ID. Por ejemplo, las versiones en español e inglés de la misma plantilla deben configurarse por separado.
Las etiquetas no se envían a Meta. No modifican el estado ni la puntuación de calidad de la plantilla y no provocan una nueva revisión.

Códigos de idioma

Idioma	Code
Afrikáans	af
Albanés	sq
Árabe	ar
Azerbaiyano	az
Bengalí	bn
Búlgaro	bg
Catalán	ca
Chino (China continental)	zh_CN
Chino (Hong Kong)	zh_HK
Chino (Taiwán)	zh_TW
Croata	hr
Checo	cs
Danés	da
Neerlandés	nl
Inglés	en
Inglés (Reino Unido)	en_GB
Inglés (EE. UU.)	en_US
Estonio	et
Filipino	fil
Finés	fi
Francés	fr
Georgiano	ka
Alemán	de
Griego	el
Guyaratí	gu
Hausa	ha
Hebreo	he
Hindi	hi
Húngaro	hu
Indonesio	id
Irlandés	ga
Italiano	it
Japonés	ja
Canarés	kn
Kazajo	kk
Kinyarwanda	rw_RW
Coreano	ko
Kirguís	ky_KG
Lao	lo
Letón	lv
Lituano	lt
Macedonio	mk
Malayo	ms
Malayalam	ml
Maratí	mr
Noruego	nb
Persa	fa
Polaco	pl
Portugués (Brasil)	pt_BR
Portugués (Portugal)	pt_PT
Panyabí	pa
Rumano	ro
Ruso	ru
Serbio	sr
Eslovaco	sk
Esloveno	sl
Español	es
Español (Argentina)	es_AR
Español (España)	es_ES
Español (México)	es_MX
Suajili	sw
Sueco	sv
Tamil	ta
Telugu	te
Tailandés	th
Turco	tr
Ucraniano	uk
Urdu	ur
Uzbeko	uz
Vietnamita	vi
Zulú	zu

También puedes descargar este archivo para consultar la correspondencia entre idiomas y códigos:
Códigos de idioma de plantillas.xlsx

Visión general

Validación de la llamada

Obtener plantillas

Dirección de llamada

Parámetros de la solicitud

Ejemplo de solicitud

Parámetros de la respuesta

Ejemplo de respuesta

Consultar información de una plantilla

Dirección de llamada

Parámetros de la solicitud

Ejemplo de solicitud

Parámetros de la respuesta

Ejemplo de respuesta

Subir archivo multimedia de ejemplo

Dirección de llamada

Parámetros de la solicitud

Ejemplo de solicitud

Parámetros de la respuesta

Respuesta correcta

Respuesta de error

Crear plantilla

Dirección de llamada

Ejemplo de llamada

Parámetros de la solicitud

Objeto components

Componente header

Descripción del objeto example

Componente body

Descripción del objeto example

Componente footer

Componente buttons

Descripción del objeto buttons

Consideraciones especiales sobre las plantillas de autenticación

Aspectos a tener en cuenta

Ejemplo de COPY_CODE

Ejemplo de ONE_TAP

Parámetros de la respuesta

Respuesta correcta

Respuesta de error

Actualizar plantilla

Dirección de llamada

Ejemplo de llamada

Parámetros de la solicitud

Parámetros de la respuesta

Respuesta correcta

Respuesta de error

Eliminar plantilla

Dirección de llamada

Parámetros de la respuesta

Respuesta correcta

Respuesta de error

Obtener lista de etiquetas

Dirección de llamada

Parámetros de la solicitud

Ejemplo de solicitud

Parámetros de la respuesta

Ejemplo de respuesta

Crear etiqueta

Dirección de llamada

Parámetros de la solicitud

Ejemplo de solicitud

Parámetros de la respuesta

Respuesta correcta

Respuesta de error

Modificar etiqueta

Dirección de llamada

Parámetros de la solicitud

Ejemplo de solicitud

Parámetros de la respuesta

Respuesta correcta

Respuesta de error

Eliminar etiqueta

Dirección de llamada

Parámetros de la solicitud

Ejemplo de solicitud

Parámetros de la respuesta

Respuesta correcta

Respuesta de error