API Cloud (TEMPLATES)

Las plantillas se usan en mensajes de plantilla para abrir conversaciones de marketing, utilidad y autenticación con los clientes. A diferencia de los mensajes de formato libre, las plantillas son el único tipo de mensaje que se puede enviar a clientes que aún no han iniciado una conversación contigo o que no te han enviado ningún mensaje en las últimas 24 horas.

Los endpoints se pueden consultar con varias versiones de Meta. Es importante establecer la VERSION en cada URL (ej: v16.0, v17.0, v18.0, v19.0).

Fundamentos de plantillas

Las plantillas son activos de la cuenta de WhatsApp Business que se envían en mensajes de plantilla mediante Cloud API o Marketing Messages API para WhatsApp. Son el único tipo de mensaje que se puede enviar a usuarios de WhatsApp fuera de una ventana de servicio al cliente. Se usan comúnmente para mensajes masivos o cuando no hay una ventana de servicio abierta.

Creación

Puedes crear plantillas con la Message Templates API o desde el panel de plantillas en WhatsApp Manager. Se pueden crear máximo 100 plantillas por hora en una cuenta de WhatsApp Business.

La creación vía API usa una sintaxis común. La variación principal ocurre en la cadena category, que asigna la categoría, y en el array components, que define los componentes de la plantilla.

Sintaxis común:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "<NOMBRE>",
    "category": "<CATEGORIA>",
    "language": "<LENGUAJE>",
    "parameter_format": "<FORMATO_DE_PARAMETROS>",
    "components": [<COMPONENTES>]
  }'

Nombres

Toda plantilla debe tener un nombre, pero los nombres no son únicos. Esta flexibilidad permite crear múltiples plantillas con el mismo nombre en diferentes idiomas.

Los nombres están limitados a 512 caracteres, compuestos por caracteres alfanuméricos en minúscula y guiones bajos.

Categorías

Cada plantilla debe categorizarse como authentication, marketing o utility. Las categorías también influyen en la tarificación.

Categorización de plantillas

Guías de categoría

Marketing

Las plantillas de marketing son las más flexibles. También se consideran marketing:

• Plantillas con contenido mixto (por ejemplo, actualización de pedido con promo o encuesta con contenido promocional).
• Plantillas con contenido poco claro (por ejemplo, solo {{1}} o ¡Felicitaciones!).

Utility

Las plantillas de utilidad son típicamente disparadas por una acción o solicitud del usuario. Para categorizarse como utility, deben cumplir ambos criterios:

• Deben ser no promocionales, sin intención promocional o persuasiva.
• Deben además ser específicas del usuario o solicitadas por él (relacionadas con su pedido, cuenta, servicios o transacciones) O esenciales o críticas para el usuario (por ejemplo, su seguridad).

Utility esencial o crítica — para considerarse esencial/crítica, debe reflejar uno de estos casos y ser no promocional:

Authentication

Nota: solo las plantillas de autenticación pueden enviar un one-time passcode para verificación de identidad. Marketing y utility no pueden usarse para este fin.

Las plantillas de autenticación permiten verificar la identidad del usuario (normalmente con códigos alfanuméricos) en varios pasos: creación de cuenta nueva, integridad/acceso/recuperación de cuenta, y pedidos/transacciones nuevos o existentes.

Son la categoría más restrictiva. Para clasificarse como authentication, un negocio debe:

• Usar plantillas de autenticación de Cloud API en la Template Library (incluyen add-ons opcionales como disclaimers de seguridad y avisos de expiración).
• Configurar un botón de one-time password: copy-code o one-tap.
• Cumplir restricciones de contenido: no se permiten URLs, media ni emojis; los parámetros se limitan a 15 caracteres.

Cómo asigna WhatsApp la categoría durante la creación

Al crear una plantilla indicas su categoría según las guías. WhatsApp valida la categoría indicada según el contenido y las guías, y establece el estado según el resultado:

• APPROVED: WhatsApp coincide con la categoría elegida y la plantilla pasó la revisión. Puede usarse para enviar. Se notifica por email, alerta en WhatsApp Manager y webhook message_template_status_update con event: APPROVED.
  • Advertencia (desde 9 abr 2025): si elegiste UTILITY y WhatsApp determinó que debería ser MARKETING, la plantilla se aprueba como MARKETING. Puedes solicitar revisión hasta 60 días desde la actualización de categoría.
  • Advertencia (desde 9 abr 2025): allow_category_change ahora es true por defecto en la creación.
• PENDING: WhatsApp coincide con la categoría pero la plantilla está en revisión. Al completarse, un webhook message_template_status_update con event: APPROVED o REJECTED.
• REJECTED: WhatsApp no coincide con la categoría que designaste. Webhook message_template_status_update con event: REJECTED y reason: INCORRECT_CATEGORY. Opciones: crear una nueva, editar la categoría, o solicitar revisión.

Plantillas duplicadas por migración de número: todas las plantillas elegibles se duplican automáticamente en la WABA de destino y se realizan chequeos de categoría para asegurar que estén correctamente categorizadas.

Actualizaciones automáticas de categoría

WhatsApp introdujo un proceso recurrente para identificar y actualizar plantillas aprobadas que deberían tener otra categoría.

Para plantillas aprobadas como utility pero que deberían ser marketing:

• Período de aviso: aviso de 1 día antes de actualizar a marketing. Desde 16 abr 2025, si fuiste advertido por abuso de categorización, el aviso de 24h no se da y el cambio es instantáneo.
• Categoría: cambia a MARKETING.
• Estado: no cambia; permanece APPROVED y puede seguir enviándose.

Para plantillas aprobadas como marketing o utility pero que deberían ser authentication (desde 1 oct 2024):

• Aviso previo proporcionado.
• Categoría: no cambia.
• Estado: el primer día del mes siguiente, el estado cambia a REJECTED y ya no puede usarse para enviar.

Notificaciones:

Tu opciones en este proceso: puedes crear una nueva plantilla; para utility→marketing puedes solicitar revisión (si se aprueba, la categoría no se actualiza; si no, se actualiza); para marketing/utility→authentication no puedes solicitar revisión (busca opciones en la template library). Tienes 60 días para revisar y apelar en Business Support Home.

Saber qué plantillas se actualizarán o se actualizaron:

• Vía API: GET /{waba-id}/message_templates?fields=category,correct_category. Si coinciden → ya actualizada; si no coinciden y correct_category no es vacío → se actualizará el primer día del próximo mes; si correct_category es vacío/nulo → no afectada.
• Vía WhatsApp Manager: el panel Manage Templates identifica las plantillas cuyas categorías se actualizarán.

Cómo actualizar la categoría o solicitar una revisión

Editar la categoría:

• Vía API: puedes editar el contenido o solo la categoría. La plantilla pasa validación y revisión nuevamente; si aprueba, se dispara template_category_update con new_category.
• Vía WhatsApp Manager: en la pestaña Manage Templates, edita el contenido para alinearlo a las guías y vuelve a enviarlo para aprobación.

Calificaciones y resultados de la revisión de categoría: puedes solicitar a Meta revisar la categoría si es UTILITY o MARKETING con estado REJECTED, o MARKETING con estado APPROVED. Resultados: aprobada (categoría actualizada) o rechazada (sin cambio).

Cómo solicitar una revisión de categoría:

1. En WhatsApp Manager, selecciona el menú desplegable Message Templates y luego Message Templates. Deberías ver un banner de rechazo. Haz clic en Go to Business Support.
2. Haz clic en Template Category Updates, selecciona las plantillas a revisar y haz clic en Request Review.

Cómo ver las plantillas enviadas para revisión: en la barra lateral de Business Support, haz clic en Template Category Updates y luego la pestaña In review.

Cómo ver las decisiones de categoría: si el cambio no se aprueba, la plantilla se ve bajo Template category updates > Unchanged; si se aprueba, bajo Reversed (y se revierte si ya se había cambiado).

Restricciones por mal uso del sistema de categorización

Si un negocio clasifica consistentemente plantillas de marketing como utility, WhatsApp puede aplicar restricciones escalonadas:

Advertencia: si se detecta mal uso continuo tras una restricción previa, la aplicación puede reintroducirse por períodos más largos y a mayor nivel.

Notificaciones:

• Email: a todos los admins de la WABA (control total) cuando ocurre un warning, restricción o levantamiento.
• Webhook: un account_update con el objeto restriction_info reflejando el estado actual de la aplicación.

Eventos de webhook (suscripción whatsapp_business_account):

{
  "field": "account_update",
  "value": {
    "event": "ACCOUNT_RESTRICTION",
    "violation_info": {
      "violation_type": "<violation_type>"
    },
    "restriction_info": [
      {
        "restriction_type": "<restriction_type>",
        "expiration": "<unix_timestamp>"
      }
    ]
  }
}

restriction_info solo está presente cuando se aplica una restricción activa; se omite para warnings y eventos de recuperación.

Si crees que plantillas específicas fueron incorrectamente recategorizadas, puedes apelar a nivel de plantilla vía Business Support > Template Category Updates > Request Review.

Componentes

Las plantillas se componen de varios componentes de texto, media y UI interactiva, que defines al crearla. Consulta la guía de componentes de plantillas para conocer todos los posibles.

Idiomas

Debes asignar un código de idioma al crear la plantilla. Meta no traduce los strings ni variables: eres responsable de proveer strings y parámetros de ejemplo en el idioma apropiado.

Si creas múltiples plantillas con el mismo nombre pero en idiomas diferentes, cada una cuenta contra tu límite de plantillas.

Idiomas soportados:

Formatos de parámetros

Algunos componentes permiten definir strings con uno o más parámetros (descritos como “variables” en WhatsApp Manager), que se reemplazan con valores en el payload de envío.

Al crear la plantilla, si un string incluye parámetros, puedes especificar su formato — named o positional — y debes incluir un valor de ejemplo por cada parámetro. Si no especificas formato, se usa positional por defecto.

Parámetros con nombre (named)

Los parámetros con formato named deben ser strings únicos, compuestos por caracteres en minúscula y guiones bajos, envueltos en doble llave, por ejemplo {{first_name}}. Los valores de ejemplo y reales pueden aparecer en cualquier orden.

Ejemplo de creación con parámetros named:

{
  "name": "order_confirmation",
  "language": "en_US",
  "category": "utility",
  "parameter_format": "named",
  "components": [
    {
      "type": "body",
      "text": "Thank you, {{first_name}}! Your order number is {{order_number}}.",
      "example": {
        "body_text_named_params": [
          { "param_name": "first_name", "example": "Pablo" },
          { "param_name": "order_number", "example": "860198-230332" }
        ]
      }
    }
  ]
}

Ejemplo de envío con parámetros named:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "template",
  "template": {
    "name": "order_confirmation",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "parameter_name": "first_name", "text": "Jessica" },
          { "type": "text", "parameter_name": "order_number", "text": "SKBUP2-4CPIG9" }
        ]
      }
    ]
  }
}

Parámetros posicionales

Los parámetros posicionales deben ser números de índice ordenados, comenzando en 1, envueltos en doble llave: {{1}}, {{2}}, etc. Los valores de ejemplo y reales deben aparecer en el orden de sus placeholders en el string del componente.

Ejemplo de creación con parámetro posicional:

{
  "name": "order_confirmation",
  "language": "en_US",
  "category": "utility",
  "parameter_format": "positional",
  "components": [
    {
      "type": "body",
      "text": "Hi {{1}}! Your order number is {{2}}. Thank you.",
      "example": {
        "body_text": [["Pablo", "860198-230332"]]
      }
    }
  ]
}

Ejemplo de envío con parámetro posicional:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "template",
  "template": {
    "name": "order_confirmation",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Jessica" },
          { "type": "text", "text": "SKBUP2-4CPIG9" }
        ]
      }
    ]
  }
}

Media

Los componentes de header de plantilla pueden mostrar media. Si creas una plantilla con header de media, debes usar la Resumable Upload API para obtener un asset handle e incluirlo en la solicitud de creación. El asset de ejemplo se revisa como parte de la revisión de plantillas.

Revisión de plantillas

Las plantillas se revisan automáticamente al crearlas o editarlas. Si la plantilla es aprobada, su estado se establece en APPROVED y puedes comenzar a enviarla. Si es rechazada o su estado cambia a otro valor, no puede enviarse en mensajes de plantilla.

Estado de plantilla

Las plantillas deben tener estado APPROVED antes de poder enviarse. El estado se establece inicialmente por la revisión, pero puede cambiar según el uso y el feedback de calidad.

Los cambios de estado se comunican mediante webhooks message_template_status_update, pero puedes usar la Template API y solicitar el campo status para consultar el estado en cualquier momento.

Estado en WhatsApp Manager (con ratings de calidad para plantillas activas):

• In-Review: aún bajo revisión (hasta 24h).
• Rejected: rechazada durante la revisión o viola una o más políticas.
• Active - Quality pending: sin feedback de calidad aún. Enviable.
• Active - High Quality: poco o ningún feedback negativo. Enviable.
• Active - Medium Quality: feedback negativo de varios clientes o baja tasa de lectura. Enviable, pero podría pausarse.
• Active - Low Quality: feedback negativo o baja lectura. Enviable pero en riesgo de pausa/deshabilitado.
• Paused: pausada por feedback recurrente o baja lectura. No enviable.
• Disabled: deshabilitada por feedback recurrente. No enviable.
• Appeal Requested: se solicitó una apelación.

Límites de plantillas

El número de plantillas que puede tener una cuenta de WhatsApp Business está determinado por su business portfolio padre.

• Si el portfolio padre no está verificado: cada WABA se limita a 250 plantillas.
• Si el portfolio está verificado y al menos una de sus WABA tiene un número con display name aprobado: cada WABA puede tener hasta 6,000 plantillas.

Además, existen límites de envío y procesos que afectan la entrega:

• Messaging limits — límite de plantillas enviables fuera de ventanas de servicio.
• Template pacing — da tiempo a los usuarios para dar feedback.
• Template pausing — puede pausar plantillas con mal feedback.
• Template archival — archiva y elimina plantillas inactivas por 12+ meses (borrado tras 28 días salvo desarchivado).
• Per-user marketing template message limits — limita cuántas plantillas de marketing recibe un usuario de cualquier negocio.

Tiempo de vida (TTL)

Si un mensaje no puede entregarse, el sistema seguirá intentándolo durante un período llamado time-to-live (TTL). Puedes personalizar el TTL al crear la plantilla.

Rating de calidad

El rating de calidad de plantilla evalúa la calidad de las plantillas según uso, feedback del cliente y engagement. Consulta Template quality rating para saber cómo afecta al estado y cómo recibir notificaciones de cambios.

Secuencia de entrega de múltiples mensajes

Al enviar una serie de mensajes, el orden de entrega no está garantizado que coincida con el orden de las solicitudes a la API. Para asegurar la secuencia, confirma la recepción de un estado delivered en un webhook de estado antes de enviar el siguiente mensaje de la secuencia.

Componentes de plantillas

Las plantillas se componen de hasta cuatro componentes que defines al crearla: header, body, footer y botones. El único componente obligatorio es el body. Elige los componentes según tus necesidades de negocio. Algunos componentes soportan variables, cuyos valores provees al enviar la plantilla; si usas variables, debes incluir valores de ejemplo al crearla.

Header de texto

Los headers de texto son opcionales y se agregan al inicio del mensaje. Cada plantilla puede incluir solo un header de texto. No uses caracteres especiales de Markdown en este componente.

El header de texto soporta 1 parámetro.

Sintaxis de creación:

{
  "type": "header",
  "format": "text",
  "text": "<HEADER_TEXT>",
  "example": {
    "header_text_named_params": [
      { "param_name": "<NAMED_PARAMETER_NAME>", "example": "<PARAMETER_EXAMPLE_VALUE>" }
    ]
  }
}

Header de media

Los headers de media pueden ser una imagen, video, gif o documento (como PDF). Debes subir toda la media con la Resumable Upload API. La sintaxis es la misma para todos los tipos.

Nota: los gifs solo están disponibles para Marketing Messages API para WhatsApp. Son archivos mp4 con máximo 3.5MB; WhatsApp muestra los archivos más grandes como mensajes de video.

Sintaxis de creación:

{
  "type": "HEADER",
  "format": "<FORMATO>",
  "example": {
    "header_handle": ["<HEADER_HANDLE>"]
  }
}

Enviar plantilla basada en media

Usa la API de mensajes para enviar una plantilla basada en media. Establece la propiedad type en template y usa la propiedad template para definir el objeto de plantilla y su objeto de media.

Al definir el objeto de media, puedes:

• Subir tu asset de media a los servidores de Meta y usar su media ID (propiedad id).
• Alojar el asset en tu servidor y usar su URL (propiedad link). Si usas link, tu asset debe estar en un servidor públicamente accesible o el mensaje fallará.

Para reducir la probabilidad de errores y evitar solicitudes innecesarias a tu servidor público, Meta recomienda subir los assets de media y usar sus IDs al enviar mensajes.

También puedes cachear los assets de media. Consulta Media HTTP Caching.

Sintaxis de request:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/{VERSION}/{did}/messages' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "PHONE_NUMBER",
    "type": "template",
    "template": {
      "name": "TEMPLATE_NAME",
      "language": { "code": "LANGUAGE_AND_LOCALE_CODE" },
      "components": [
        {
          "type": "header",
          "parameters": [
            { "type": "image", "image": { "link": "https://URL" } }
          ]
        },
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "TEXT-STRING" },
            {
              "type": "currency",
              "currency": { "fallback_value": "VALUE", "code": "USD", "amount_1000": NUMBER }
            },
            {
              "type": "date_time",
              "date_time": { "fallback_value": "MONTH DAY, YEAR" }
            }
          ]
        }
      ]
    }
  }'

Una respuesta exitosa incluye un objeto con un identificador prefijado con wamid. Usa el ID después de wamid para hacer seguimiento del estado del mensaje.

{
  "messaging_product": "whatsapp",
  "contacts": [{
    "input": "PHONE_NUMBER",
    "wa_id": "WHATSAPP_ID"
  }],
  "messages": [{
    "id": "wamid.ID"
  }]
}

Header de ubicación

Los headers de ubicación aparecen como mapas genéricos al inicio de la plantilla. Se usan para tracking de órdenes, actualizaciones de entrega, pickup/dropoff y localizar tiendas. Al tocarlos, se abre la app de mapas del usuario con la ubicación especificada. La ubicación se especifica al enviar la plantilla.

Los headers de ubicación solo pueden usarse en plantillas categorizadas como UTILITY o MARKETING. No se soportan ubicaciones en tiempo real.

Sintaxis de creación:

{
  "type": "header",
  "format": "location"
}

Sintaxis de envío:

{
  "type": "header",
  "parameters": [
    {
      "type": "location",
      "location": {
        "latitude": "<LATITUD>",
        "longitude": "<LONGITUD>",
        "name": "<NOMBRE>",
        "address": "<DIRECCION>"
      }
    }
  ]
}

Body

El body es el texto central de la plantilla y es un componente solo de texto. Las plantillas se limitan a un componente body. El texto del body acepta múltiples parámetros.

Sintaxis de creación (parámetros named):

{
  "type": "body",
  "text": "<BODY_TEXT>",
  "example": {
    "body_text_named_params": [
      { "param_name": "<NAMED_PARAMETER_NAME>", "example": "<PARAMETER_EXAMPLE_VALUE>" }
    ]
  }
}

Sintaxis de creación (parámetros posicionales):

{
  "type": "body",
  "text": "<BODY_TEXT>",
  "example": {
    "body_text": ["<PARAMETER_EXAMPLE_VALUE>"]
  }
}

Footer

Los footers son componentes opcionales solo de texto que aparecen inmediatamente después del body. Las plantillas se limitan a un componente footer.

Sintaxis:

{
  "type": "FOOTER",
  "text": "<TEXTO>"
}

Botones

Los botones son componentes interactivos opcionales que realizan acciones específicas al ser tocados.

Las plantillas pueden tener una combinación de hasta 10 botones en total, aunque hay límites por tipo y límites de combinación. Las plantillas con 4 o más botones, o con un botón quick reply y uno o más de otro tipo, no pueden verse en clientes de escritorio de WhatsApp; se pedirá al usuario ver el mensaje en el teléfono.

Los botones se definen en un único componente de botones, empaquetados en un array buttons. Si una plantilla tiene más de tres botones, dos aparecen en el mensaje y WhatsApp reemplaza el resto con un botón See all options.

Botones de copiar código

Los botones de copiar código copian un string de texto (definido al enviar la plantilla) al portapapeles del dispositivo. Las plantillas se limitan a un botón de copiar código.

{
  "type": "COPY_CODE",
  "example": "<EJEMPLO>"
}

Botones multi-producto (MPM)

Botones especiales no personalizables que, al tocarlos, muestran hasta 30 productos de tu catálogo de ecommerce, organizados en hasta 10 secciones, en un solo mensaje.

Botones de contraseña de un solo uso (OTP)

Tipo especial de botón URL usado con plantillas de autenticación.

Botones de llamada de voz

Realizan una llamada de WhatsApp al negocio al ser tocados. Consulta Crear y enviar plantilla con botón de llamada.

Botones de número de teléfono

Llaman al número de teléfono del negocio especificado al ser tocados. Las plantillas se limitan a un botón de número de teléfono.

{
  "type": "PHONE_NUMBER",
  "text": "<TEXTO>",
  "phone_number": "<NUMERO>"
}

Botones de respuesta rápida

Botones de texto personalizados que envían el string especificado al ser tocados. Un caso común es un botón para opt-out de mensajes de marketing.

Las plantillas se limitan a 10 botones de respuesta rápida. Si se usan con otros botones, deben organizarse en dos grupos: respuesta rápida y no-respuesta rápida. Si se agrupan incorrectamente, la API devuelve un error de combinación inválida.

• Agrupaciones válidas: Quick Reply, Quick Reply, Quick Reply, Quick Reply, URL, Phone, URL, Phone, Quick Reply, Quick Reply.
• Agrupaciones inválidas: Quick Reply, URL, Quick Reply, URL, Quick Reply, URL.

Al enviar una plantilla con múltiples botones de respuesta rápida, puedes usar la propiedad index para designar el orden en que aparecen.

{
  "type": "QUICK_REPLY",
  "text": "<TEXTO>"
}

Botones SPM (producto único)

Botones especiales no personalizables mapeados a un producto de tu catálogo. Al tocarlos, cargan los detalles del producto desde el catálogo. Los usuarios pueden agregarlo al carrito y realizar un pedido.

Botones URL

Cargan la URL especificada en el navegador del dispositivo al ser tocados. Las plantillas se limitan a dos botones URL.

{
  "type": "URL",
  "text": "<TEXTO>",
  "url": "<URL>",
  "example": ["<EJEMPLO>"]
}

Codificación de URL

Si los valores de los parámetros de tu botón URL contienen caracteres especiales, debes percent-encodearlos antes de incluirlos en la solicitud de envío. Los caracteres sin codificar pueden hacer que la URL generada falle la validación.

Por ejemplo, si tu URL de plantilla es https://example.com/order?name={{customer_name}} y el valor del parámetro es Gonçalves, debes enviar el valor como Gon%C3%A7alves:

{
  "type": "button",
  "sub_type": "url",
  "index": "0",
  "parameters": [
    { "type": "text", "parameter_name": "customer_name", "text": "Gon%C3%A7alves" }
  ]
}

Oferta por tiempo limitado

Los componentes Limited-Time Offer son componentes especiales usados para crear plantillas de oferta por tiempo limitado.

Webhooks

Suscríbete al campo de webhook message_template_components_update para recibir notificaciones de cambios en los componentes de una plantilla.

Template Library

Template Library facilita la creación de plantillas de utilidad para casos de uso comunes (recordatorios de pago, actualizaciones de entrega) y plantillas de autenticación para verificación de identidad.

Estas plantillas pre-escritas ya están categorizadas como utility o authentication. Contienen contenido fijo que no puede editarse y parámetros que puedes adaptar para información del negocio o del usuario.

Advertencia: cuando una plantilla contiene el valor library_template_name en la respuesta de GET /{waba-id}/message_templates?name=<NOMBRE>, es una plantilla creada desde Template Library y está sujeta a chequeos de tipo y restricciones.

Parámetros y restricciones

Los parámetros representan espacios donde se inserta información variable (nombres, direcciones, teléfonos). Los mensajes enviados con plantillas de la library están sujetos a chequeos de parámetros al momento del envío. Valores fuera de los rangos establecidos harán fallar el envío.

Advertencia: todos los parámetros tienen restricción de longitud. Si recibes un error, prueba con un valor más corto.

Formularios

Advertencia: los formularios solo están disponibles para cuentas que han aumentado sus límites de mensajería.

Algunas plantillas de Template Library son formularios interactivos impulsados por WhatsApp Flows. En WhatsApp Manager se identifican por la etiqueta “Form”. Los casos de uso soportados actualmente son Customer Feedback y Delivery Failure.

Al llamar a GET /message_template_library, la clave type del array buttons mostrará "FORMS" para identificarlos.

{
  "name": "delivery_failed_2_form",
  "language": "en_US",
  "category": "UTILITY",
  "topic": "ORDER_MANAGEMENT",
  "usecase": "DELIVERY_FAILED",
  "industry": ["E_COMMERCE"],
  "body": "We were unable to deliver order {{1}} today.\n\nPlease {{2}} to schedule another delivery attempt.",
  "body_params": ["#12345", "try a redelivery"],
  "body_param_types": ["TEXT", "TEXT"],
  "buttons": [{ "type": "FLOW", "text": "Reschedule" }],
  "id": "7138055039625658"
}

Uso de la API

La Template Library API tiene dos endpoints:

GET /message_template_library                       // Explorar plantillas disponibles
POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates   // Crear plantilla desde la library

Buscar y filtrar plantillas

Advertencia: las plantillas con parámetros de header Document solo soportan PDFs.

Sintaxis de request:

GET /message_template_library
GET /message_template_library?search=<SEARCH_KEY>       // substring en contenido, nombre, header, body o footer
GET /message_template_library?topic=<TOPIC>
GET /message_template_library?usecase=<USECASE>
GET /message_template_library?industry=<INDUSTRY>
GET /message_template_library?language=<LANGUAGE>
GET /message_template_library?name=<NAME>

Parámetros de query:

Filtros de plantillas:

• Industria: E_COMMERCE, FINANCIAL_SERVICES.
• Tema: ACCOUNT_UPDATE, CUSTOMER_FEEDBACK, ORDER_MANAGEMENT, PAYMENTS.
• Caso de uso: ACCOUNT_CREATION_CONFIRMATION, AUTO_PAY_REMINDER, DELIVERY_CONFIRMATION, DELIVERY_FAILED, DELIVERY_UPDATE, FEEDBACK_SURVEY, FRAUD_ALERT, LOW_BALANCE_WARNING, ORDER_ACTION_NEEDED, ORDER_CONFIRMATION, ORDER_DELAY, ORDER_OR_TRANSACTION_CANCEL, ORDER_PICK_UP, PAYMENT_ACTION_REQUIRED, PAYMENT_CONFIRMATION, PAYMENT_DUE_REMINDER, PAYMENT_OVERDUE, PAYMENT_REJECT_FAIL, PAYMENT_SCHEDULED, RECEIPT_ATTACHMENT, RETURN_CONFIRMATION, SHIPMENT_CONFIRMATION, STATEMENT_ATTACHMENT, STATEMENT_AVAILABLE, TRANSACTION_ALERT.

Crear plantillas desde la library

Para crear una plantilla desde Template Library, llama al endpoint existente <WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates con las propiedades del body:

{
  "name": "<NAME>",
  "category": "UTILITY",
  "language": "en_US",
  "library_template_name": "<LIBRARY_TEMPLATE_NAME>",
  "library_template_button_inputs": "[
    {'type': 'URL', 'url': {'base_url' : 'https://www.example.com/{{1}}',
    'url_suffix_example' : 'https://www.example.com/demo'}},
    {type: 'PHONE_NUMBER', 'phone_number': '+16315551010'}
]"
}

Propiedades del body:

Library template button inputs:

Library template body inputs:

Ejemplo de request:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "my_delivery_update",
    "language": "en_US",
    "category": "UTILITY",
    "library_template_name": "delivery_update_1",
    "library_template_button_inputs": "[{'type': 'URL', 'url': {'base_url': 'https://www.example.com/{{1}}', 'url_suffix_example': 'https://www.example.com/order_update'}}]"
  }'

Ejemplo de respuesta:

{
  "id": "{hsm-id}",
  "status": "APPROVED",
  "category": "UTILITY"
}

Archivo de plantillas

Las plantillas que han estado inactivas durante 12 meses o más se archivan automáticamente. Las plantillas archivadas no pueden enviarse en mensajes de plantilla y están programadas para eliminarse después de 28 días. Puedes desarchivar una plantilla dentro de la ventana de 28 días para restaurarla a su estado anterior.

Auto-archivado

Todas las cuentas de WhatsApp Business tienen el auto-archivado habilitado. No puedes optar por no participar.

Una plantilla es elegible para auto-archivado cuando se cumplen todas las siguientes condiciones:

• El estado de la plantilla no es PENDING_DELETION, DELETED o ARCHIVED.
• La plantilla ha estado inactiva durante más de 12 meses.

La actividad de la plantilla incluye crearla, editarla, enviarla, apelarla o desarchivarla.

Eliminación post-archivado

WhatsApp elimina automáticamente las plantillas archivadas 28 días después del archivado. Una vez eliminada, la plantilla no puede recuperarse. Si desarchivas una plantilla antes de que expire la ventana de 28 días, la eliminación programada se cancela.

Notificaciones

Cuando se archivan plantillas, se te notifica a través de los siguientes canales:

• Webhook — Se envía un webhook message_template_status_update por cada plantilla archivada o desarchivada.
• Email — Se envía un email cuando se archivan plantillas, listando las afectadas con un link para verlas y desarchivarlas en WhatsApp Manager.

Marketing Messages API (MM API)

La MM API para WhatsApp es una API para enviar mensajes de marketing en WhatsApp que optimiza la entrega para llegar a más personas con mayor probabilidad de encontrar tus mensajes relevantes.

Requisitos

• Tener una cuenta de WhatsApp Business activa y estar en un país elegible para MM API.
• Tener una plantilla de marketing aprobada.
• Estar suscrito al webhook messages.

Aceptar los términos de servicio

1. Navega al App Dashboard > WhatsApp > panel Quickstart.
2. Ubica el módulo “Improve ROI with marketing messages with optimizations” y haz clic en “Get started”.
3. Haz clic en “Continue to integration guide” y acepta los Términos de Servicio.

Enviar mensajes de marketing

La MM API para WhatsApp solo permite enviar mensajes de plantillas de marketing. Para enviar otros tipos de mensajes o recibir mensajes, usa Cloud API en paralelo con MM API en el mismo número de negocio.

Prerequisitos:

• WABA con onboarding de MM API completo.
• Al menos un número de negocio registrado asociado al WABA.
• Al menos una plantilla de marketing aprobada.
• Un access token con el permiso whatsapp_business_messaging.
• Una integración de Meta Pixel o Conversions API (requerida para medición de conversión).

Sync de plantillas: las plantillas de marketing nuevas tardan hasta 10 minutos en sincronizarse con la cuenta de Ads correspondiente (habilita optimización y medición de clics/conversiones). Las plantillas inactivas por más de 7 días también requieren 10 minutos tras su primer uso. Espera 10 minutos tras crear plantillas nuevas o reactivar plantillas dormidas antes de enviar tráfico de marketing.

Endpoint: envía todo el tráfico de marketing a POST /{v}/{did}/marketing_messages. El endpoint soporta solo mensajes de plantillas de marketing para MM API y Cloud API; los demás tipos (freeform, authentication, service, utility) producen error. Si los requisitos de onboarding no se cumplen, el mensaje se enruta vía Cloud API (puedes deshabilitarlo con product_policy: STRICT).

Campos opcionales del payload:

• product_policy: CLOUD_API_FALLBACK (default — envía vía Cloud API si onboarding no está completo) o STRICT (nunca hace fallback).
• message_activity_sharing: habilita/deshabilita compartir actividades de mensaje (por ejemplo, lecturas) para ese mensaje con Meta. Si no se provee, se aplica la configuración default a nivel WABA.

Envío por BSUID (business-scoped user ID): el campo recipient (BSUID o parent BSUID) es opcional junto a to (ahora opcional). Se requiere al menos uno; si se proveen ambos, to tiene precedencia. Enviar por BSUID deshabilita la optimización de entrega de MM API, y el pricing dinámico (bid_spec) no se soporta → error 131062 (“Business-scoped User ID (BSUID) recipients are not supported”). Las plantillas de autenticación también fallan con 131062 con BSUID. La respuesta agrega user_id (BSUID) y omite wa_id cuando se envía por BSUID.

Deshabilitar marketing messages en Cloud API: configura disable_marketing_messages_on_cloud_api: true|false vía POST /{waba-id} (WhatsApp Business Account API). Cuando es true, el endpoint /messages rechaza las plantillas de marketing con error 131063 (“Marketing templates disabled for Cloud API”). Sin efecto en WABAs que no se hayan onboardado a MM API. Con product_policy: STRICT no se intenta fallback a Cloud API sin importar esta configuración.

Optimizaciones creativas automáticas: habilitadas por default a nivel plantilla; todas deshabilitadas por default a nivel WABA. Configura por plantilla o por WABA vía degrees_of_freedom_spec.creative_features_spec con enroll_status: OPT_IN|OPT_OUT por feature. Features: image_brightness_and_contrast, image_touchups, add_text_overlay, image_animation, image_background_gen, auto_promotion_tag, text_extraction_for_headline, text_extraction_for_tap_target, product_extensions, text_formatting_optimization. Pausadas/deprecadas (no se aplicarán): image cropping, text overlays, image animation, image background generation. Promedio de +13.9% CTR (A/B test sobre 50M mensajes, dic 2025–ene 2026). Consulta estados: GET /{template-id}?fields=degrees_of_freedom_spec o GET /{waba-id}?fields=degrees_of_freedom_spec.

Truncación de texto (no cambia contenido; el original queda accesible vía “Read more”): mensajes sin CTA pero con link en el body → 5 líneas; mensajes con header de media (imagen/video/documento/ubicación/GIF) → 3 líneas; mensajes sin header (texto) → 4 líneas.

La MM API es solo de envío: no recibe mensajes entrantes — usa Cloud API en paralelo en el mismo número.

Beneficios clave

1. Impulsar y medir resultados de negocio: con las optimizaciones automáticas de entrega, puedes llegar a más personas que encontrarán valiosos tus mensajes, lo que generó más lecturas y clics en pruebas. También puedes acceder a insights de medición:

   • Benchmarks de rendimiento, para entender cómo se desempeñó tu mensaje comparado con negocios similares.
   • Recomendaciones personalizadas, para mejorar el rendimiento de tus campañas.

2. Mejorar la experiencia y el engagement del cliente: la MM API ayuda a entregar mensajes de marketing más relevantes y oportunos con features como:

   • Optimizaciones creativas automáticas (en pruebas), para aplicar tratamientos creativos como animación de imágenes y filtros.
   • Formatos de media más ricos, como GIFs.
   • Time-to-live, para evitar entregas irrelevantes o retrasadas en campañas sensibles al tiempo.

3. Actualizar fácilmente, con confiabilidad y seguridad consistentes: la MM API ofrece un esquema técnico similar y el mismo modelo de facturación que Cloud API, y los negocios pueden usar números de teléfono y plantillas MM existentes.

Envía todo tu tráfico de marketing al endpoint /marketing_messages para el enrutamiento automático de los mensajes de negocios elegibles.

Endpoint del ISV:

POST /{v}/{did}/marketing_messages

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/{VERSION}/{did}/marketing_messages' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
    "messaging_product": "whatsapp",
    "recipient_type": "individual",
    "to": "PHONE_NUMBER",
    "type": "template",
    "template": {
      "name": "MARKETING_TEMPLATE_NAME",
      "language": { "code": "LANGUAGE_AND_LOCALE_CODE" },
      "components": []
    }
  }'

Nota: según Meta, un AB test con aproximadamente 12 millones de mensajes de marketing entregados en India (enero 2025) mostró que la entrega optimizada de MM API superó a la entrega estándar de Cloud API para mensajes de alto engagement (más lecturas, clics, etc.).

Verificar que el mensaje se envió con el webhook status

La MM API dispara webhooks de mensajes de estado para eventos como sent, delivered y read. Cuando un mensaje se envía vía MM API, el payload del webhook tendrá category y conversation.origin.type establecidos en marketing_lite:

{
  "conversation": {
    "id": "<CONVERSATION_ID>",
    "origin": {
      "type": "marketing_lite"
    }
  },
  "pricing": {
    "billable": true,
    "pricing_model": "PMP",
    "category": "marketing_lite"
  }
}

Disponibilidad geográfica de features

Algunas features avanzadas y capacidades de reporting de la MM API solo están disponibles en geografías particulares por política de Meta y/o regulación local.

Espacio Económico Europeo, Reino Unido, Japón, Corea del Sur, Nigeria, Sudáfrica

• Los mensajes enviados desde un número de negocio en estos países, o a un usuario de WhatsApp en estos países, no recibirán optimizaciones de entrega. Ten en cuenta que los límites de plantillas de marketing por usuario tampoco están activos aquí, así que la falta de optimizaciones no afecta la entrega.
• No habrá métricas de reporting de clics y conversiones.
• Las métricas no están disponibles en la UI de Ads Manager ni en Insights API. Como con Cloud API, las métricas estarán disponibles vía Business Management API y las métricas de ‘conversation’ de la UI de WhatsApp Manager.

Estados Unidos

• Desde el 1 de abril de 2025, los mensajes de marketing enviados a usuarios de WhatsApp en EE. UU. no se entregarán (error 131049). Esta política aplica a todas las Business Messaging APIs (incluida Cloud API).
• Los números de negocio en EE. UU. pueden seguir usando MM API para enviar mensajes a usuarios fuera de EE. UU.

Cuba, Irán, Corea del Norte, Siria, Venezuela y tres regiones sancionadas de Ucrania (Crimea, Donetsk, Luhansk)

• Los negocios en estas regiones no son elegibles para onboard, y no se pueden enviar mensajes a usuarios de WhatsApp en estas regiones. Aplica a todas las Business Messaging APIs.

Rusia, Bielorrusia

Desde el 20 de junio de 2025, los negocios en Rusia y Bielorrusia pueden usar MM API con las siguientes excepciones:

• Los mensajes enviados por un negocio con perfil de negocio de Meta en Rusia o Bielorrusia, o usando un método de pago con dirección en esos países, no recibirán optimizaciones de entrega.
• No habrá métricas de reporting de clics y conversiones. Las métricas continúan disponibles vía Business Management API y las métricas de conversación de WhatsApp Manager.
• Los mensajes a usuarios de WhatsApp en estos países no usarán features de optimización como max pricing.
• Todas las demás features de la MM API continúan disponibles.

Comparación de features con Cloud API

La MM API ofrece features añadidas que no están disponibles en Cloud API, como benchmarks y recomendaciones de rendimiento, time-to-live y optimizaciones creativas automáticas (pilot).

Features de optimización

Formatos de mensajes de marketing

Guidance

Métricas

Enterprise, seguridad y cumplimiento

Onboarding

Plantillas de marketing

Las plantillas de marketing se usan típicamente para impulsar engagement, conocimiento de marca y ventas. Son el único tipo de plantilla que se puede usar tanto con Cloud API como con Marketing Messages API para WhatsApp.

Plantillas personalizadas

Puedes usar la Message Templates API para crear plantillas de marketing personalizadas con cualquier componente soportado.

Componentes soportados en un custom marketing template:

Paso 1 — Crear: POST /message_templates/{VERSION}/{did} con category: "marketing" y parameter_format: "named" para usar parámetros nombrados ({{name}}):

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "welcome_discount_template",
  "language": "en_US",
  "category": "marketing",
  "parameter_format": "named",
  "components": [
    {
      "type": "header",
      "format": "image",
      "example": {
        "header_handle": ["4::aW1h..."]
      }
    },
    {
      "type": "body",
      "text": "Welcome to Lucky Shrub, {{first_name}}!\n\nUse code *{{discount_code}}* to get {{discount_amount}} off of your first purchase!",
      "example": {
        "body_text_named_params": [
          { "param_name": "first_name", "example": "Pablo" },
          { "param_name": "discount_code", "example": "WELCOME20" },
          { "param_name": "discount_amount", "example": "20%" }
        ]
      }
    },
    {
      "type": "footer",
      "text": "Lucky Shrub: Your gateway to succulents!"
    },
    {
      "type": "buttons",
      "buttons": [
        { "type": "url", "text": "View deals", "url": "https://www.luckyshrub.com/deals" },
        { "type": "phone_number", "text": "Call us", "phone_number": "+15550051310" },
        { "type": "quick_reply", "text": "Unsubscribe" }
      ]
    }
  ]
}'

Paso 2 — Enviar: la plantilla debe estar APPROVED. En el envío, los parámetros nombrados van en el body con parameter_name (pueden ir en cualquier orden) y el header de media usa el id del asset subido:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/messages/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "16505551234",
  "type": "template",
  "template": {
    "name": "welcome_discount_template",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "header",
        "parameters": [
          { "type": "image", "image": { "id": "1339522734477770" } }
        ]
      },
      {
        "type": "body",
        "parameters": [
          { "type": "text", "parameter_name": "first_name", "text": "Jessica" },
          { "type": "text", "parameter_name": "discount_code", "text": "WELCOME25" },
          { "type": "text", "parameter_name": "discount_amount", "text": "25%" }
        ]
      }
    ]
  }
}'

Plantillas especiales

Algunas plantillas usan un componente especial que requiere o excluye otros componentes, o requieren configuración adicional:

• Plantillas de catálogo: muestran tu catálogo de productos dentro de WhatsApp.
• Plantillas de código de cupón: muestran un botón único de copiar código. Al tocarlo, el código se copia al portapapeles del cliente.
• Plantillas de carousel de tarjetas de media: un solo mensaje de texto acompañado de hasta 10 tarjetas de media en vista horizontal desplazable.
• Plantillas de solicitud de permiso de llamada: permiten llamar a tus clientes fuera de la ventana de servicio al cliente.
• Plantillas de oferta por tiempo limitado: muestran fechas de expiración y countdown timers para códigos de oferta.
• Plantillas multi-producto (MPM): hasta 30 productos de tu catálogo, organizados en hasta 10 secciones, en un solo mensaje.
• Plantillas de carousel de tarjetas de producto: un solo mensaje de texto acompañado de hasta 10 tarjetas de producto en vista horizontal desplazable.
• Plantillas de producto único (SPM): un solo mensaje de texto acompañado de hasta 10 tarjetas de producto en vista horizontal desplazable.

Plantilla de solicitud de permiso de llamada

Las plantillas de solicitud de permiso de llamada permiten pedir permiso para llamar a usuarios de WhatsApp. Incluyen un componente body (requerido) y un componente call_permission_request. Cuando el usuario recibe el mensaje, puede otorgar o denegar el permiso para que tu negocio lo llame.

Se pueden categorizar como MARKETING o UTILITY. Este ejemplo usa MARKETING. Para un ejemplo con categoría UTILITY, consulta utility call permission request templates.

Limitaciones:

• Solo las plantillas categorizadas como MARKETING o UTILITY pueden incluir un componente de solicitud de permiso de llamada.
• Debes incluir texto de body, y no debe estar vacío.
• No puedes combinar el componente de solicitud de permiso de llamada con otros componentes interactivos.

Crear: POST /message_templates/{VERSION}/{did} con parameter_format: "named":

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "vip_early_access_call",
  "language": "en_US",
  "category": "MARKETING",
  "parameter_format": "named",
  "components": [
    {
      "type": "body",
      "text": "Hi {{first_name}}, as a Lucky Shrub VIP, get a first look at our rare new succulents before anyone else. Can we give you a quick call?",
      "example": {
        "body_text_named_params": [
          { "param_name": "first_name", "example": "Pablo" }
        ]
      }
    },
    {
      "type": "call_permission_request"
    }
  ]
}'

Enviar: la plantilla debe estar APPROVED. En el envío, los parámetros nombrados van en el body con parameter_name:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/messages/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+15551234567",
  "type": "template",
  "template": {
    "name": "vip_early_access_call",
    "language": { "policy": "deterministic", "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "parameter_name": "first_name", "text": "Pablo" }
        ]
      }
    ]
  }
}'

Plantilla de código de cupón

Las plantillas de código de cupón son plantillas de marketing que muestran un botón único de copiar código. Cuando el usuario toca el botón, WhatsApp copia el código de cupón al portapapeles.

Limitaciones:

• Actualmente no soportadas por el cliente web de WhatsApp.
• El texto del botón de copiar código no se puede personalizar.
• Las plantillas se limitan a un botón de copiar código.

Propiedades en creación vs. envío:

• Solo creación: texto del header, texto del body (con placeholders), etiqueta del botón quick reply, código de ejemplo del botón de copiar código.
• Solo envío: valores de los parámetros del body (coupon_code, discount), el código de cupón (valor del botón de copiar código).
• Ambos: nombre e idioma de la plantilla.

Crear: POST /message_templates/{VERSION}/{did} con parameter_format: "named":

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "winter_sale_coupon",
  "language": "en_US",
  "category": "MARKETING",
  "parameter_format": "named",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our Winter Sale is on!"
    },
    {
      "type": "BODY",
      "text": "Shop now through the end of December and use the one-time use code {{coupon_code}} to get {{discount}} off of your entire order!",
      "example": {
        "body_text_named_params": [
          { "param_name": "coupon_code", "example": "WINTER25" },
          { "param_name": "discount", "example": "30%" }
        ]
      }
    },
    {
      "type": "BUTTONS",
      "buttons": [
        { "type": "QUICK_REPLY", "text": "Unsubscribe" },
        { "type": "COPY_CODE", "example": "WINTER25" }
      ]
    }
  ]
}'

Enviar: la plantilla debe estar APPROVED. El código de cupón se provee en el componente de botón con sub_type: "copy_code" y su index (zero-indexed):

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/messages/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "messaging_product": "whatsapp",
  "to": "16505551234",
  "type": "template",
  "template": {
    "name": "winter_sale_coupon",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "parameter_name": "coupon_code", "text": "WINTER25" },
          { "type": "text", "parameter_name": "discount", "text": "30%" }
        ]
      },
      {
        "type": "button",
        "sub_type": "copy_code",
        "index": 1,
        "parameters": [
          { "type": "coupon_code", "coupon_code": "WINTER25" }
        ]
      }
    ]
  }
}'

Plantilla de oferta por tiempo limitado

Las plantillas de oferta por tiempo limitado muestran fechas de expiración y countdown timers para códigos de oferta en mensajes de plantilla.

Limitaciones:

• Solo se soportan plantillas categorizadas como MARKETING.
• No se soportan componentes de footer.
• Los usuarios que ven el mensaje con la app web o de escritorio de WhatsApp no verán la oferta; ven un aviso indicando que la oferta por tiempo limitado no es soportada.

Crear: POST /message_templates/{VERSION}/{did} con el componente limited_time_offer:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "limited_time_offer_caribbean_pkg_2023",
  "language": "en_US",
  "category": "marketing",
  "components": [
    {
      "type": "header",
      "format": "image",
      "example": { "header_handle": ["4::aW..."] }
    },
    {
      "type": "limited_time_offer",
      "limited_time_offer": {
        "text": "Expiring offer!",
        "has_expiration": true
      }
    },
    {
      "type": "body",
      "text": "Good news, {{1}}! Use code {{2}} to get 25% off all Caribbean Destination packages!",
      "example": { "body_text": [["Pablo", "CARIBE25"]] }
    },
    {
      "type": "buttons",
      "buttons": [
        { "type": "copy_code", "example": "CARIBE25" },
        {
          "type": "url",
          "text": "Book now!",
          "url": "https://awesomedestinations.com/offers?code={{1}}",
          "example": ["https://awesomedestinations.com/offers?ref=n3mtql"]
        }
      ]
    }
  ]
}'

Enviar: la plantilla debe estar APPROVED. El código de oferta y su timestamp de expiración se proveen al enviar:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/messages/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "16505555555",
  "type": "template",
  "template": {
    "name": "limited_time_offer_caribbean_pkg_2023",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "header",
        "parameters": [
          { "type": "image", "image": { "id": "1602186516975000" } }
        ]
      },
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Pablo" },
          { "type": "text", "text": "CARIBE25" }
        ]
      },
      {
        "type": "limited_time_offer",
        "parameters": [
          {
            "type": "limited_time_offer",
            "limited_time_offer": { "expiration_time_ms": 1209600000 }
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "copy_code",
        "index": 0,
        "parameters": [
          { "type": "coupon_code", "coupon_code": "CARIBE25" }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": 1,
        "parameters": [
          { "type": "text", "text": "n3mtql" }
        ]
      }
    ]
  }
}'

Combinar con botones de solicitud de pago: solo para negocios en Brasil con botones CTA de pago (Pix, Boleto o Payment Link). Permite envíos de pago sensibles al tiempo con countdown timer y las opciones de pago disponibles dentro del mensaje. Ver Payment Request CTA Templates (Brazil).

Plantilla de ubicación

Las plantillas de ubicación envían un mensaje de marketing con un header de mapa que muestra una ubicación específica. Cuando el usuario toca el mapa, su app de mapas por defecto abre esas coordenadas. Útiles para aperturas de tiendas, invitaciones a eventos, pop-up shops y promociones basadas en ubicación.

Se pueden categorizar como MARKETING o UTILITY. Este ejemplo usa MARKETING. Para un ejemplo con categoría UTILITY (por ejemplo, tracking de pedidos o actualizaciones de entrega), consulta utility location templates.

Limitaciones:

• Solo las plantillas categorizadas como UTILITY o MARKETING pueden incluir un header de ubicación.
• No se soportan ubicaciones en tiempo real.
• La ubicación (latitud, longitud, nombre, dirección) se especifica al enviar, no al crear la plantilla.

Componentes soportados:

• 1 header de ubicación (requerido)
• 1 body (requerido; soporta parámetros nombrados)
• 1 footer (opcional)
• Botones (opcional)

Crear: POST /message_templates/{VERSION}/{did} con parameter_format: "named":

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "store_grand_opening",
  "language": "en_US",
  "category": "MARKETING",
  "parameter_format": "named",
  "components": [
    {
      "type": "HEADER",
      "format": "LOCATION"
    },
    {
      "type": "BODY",
      "text": "Hi {{customer_name}}! We are opening a new store near you. Visit us on opening day for {{discount}} off your first purchase!",
      "example": {
        "body_text_named_params": [
          { "param_name": "customer_name", "example": "Lisa" },
          { "param_name": "discount", "example": "20%" }
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Reply STOP to unsubscribe."
    },
    {
      "type": "BUTTONS",
      "buttons": [
        { "type": "QUICK_REPLY", "text": "Unsubscribe from Promos" }
      ]
    }
  ]
}'

Enviar: la plantilla debe estar APPROVED. Debes especificar las coordenadas de la ubicación al enviar, en el componente header:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/messages/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "template",
  "template": {
    "name": "store_grand_opening",
    "language": { "policy": "deterministic", "code": "en_US" },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "location",
            "location": {
              "latitude": "34.01881798498779",
              "longitude": "-118.46708679200001",
              "name": "Lucky Shrub - Santa Monica",
              "address": "3250 Ocean Park Blvd, Santa Monica, CA 90405"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          { "type": "text", "parameter_name": "customer_name", "text": "Maria" },
          { "type": "text", "parameter_name": "discount", "text": "15%" }
        ]
      }
    ]
  }
}'

Los valores de latitud y longitud son obligatorios; name y address son opcionales. Los valores de envío son independientes de los ejemplos usados en la creación.

Plantilla de carousel de tarjetas de media

Las plantillas de carousel de tarjetas de media envían un mensaje de plantilla de marketing acompañado de hasta 10 tarjetas de media de producto en una vista horizontal desplazable.

Cuando el usuario toca el botón URL de una tarjeta para comprar el producto, la URL mapeada se abre en el navegador por defecto del dispositivo, sacando al usuario de la experiencia del cliente de WhatsApp. Si prefieres mantener al usuario dentro de WhatsApp, usa las Plantillas de carousel de tarjetas de producto. Las tarjetas de carousel solo están disponibles para mensajes de plantillas de marketing.

Tarjetas de media:

• Un mensaje body + hasta 10 tarjetas de media.
• Cada tarjeta: header de imagen o video (asset) + body opcional (máx. 160 caracteres) + hasta 2 botones (mezcla de quick reply, teléfono y URL).
• Todas las tarjetas definidas en una plantilla deben tener los mismos componentes; si una tarjeta tiene body text, todas deben tenerlo (para alturas consistentes).
• Cuando los usuarios hacen pedidos, lo hacen fuera del cliente de WhatsApp, por lo que no se disparan webhooks describiendo su pedido.

Crear: define la cantidad exacta de tarjetas (mínimo 2, máximo 10) al crear la plantilla. Una plantilla aprobada solo puede enviar la misma cantidad de tarjetas definida en su creación. POST /message_templates/{VERSION}/{did}:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "carousel_template_media_cards_v1",
  "language": "en_US",
  "category": "marketing",
  "components": [
    {
      "type": "body",
      "text": "Rare succulents for sale! {{1}}, add these unique plants to your collection. Each of these rare succulents are {{2}} if you checkout using code {{3}}. Shop now and add some unique and beautiful plants to your collection!",
      "example": { "body_text": [["Pablo", "30%", "30OFF"]] }
    },
    {
      "type": "carousel",
      "cards": [
        {
          "components": [
            {
              "type": "header",
              "format": "image",
              "example": { "header_handle": ["4::an..."] }
            },
            {
              "type": "buttons",
              "buttons": [
                { "type": "quick_reply", "text": "Send me more like this!" },
                {
                  "type": "url",
                  "text": "Shop",
                  "url": "https://www.luckyshrub.com/rare-succulents/{{1}}",
                  "example": ["BLUE_ELF"]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}'

Enviar: la plantilla debe estar APPROVED. Se proveen los mismos body variables y el contenido de cada tarjeta (card_index zero-indexed, asset ID del header, payload del botón quick reply, y texto a inyectar en la URL):

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/messages/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "template",
  "template": {
    "name": "carousel_template_media_cards_v1",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "Pablo" },
          { "type": "text", "text": "20%" },
          { "type": "text", "text": "20OFF" }
        ]
      },
      {
        "type": "carousel",
        "cards": [
          {
            "card_index": 0,
            "components": [
              {
                "type": "header",
                "parameters": [
                  { "type": "image", "image": { "id": "1558081531584829" } }
                ]
              },
              {
                "type": "button",
                "sub_type": "quick_reply",
                "index": "0",
                "parameters": [ { "type": "payload", "payload": "more-aloes" } ]
              },
              {
                "type": "button",
                "sub_type": "url",
                "index": "1",
                "parameters": [ { "type": "text", "text": "blue-elf" } ]
              }
            ]
          }
        ]
      }
    ]
  }
}'

Nota sobre índices: si cualquier botón usa variables, el tipo y orden de los botones debe coincidir con el tipo y orden definidos en la plantilla. No puedes usar los valores de index para reordenar los botones en el envío; el index debe mapear el orden definido en la plantilla.

Límites de plantillas de marketing por usuario

WhatsApp puede limitar la cantidad de plantillas de marketing que una persona recibe de cualquier negocio en un período, comenzando por entregar menos conversaciones de marketing a usuarios con menor probabilidad de engagement. En la mayoría de los mercados de WhatsApp, esto se determina según varios factores, incluida una vista dinámica de la tasa de lectura de mensajes de marketing del individuo.

Consulta límites de plantillas de marketing por usuario para más información.

Preferencias de usuario para mensajes de marketing

WhatsApp proporciona una configuración, Offers and announcements, que permite a los usuarios indicar su nivel de interés en mensajes de marketing y detener o reanudar la entrega de mensajes de marketing de tu negocio.

Feedback de interés/desinterés

Los usuarios pueden usar Offers and announcements para indicar cuán interesados están en recibir plantillas de marketing.

Si un usuario elige Not interested, puede afectar los límites de plantillas de marketing por usuario. También muestra un segundo modal que ofrece detener la entrega de mensajes de marketing de tu negocio.

Nota: el feedback de Interesado/No interesado no dispara el webhook user_preferences. Solo las acciones de detener y reanudar disparan el webhook.

Controles de detener/reanudar

Los usuarios pueden usar Offers and announcements para detener o reanudar la entrega de plantillas de marketing.

Si intentas enviar una plantilla de marketing a un usuario que ha detenido los mensajes de marketing de tu negocio, la API procesará la solicitud pero no enviará el mensaje. En su lugar, la API disparará un webhook de mensajes de estado con:

• status establecido en failed,
• code establecido en 131050,
• title establecido en Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business.

Para ser notificado cuando un usuario detiene o reanuda la entrega de plantillas de marketing, suscríbete al webhook user_preferences.

Cuentas vinculadas con la app de WhatsApp Business

Para mejorar la experiencia de los usuarios de WhatsApp Business, los mensajes de marketing enviados a clientes de negocio no suben los hilos del chat a la parte superior de la bandeja de entrada. Estos mensajes aún se entregan y son visibles, pero el hilo solo sube si el cliente responde.

Nota: esta feature está actualmente limitada y no está disponible de forma general (GA) para todos los usuarios.

Plantillas de utilidad

Las plantillas de utilidad se envían típicamente en respuesta a una acción o solicitud del usuario, como una confirmación de pedido o una actualización.

Tienen requisitos de contenido estrictos, particularmente en cuanto a material de marketing. Si intentas crear o actualizar una plantilla de utilidad con material de marketing, la plantilla se recategorizará automáticamente como plantilla de marketing. Consulta la categorización de plantillas para las guías de contenido.

Componentes soportados:

• 1 header (opcional; todos los tipos soportados)
• 1 body
• 1 footer (opcional)
• Hasta 10 botones (opcional). Tipos soportados:
  • Call request
  • Copy code
  • Phone number
  • Quick-reply
  • URL

Crear: POST /message_templates/{VERSION}/{did} con category: "utility":

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "reservation_confirmation",
  "language": "en_US",
  "category": "utility",
  "parameter_format": "named",
  "components": [
    {
      "type": "header",
      "format": "image",
      "example": { "header_handle": ["4::aW..."] }
    },
    {
      "type": "body",
      "text": "*You'\''re all set!*\n\nYour reservation for {{number_of_guests}} at Lucky Shrub Eatery on {{day}}, {{date}}, at {{time}}, is confirmed. See you then!",
      "example": {
        "body_text_named_params": [
          { "param_name": "number_of_guests", "example": "4" },
          { "param_name": "day", "example": "Saturday" },
          { "param_name": "date", "example": "August 30th, 2025" },
          { "param_name": "time", "example": "7:30 pm" }
        ]
      }
    },
    {
      "type": "footer",
      "text": "Lucky Shrub Eatery: The Luckiest Eatery in Town!"
    },
    {
      "type": "buttons",
      "buttons": [
        {
          "type": "url",
          "text": "Change reservation",
          "url": "https://www.luckyshrubeater.com/reservations"
        },
        {
          "type": "phone_number",
          "text": "Call us",
          "phone_number": "+15550051310"
        },
        {
          "type": "quick_reply",
          "text": "Cancel reservation"
        }
      ]
    }
  ]
}'

Enviar: la plantilla debe estar APPROVED. Los parámetros nombrados van en el body con parameter_name:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/messages/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "16505551234",
  "type": "template",
  "template": {
    "name": "reservation_confirmation",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "header",
        "parameters": [
          { "type": "image", "image": { "id": "2871834006348767" } }
        ]
      },
      {
        "type": "body",
        "parameters": [
          { "type": "text", "parameter_name": "number_of_guests", "text": "4" },
          { "type": "text", "parameter_name": "day", "text": "Saturday" },
          { "type": "text", "parameter_name": "date", "text": "August 30th, 2025" },
          { "type": "text", "parameter_name": "time", "text": "7:30 pm" }
        ]
      }
    ]
  }
}'

Plantillas de autenticación

Si tu app móvil ofrece a los usuarios la opción de recibir contraseñas de un solo uso (OTP) o códigos de verificación por WhatsApp, debes usar una plantilla de autenticación.

Composición de una plantilla de autenticación:

• Texto preestablecido fijo, no personalizable: <VERIFICATION_CODE> is your verification code.
• Un disclaimer de seguridad opcional: For your security, do not share this code. (add_security_recommendation)
• Una advertencia de expiración opcional: This code expires in <NUM_MINUTES> minutes. (code_expiration_minutes, 1–90)
• Un botón: one-tap autofill, copy code, o ningún botón (zero-tap).

Tipos de botones:

• One-tap autofill: abre tu app y entrega el código sin salir de WhatsApp. Requiere cambios en el código de la app Android (supported_apps con package_name + signature_hash).
• Copy code: copia el código al portapapeles al tocarlo.
• Zero-tap: transmite el código; tu app lo captura con un broadcast receiver. Solo Android.

Seguridad de dispositivos vinculados (linked device security): los mensajes de autenticación solo se entregan al dispositivo primario del usuario. Los mensajes enviados a dispositivos vinculados se enmascaran con un prompt para verlos en el dispositivo primario. Habilitado por defecto, no requiere cambios de código, no es configurable. Solo disponible en Cloud API.

Keyboard suggestions (iOS): desde el 15 de junio de 2026, habilitado por defecto para todas las plantillas de autenticación. En iOS 26+, iOS detecta el OTP en la notificación push y muestra un prompt de autofill en el teclado. Sin cambios de integración. Solo detecta códigos numéricos de 3 a 8 dígitos; no se dispara cuando WhatsApp está en foreground.

Crear: POST /message_templates/{VERSION}/{did} con category: "authentication":

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "verification_code",
  "language": "en_US",
  "category": "authentication",
  "message_send_ttl_seconds": 60,
  "components": [
    {
      "type": "body",
      "add_security_recommendation": true
    },
    {
      "type": "footer",
      "code_expiration_minutes": 10
    },
    {
      "type": "buttons",
      "buttons": [
        {
          "type": "otp",
          "otp_type": "one_tap",
          "text": "Copy Code",
          "autofill_text": "Autofill",
          "supported_apps": [
            { "package_name": "com.example.luckyshrub", "signature_hash": "K8a/AINcGX7" }
          ]
        }
      ]
    }
  ]
}'

Nota: en la creación el tipo de botón se designa como otp, pero al crearse se convierte a url (verificable con un GET de la plantilla).

Enviar: la plantilla debe estar APPROVED. El OTP se envía dos veces: en el body y en el botón:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/messages/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "12015553931",
  "type": "template",
  "template": {
    "name": "verification_code",
    "language": { "code": "en_US" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "J$FpnYnP" }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": 0,
        "parameters": [
          { "type": "text", "text": "J$FpnYnP" }
        ]
      }
    ]
  }
}'

Vistas previas (previews): puedes generar vistas previas del texto de la plantilla de autenticación en varios idiomas con GET /message_template_previews (category=AUTHENTICATION, add_security_recommendation, code_expiration_minutes, button_types=OTP).

Bulk management: crea o actualiza plantillas de autenticación en varios idiomas con POST /{waba-id}/upsert_message_templates (usa languages en vez de language; text y autofill_text no soportados).

Mensajes de servicio

Los mensajes de servicio son mensajes libres que puedes enviar a usuarios de WhatsApp durante una ventana de servicio al cliente. A diferencia de los mensajes de plantilla, no requieren aprobación previa — puedes componerlos y enviarlos según lo necesites en respuesta al mensaje o llamada de un usuario.

Solo se pueden enviar por el Messages API. Fuera de una ventana de servicio al cliente, usa mensajes de plantilla.

Ventanas de servicio al cliente

Cuando un usuario te escribe o te llama, se inicia un temporizador de 24 horas llamado ventana de servicio al cliente. Si el usuario te vuelve a escribir o llamar antes de que expire, el temporizador se reinicia a 24 horas.

Mientras la ventana está abierta, puedes enviar cualquiera de los tipos de mensaje de servicio listados abajo. Cuando la ventana se cierra, solo puedes enviar mensajes de plantilla pre-aprobados.

Recuerda: solo puedes enviar mensajes a usuarios de WhatsApp que hayan optado in a recibir mensajes tuyos.

Precios

Los mensajes de servicio se facturan bajo la categoría de precios SERVICE. Ver Pricing.

Tipos de mensaje

Request común:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/messages/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505551234",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "As requested, here'\''s the link to our latest product: https://www.meta.com/quest/quest-3/"
  }
}'

Notas importantes:

• Formato de números de teléfono: se soportan +, -, (, ) y espacios. Incluye siempre + y el código de país; si omites el +, se antepone el código de país de tu número de negocio (puede resultar en entregas no deseadas).
• Media caching: los assets alojados por link se cachean 10 minutos; agrega un query string aleatorio para forzar re-fetch.
• Secuencia de entrega: el orden de entrega no está garantizado; confirma el estado delivered en el webhook antes de enviar el siguiente mensaje si necesitas secuencia.
• TTL: 30 días para todos los mensajes excepto plantillas de autenticación (10 minutos). Si no recibes delivered antes del TTL, asume que el mensaje fue descartado.
• Marcar como leído: POST /messages con {"status":"read","message_id":"<wamid>"} (dentro de 30 días). Agrega typing_indicator: {"type":"text"} para mostrar indicador de escritura (se descarta al responder o tras 25 segundos).
• Respuestas contextuales: incluye context: {"message_id":"<wamid>"} para citar el mensaje anterior en una burbuja contextual.
• Calidad del mensaje: basada en cómo se recibieron los mensajes en los últimos 7 días (bloqueos, reportes, mutes, archivos). Sigue la WhatsApp Business Messaging Policy, envía solo a opt-in, personaliza y evita mensajes de bienvenida abiertos.

Crear plantilla

Plantilla de solo texto

Request

POST /message_templates/{VERSION}/{did}

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "pedido_cancelado_reembolso",
  "language": "es",
  "category": "UTILITY",
  "allow_category_change": true,
  "components": [
    {
      "type": "BODY",
      "text": "Su pedido ha sido cancelado; su reembolso se procesará en 7-10 días"
    }
  ]
}'

Propiedades:

Response

Éxito (200)

{
  "id": "<ID>",
  "status": "<STATUS>",
  "category": "<CATEGORY>"
}

Plantilla con header de imagen y body de texto

Request

POST /message_templates/{VERSION}/{did}

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "isv_template",
  "language": "es_ES",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_handle": [
          "4::aW1h"
        ]
      }
    },
    {
      "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" }
      ]
    }
  ]
}'

Response

Éxito (200)

{
  "id": "<ID>",
  "status": "<STATUS>",
  "category": "<CATEGORY>"
}

Editar plantilla

Request

PUT /message_templates/{VERSION}/{did}/{message_template_id}

curl --request PUT \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}/{message_template_id}' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{}'

Limitaciones

• Solo se pueden editar plantillas en estado APPROVED, REJECTED o PAUSED.
• Solo se pueden editar las propiedades category o components.
• No se puede editar la category de una plantilla aprobada.
• Las plantillas aprobadas se pueden editar máximo diez veces en 30 días o una vez cada 24 horas. Las rechazadas o en pausa, sin límite.
• Después de editar una plantilla aprobada o en pausa, se aprobará automáticamente a menos que no supere la revisión.

Body:

{
  "category": "<CATEGORY>",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Hola y bienvenido"
    }
  ]
}

Response

Éxito (200)

{
  "success": true
}

Obtener plantillas

Listar plantillas

Request

GET /message_templates/{VERSION}/{did}?fields=format,rejected_reason,quality_score,status,name,language,components,category,previous_category&limit=5

curl --request GET \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}?fields=format,rejected_reason,quality_score,status,name,language,components,category,previous_category&limit=5' \
  --header 'Authorization: <JWT>' \

Response

Éxito (200)

{
  "data": [
    {
      "id": "2606927862810126",
      "name": "un_template",
      "components": [{ "type": "BODY", "text": "this is" }],
      "language": "es",
      "status": "REJECTED",
      "category": "UTILITY",
      "rejected_reason": "INCORRECT_CATEGORY",
      "quality_score": { "score": "UNKNOWN" }
    },
    {
      "id": "402086912569912",
      "name": "test_template_dev",
      "components": [{ "type": "BODY", "text": "this is a test" }],
      "language": "es",
      "status": "APPROVED",
      "category": "MARKETING",
      "rejected_reason": "NONE",
      "quality_score": { "score": "UNKNOWN" }
    }
  ],
  "paging": {
    "cursors": { "before": "MAZDZD", "after": "MQZDZD" },
    "next": "https://login.chattigo.com/bsp-cloud-chattigo-isv/message_templates/v19.0/56940581384?fields=format,rejected_reason,quality_score,status,name,language,components,category,previous_category&limit=2&after=MQZDZD"
  }
}

Obtener sumario de plantillas

Request

GET /message_templates/{VERSION}/{did}?fields=id&limit=1&summary=total_count,message_template_count,message_template_limit,are_translations_complete

curl --request GET \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}?fields=id&limit=1&summary=total_count,message_template_count,message_template_limit,are_translations_complete' \
  --header 'Authorization: <JWT>' \

Response

Éxito (200)

{
  "data": [{ "id": "2606927862810126" }],
  "paging": {
    "cursors": { "before": "MAZDZD", "after": "MAZDZD" },
    "next": "https://login.chattigo.com/bsp-cloud-chattigo-isv/message_templates/v19.0/56940581384?limit=1&summary=total_count,message_template_count,message_template_limit,are_translations_complete&fields=id&after=MAZDZD"
  },
  "summary": {
    "total_count": 169,
    "message_template_count": 148,
    "message_template_limit": 6000,
    "are_translations_complete": false
  }
}

Obtener plantilla por nombre o contenido

Request

GET /message_templates/{VERSION}/{did}?name_or_content=tpl_flow_demo_preview&limit=1

curl --request GET \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}?name_or_content=tpl_flow_demo_preview&limit=1' \
  --header 'Authorization: <JWT>' \

Response

Éxito (200)

{
  "data": [
    {
      "id": "210800678688659",
      "name": "tpl_flow_demo_preview",
      "components": [
        {
          "type": "BODY",
          "text": "Hola y bienvenido a la demo de flow.\nPuedes responder a continuación las preguntas iniciales."
        },
        {
          "type": "BUTTONS",
          "buttons": [
            {
              "type": "FLOW",
              "text": "Responder",
              "flow_id": 2033644160334325,
              "flow_action": "NAVIGATE",
              "navigate_screen": "REGISTER"
            }
          ]
        }
      ],
      "language": "es",
      "status": "APPROVED",
      "category": "MARKETING"
    }
  ],
  "paging": {
    "cursors": { "before": "MAZDZD", "after": "MAZDZD" }
  }
}

Obtener plantilla por nombre

Request

GET /message_templates/{VERSION}/{did}?name=tpl_flow_demo_preview&limit=1

curl --request GET \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}?name=tpl_flow_demo_preview&limit=1' \
  --header 'Authorization: <JWT>'

Response

Éxito (200)

La respuesta es idéntica a la de obtener plantilla por nombre o contenido (name_or_content).

Cargar multimedia

Para cargar una imagen nueva a Meta, se consulta el siguiente endpoint:

Request

POST /{VERSION}/{did}/uploads

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/{VERSION}/{did}/uploads' \
  --header 'Authorization: <JWT>' \
  -F 'file=@/ruta/imagen.jpg'

Response

Éxito (200)

{
  "h": "4::aW1hZ2............."
}

Métricas de plantillas

Request

GET /message_templates/{VERSION}/{did}/analytics?granularity=DAILY&metric_types=["CLICKED","DELIVERED","READ","SENT"]&start=1709769600&end=1709841600&template_ids=[776614587250474]

curl --request GET \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}/analytics?granularity=DAILY&metric_types=["CLICKED","DELIVERED","READ","SENT"]&start=1709769600&end=1709841600&template_ids=[776614587250474]' \
  --header 'Authorization: <JWT>' \

Response

Éxito (200)

{
  "data": [
    {
      "granularity": "DAILY",
      "data_points": [
        {
          "template_id": "776614587250474",
          "start": 1709769600,
          "end": 1709856000,
          "sent": 2,
          "delivered": 2,
          "read": 2,
          "clicked": [
            {
              "type": "url_button",
              "button_content": "Visitar el sitio web",
              "count": 1
            },
            {
              "type": "url_button",
              "button_content": "Visitar el sitio web 2",
              "count": 1
            },
            {
              "type": "quick_reply_button",
              "button_content": "Si",
              "count": 1
            }
          ]
        }
      ]
    }
  ],
  "paging": {
    "cursors": { "before": "MAZDZD", "after": "MjQZD" }
  }
}

Eliminar una plantilla

Por nombre

Request

DELETE /message_templates/{VERSION}/{did}?name=test_name

curl --request DELETE \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}?name=test_name' \
  --header 'Authorization: <JWT>' \

Response

Éxito (200)

{
  "success": true
}

Por ID y nombre

Request

DELETE /message_templates/{VERSION}/{did}?hsm_id=1723223958184989&name=test_name

curl --request DELETE \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}?hsm_id=1723223958184989&name=test_name' \
  --header 'Authorization: <JWT>' \

Response

Éxito (200)

{
  "success": true
}

Habilitar analítica de una plantilla

Debes confirmar los análisis de plantillas en la cuenta de WhatsApp Business para poder obtener los datos, ya sea con el Administrador de WhatsApp o con la API.

Request

POST /message_templates/{VERSION}/{did}/enable_analytics

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}/enable_analytics' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{}'

Response

Éxito (200)

{
  "id": 102290129340398
}

Deshabilitar el análisis de clics en botones

Puedes desactivar el button click tracking en una plantilla individual configurando su campo cta_url_link_tracking_opted_out en true. Una vez deshabilitada, la API ya no devolverá la propiedad en la que se hizo clic en el análisis.

Request

POST /message_templates/{VERSION}/{did}/{message_template_id}?cta_url_link_tracking_opted_out=true&category=marketing

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}/{message_template_id}?cta_url_link_tracking_opted_out=true&category=marketing' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{}'

Query parameters:

Response

Éxito (200)

{
  "id": 102290129340398
}

Recuperar namespace de una plantilla

El namespace de la plantilla de mensaje se necesita para enviar mensajes con las plantillas.

Request

GET /message_templates/{VERSION}/{did}/message_template_namespace

curl --request GET \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}/message_template_namespace' \
  --header 'Authorization: <JWT>' \

Response

Éxito (200)

{
  "id": "1972385232742141",
  "message_template_namespace": "12abcdefghijk_34lmnop"
}

Migrar una plantilla

Request

POST /message_templates/{VERSION}/{did}/migrate_message_templates?source_waba_id=102290129340398&page_number=0

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/message_templates/{VERSION}/{did}/migrate_message_templates?source_waba_id=102290129340398&page_number=0' \
  --header 'Authorization: <JWT>' \
  --header 'Content-Type: application/json' \
  --data '{}'