Mensajes con plantilla

Last update: 4 days ago by Irais Aguirre

Los mensajes con plantilla son plantillas de mensaje reutilizables y previamente aprobadas con marcadores de posición para variables, y son el único medio para iniciar una conversación con un cliente.

Resumen para integración
Endpoint: POST https://{{url}}/whatsapp-bsp-api-endpoint-ws/services/v1/messaging
Token: de mensajería, en el encabezado Authorization: Bearer {{wa-msg-api-token}} (cómo generarlo)
Campos comunes: from, to (teléfono o BSUID) y type (detalle)
Respuesta: la misma para todos los mensajes (ver respuesta) En los mensajes con plantilla:

Las plantillas son mensajes que pueden contener texto y recursos multimedia (imagen, documento, video).
Se pueden sustituir variables en la plantilla (placeholders), para personalizar un mensaje.
Es el único medio para iniciar una conversación con su cliente.
Para utilizarlas, deben ser aprobadas por Whatsapp. Le pedimos que se acerque a nuestro equipo de Operaciones para que lo oriente en el proceso de aprobación.

Todos los mensajes con plantilla se envían con POST /v1/messaging; los encabezados, los campos comunes y la respuesta están en Conexión HTTP.

En esta sección:

Texto, moneda y fecha: Parámetros de texto, moneda y fecha y hora que se sustituyen en los componentes header y body de la plantilla.
Multimedia y ubicación: Parámetros de imagen, documento, video y ubicación para el componente header de la plantilla.
Botones: Plantillas con botones: respuesta rápida, contraseña de un solo uso, realizar llamada y abrir URL.
WhatsApp Flows: Plantillas que abren un WhatsApp Flow.
Secuencia: Plantillas de secuencia (carrusel) con tarjetas desplazables.
Cupones y ofertas por tiempo limitado: Plantillas con códigos de cupón y ofertas por tiempo limitado.

Estructura general

El campo type debe ser "template". Los campos from y to se describen en Campos comunes.

Nombre	Descripción	Tipo	Requerimientos
template	Objeto que contiene las propiedades de la plantilla	Objeto	Obligatorio

Objeto template

Nombre	Descripción	Tipo	Requerimientos
language	Lenguaje local, Ejemplo: es_ES, es_MX, es_US	String	Oblicatorio
name	Nombre de la plantilla	String	Obligatorio
components	Arreglo de objetos que contiene la configuración de la plantilla	Array	Opcional

Objeto components

Nombre	Descripción	Tipo	Requerimientos
type	Tipo de componente. Los valores pueden ser: header: encabezado de la plantilla. body: cuerpo de la plantilla. button: botones para acciones de la plantilla footer: pie de página de la plantilla. carousel: mensaje de texto único acompañado de un conjunto de hasta 10 tarjetas de carrusel en una vista desplazable horizontalmente limited_time_offer: permiten mostrar fechas de caducidad y temporizadores de cuenta regresiva para códigos de oferta	String	Obligatorio
subtype	quick_reply: Se refiere a un botón de respuesta rápida creado previamente que permite al cliente devolver un mensaje predefinido. url: se refiere a un botón creado previamente que permite al cliente visitar la URL generada al agregar el parámetro de texto a la URL del prefijo predefinido en la plantilla. catalog: Se refiere a un botón de catálogo creado previamente que permite al cliente devolver un catálogo de productos completo. copy_code: botón de copiar código de cupón. flow: botón que abre un WhatsApp Flow. voice_call: botón que inicia una llamada de voz de WhatsApp al negocio. call_permission_request: botón que solicita al usuario conceder permiso de llamada. mpm: botón de mensaje de múltiples productos. spm: botón de mensaje de un solo producto. order_details: botón para detalles de orden (Pagos Brasil). order_status: botón para estado de orden (Pagos Brasil). payment_request: botón para solicitud de pago (Pagos Brasil).	String	Es obligatorio cuando se utiliza con el tipo button.
index	Indice para los parametros de tipo payload.	Integer	Opcional Se utiliza con el tipo button Los valores del index pueden ser: 0,1,2
parameters	Arreglo de tipos de Plantilla. Los valores pueden ser: text currency date_time image document video location payload action coupon_code limited_time_offer gif	Array	Opcional (obligatorio para componentes `limited_time_offer`)

Relación de Tipos de Parámetros vs Tipos de Componente

Tipos de Parámetro	header	body	button
text	Si	Si	Si (URL/OTP)
currency	Si	Si	No
date_time	Si	Si	No
image	Si	No	No
document	Si	No	No
video	Si	No	No
location	Si	No	No
payload	No	No	Si
action	No	No	Si
coupon_code	No	No	Si

WABA ID (derivado por el servidor)

La cuenta de WhatsApp Business (WABA) de destino para el envío de una plantilla no se lee del cuerpo de la petición. Se deriva del encabezado Authorization: Bearer {token}: el token de mensajería se vincula a una sola WABA al emitirse, y esa WABA se utiliza para cada envío realizado con el token.

No necesitas enviar wba_id / waba_id en el cuerpo del mensaje. Cualquier campo de este tipo se ignora para el enrutamiento.
Para enviar desde otra WABA, genera un nuevo token de mensajería para esa WABA.
Los endpoints de administración (gestión de plantillas, grupos, etc.) siguen recibiendo {{waba_id}} en la ruta de la URL, porque un token de administración puede pertenecer a un usuario que gestiona varias WABAs.

Solicitud de permiso de llamada

Texto, moneda y fecha