API Crear y enviar plantilla

Crear plantilla

La creación de plantillas se describe en la documentación de la API en el método /addTemplate.

También puede crear una plantilla desde la sección "Dev Toolkit" → "Test Requests" en su cuenta personal.

Parte general de la solicitud:

Campo	Descripción
name	Nombre de la plantilla. Solo puede contener letras minúsculas, dígitos y guiones bajos.
allow_category_change	Casilla "Permitir cambio de categoría". En lugar de rechazar la plantilla, cambiaremos automáticamente su tipo de categoría.
category	Tipo de plantilla: MARKETING, UTILITY o AUTHENTICATION
language	Idioma de la plantilla. El idioma seleccionado debe coincidir con el texto de la plantilla. De lo contrario, Meta puede rechazar la plantilla.
components	Matriz de componentes de la plantilla

Ejemplo:

{
  "token": "{{token}}",
  "name": "test_marketing_2024",
  "allow_category_change": false,
  "category": "MARKETING",
  "language": "ru",
  "components": [
    // objetos del cuerpo de la plantilla
  ]
}

A continuación se describe la estructura de cada categoría de plantilla.

---

Plantillas de Marketing y Servicios

HEADER

Los encabezados son componentes opcionales que aparecen en la parte superior del mensaje de plantilla.

Admiten TEXT o medios (IMAGE, VIDEO o DOCUMENT). Las plantillas están limitadas a un solo componente de encabezado.

Tipo	Descripción
TEXT	Establezca "format": "TEXT" para definir el encabezado como texto. Reglas: máx. 60 caracteres; solo una variable; si hay variable, indique un ejemplo en header_text.
IMAGE	Establezca "format": "IMAGE" para una imagen. Incluya el objeto "example" con el enlace en "header_handle".
VIDEO	Establezca "format": "VIDEO" para un vídeo. Incluya el objeto "example" con el enlace en "header_handle".
DOCUMENT	Establezca "format": "DOCUMENT" para un documento. Incluya el objeto "example" con el enlace en "header_handle".

Ejemplo — encabezado de texto sin variable:

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Hello"
}

Ejemplo — encabezado de texto con variable:

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Our {{1}} is on!",
  "example": {
    "header_text": ["Summer Sale"]
  }
}

Ejemplo — encabezado IMAGE:

{
  "type": "HEADER",
  "format": "IMAGE",
  "example": {
    "header_handle": ["https://img-example-link.com/delicious-orange-23.jpg"]
  }
}

Ejemplo — encabezado VIDEO:

{
  "type": "HEADER",
  "format": "VIDEO",
  "example": {
    "header_handle": ["https://video-example-link.com/banner.mp4"]
  }
}

Ejemplo — encabezado DOCUMENT:

{
  "type": "HEADER",
  "format": "DOCUMENT",
  "example": {
    "header_handle": ["https://doc-example-link.com/reyshi.pdf"]
  }
}

---

BODY

El cuerpo es solo texto y es obligatorio en todas las plantillas. La plantilla puede tener un solo componente BODY.

Reglas del BODY:

• Obligatorio.

• text: máx. 1024 caracteres.

• Si hay variables en text, indique ejemplos en "example" → "body_text". El número de elementos debe coincidir con el de variables.

• Meta no limita el número de variables.

• El texto no puede ser solo una variable; Meta no acepta "text": "{{1}}".

Ejemplo:

{
  "type": "BODY",
  "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
  "example": {
    "body_text": [
      ["the end of August", "25OFF", "25%"]
    ]
  }
}

(Omita example si no hay variables en text.)

---

FOOTER

El pie es un texto opcional que aparece justo después del cuerpo. Máx. un componente FOOTER.

Ejemplo:

{
  "type": "FOOTER",
  "text": "text for footer"
}

---

BUTTONS

Los botones son componentes opcionales que realizan acciones al pulsar. Las plantillas pueden tener hasta 10 botones en total, con límites por tipo y por combinación.

Tipos de botones:

• Quick Reply — Botón de texto que envía al instante ese texto en el chat. Cualquier texto.

• URL — Abre la URL indicada en el navegador.

• Phone Number — Realiza una llamada al número indicado.

• Catalog (solo Marketing) — Al pulsar "View catalog" se abre el catálogo de productos en WhatsApp.

Los botones URL y Phone no envían respuesta en el chat como Quick Reply.

Límites:

• Quick Reply: hasta 10

• URL: hasta 2

• Phone Number: 1

• En la plantilla Catalog solo se puede usar el botón Catalog.

• Máximo 10 botones en total.

Combinaciones válidas / no válidas:

Válidas	No válidas
Quick Reply, Quick Reply, Quick Reply	Quick Reply, URL, Quick Reply
Quick Reply, Quick Reply, Quick Reply, URL, Phone	URL, Quick Reply, URL
URL, Phone, Quick Reply, Quick Reply

Hay que respetar el orden y la cantidad de cada tipo.

QUICK_REPLY:

{
  "type": "QUICK_REPLY",
  "text": "Yes"
}

Máx. 25 caracteres en text.

URL:

{
  "type": "URL",
  "text": "Shop Now",
  "url": "https://www.luckyshrub.com/shop?promo={{1}}",
  "example": ["summer2023"]
}

url: máx. 2000 caracteres. La API no acepta caracteres cirílicos en las URL. Si hay variable, indique example.

PHONE_NUMBER:

{
  "type": "PHONE_NUMBER",
  "text": "my number",
  "phone_number": "77777777777"
}

phone_number y text son obligatorios. Máx. 25 caracteres en text, 20 en phone_number.

CATALOG:

{
  "type": "CATALOG",
  "text": "View catalog"
}

Solo un botón en la plantilla Catalog. En text debe figurar "View catalog"; se traducirá según el idioma de la plantilla.

---

Ejemplo completo: plantilla de Marketing

Plantilla con: encabezado de texto con variable, cuerpo con variables, pie de texto y dos botones Quick Reply.

{
  "token": "{{token}}",
  "name": "test_marketing_2024",
  "allow_category_change": false,
  "category": "MARKETING",
  "language": "ru",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": { "header_text": ["Summer Sale"] }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": { "body_text": [["the end of August", "25OFF", "25%"]] }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        { "type": "QUICK_REPLY", "text": "Unsubscribe from Promos" },
        { "type": "QUICK_REPLY", "text": "Unsubscribe from All" }
      ]
    }
  ]
}

---

Plantilla de autenticación

Las plantillas de autenticación incluyen opciones como aviso de seguridad y advertencia de caducidad. Además, deben tener un botón de contraseña de un solo uso (copiar código o one-tap).

El valor components debe ser un array de objetos. La plantilla de autenticación debe tener:

• un body

• un footer (opcional)

• un botón OTP

BODY:

• Texto fijo: <VERIFICATION_CODE> is your verification code. No rellene la propiedad "text".

• Aviso de seguridad opcional: "For your security, do not share this code". Para añadirlo: "add_security_recommendation": true; false para omitirlo.

• El idioma mostrado depende del idioma de la plantilla.

{
  "type": "BODY",
  "add_security_recommendation": true
}

FOOTER:

• Opcional.

• Advertencia de caducidad: "This code expires in <NUM_MINUTES> minutes". Use "code_expiration_minutes" (entero de 1 a 90). Si se omite, no se muestra.

{
  "type": "FOOTER",
  "code_expiration_minutes": 5
}

BUTTONS:

• Debe incluir botón de copiar código o one-tap. Tipo: "OTP".

• "otp_type": "COPY_CODE" o "ONE_TAP".

• Solo un botón.

• "text": texto del botón. Incluso con ONE_TAP debe indicarse; si Meta no valida el one-tap, se mostrará el botón de copiar con este texto. Máx. 25 caracteres.

Para ONE_TAP también: autofill_text, package_name, signature_hash (consulte la documentación de Meta).

Ejemplo botón copiar código:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "OTP",
      "otp_type": "COPY_CODE",
      "text": "Copy Code"
    }
  ]
}

Ejemplo botón one-tap:

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "OTP",
      "otp_type": "ONE_TAP",
      "text": "Copy Code",
      "autofill_text": "Autofill",
      "package_name": "com.example.myapplication",
      "signature_hash": "K8a%2FAINcGX7"
    }
  ]
}

Ejemplo completo de plantilla de autenticación:

{
  "name": "auth_2024",
  "allow_category_change": false,
  "category": "AUTHENTICATION",
  "language": "ru",
  "components": [
    { "type": "BODY", "add_security_recommendation": true },
    { "type": "FOOTER", "code_expiration_minutes": 5 },
    {
      "type": "BUTTONS",
      "buttons": [
        { "type": "OTP", "otp_type": "COPY_CODE", "text": "Copy Code" }
      ]
    }
  ]
}

---

Enviar plantilla por API

El envío se describe en el método /sendTemplate.

También puede enviar desde "Dev Toolkit" → "Test Requests".

Necesita namespace, name y language de la plantilla. Obténgalos con el método "Get list of templates" (/templates).

Propiedades relevantes en /sendTemplate:

Propiedad	Descripción
template	Nombre de la plantilla
language	policy: "deterministic"; code: código de /templates
Objeto type "body"	Mensaje de texto. Omita si el cuerpo no tiene variables.
Objeto type "button"	En el cuerpo solo se envían botones con sub_type "url" o "catalog". Los demás se pueden omitir.

---

Enviar plantillas Marketing o Utility

Envíe solo los objetos definidos en la plantilla. Omita:

• header si no existe en la plantilla

• header si es de tipo Text y no tiene variable

• body si no tiene variables

• Botones Quick Reply y Phone — siempre omitir

• Botón URL si no tiene variable

En encabezados IMAGE, VIDEO o DOCUMENT envíe siempre la URL completa. La URL debe incluir el formato del archivo.

Ejemplo: documento con botón URL

• Encabezado tipo document

• Cuerpo con 2 variables

• Dos botones URL; el segundo tiene variable. Si un botón URL no tiene variable, omítalo. El índice del segundo botón es 1.

{
  "namespace": "{{namespace}}",
  "template": "delivery_tracking",
  "language": { "policy": "deterministic", "code": "ru" },
  "params": [
    {
      "type": "header",
      "parameters": [
        {
          "type": "document",
          "document": { "link": "https://test.com/reyshi.pdf" }
        }
      ]
    },
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "Andrey" },
        { "type": "text", "text": "№003478" }
      ]
    },
    {
      "type": "button",
      "sub_type": "url",
      "index": 1,
      "parameters": [{ "type": "text", "text": "/reyshi" }]
    }
  ],
  "phone": "{{phone}}"
}

Ejemplo: encabezado de texto con todos los tipos de botones

• Encabezado Text con una variable

• Cuerpo sin variables → omitido en la solicitud

• 4 botones: Quick Reply, Phone, URL con variable, URL sin variable

{
  "namespace": "{{namespace}}",
  "template": "utility_all_buttons_2024_05",
  "language": { "policy": "deterministic", "code": "en" },
  "params": [
    {
      "type": "header",
      "parameters": [{ "type": "text", "text": "Anna" }]
    },
    {
      "type": "button",
      "sub_type": "url",
      "index": 2,
      "parameters": [{ "type": "text", "text": "inbox" }]
    }
  ],
  "phone": "{{phone}}"
}

---

Enviar plantilla de autenticación

Ejemplo con botón copiar código:

{
  "namespace": "{{namespace}}",
  "template": "auth_2",
  "language": { "policy": "deterministic", "code": "ru" },
  "params": [
    {
      "type": "body",
      "parameters": [{ "type": "text", "text": "05425" }]
    },
    {
      "type": "button",
      "sub_type": "url",
      "index": 0,
      "parameters": [{ "type": "text", "text": "05425" }]
    }
  ],
  "phone": "[phone]"
}