Plantillas de WhatsApp en Business API

WhatsApp exige que los mensajes comerciales funcionen con reglas: plantillas previamente aprobadas para el primer mensaje, una ventana de 24 horas para mensajes libres y límites en los archivos adjuntos. Así funciona en Tesoro a través de Twilio.

Configuración de WhatsApp — Configuración de plantillas en la pantalla de configuración personal.

¿Cuándo es relevante?

El primer mensaje a un contacto falla y busca la regla de la plantilla.
La ventana de 24 horas ha expirado y no entiende por qué ya no puede enviar.
Quiere saber cuánto cuesta.

Cómo funciona la integración

Tesoro no se comunica directamente con WhatsApp:

Tesoro → envía un mensaje a la API de Twilio
Twilio → lo reenvía a la WhatsApp Business API (prefijo whatsapp:)
WhatsApp → entrega al destinatario
Actualizaciones de estado (delivered, read, failed) de vuelta a través de los webhooks de Twilio
Mensajes entrantes → en tiempo real a todos los miembros del equipo

Qué necesita

Componente	Descripción
Cuenta de Twilio	Activa, con saldo
Perfil de WhatsApp Business	Aprobado por Meta a través de Twilio
Número de WhatsApp registrado	Específico para WhatsApp Business API; configurado en Settings → Company Settings → Call Settings
Twilio SID + Token	Credenciales de API, configuradas por el administrador del sistema

Plantillas de mensajes: qué y por qué

Formatos de mensaje previamente aprobados. Obligatorios para el primer mensaje a un contacto.

En Tesoro, cada plantilla tiene:

Campo	Descripción	Validación
Title	Nombre para identificarla	3, 100 caracteres
Description	El contenido que se envía	3, 100 caracteres

Ver plantillas

Se cargan automáticamente al abrir la pestaña de WhatsApp en un registro. Disponible para Admin y Employee.

Enviar una plantilla

Abra la pestaña de WhatsApp del contacto, deal, lead o relación.
¿Sin historial de conversación? → el sistema solicita la selección de plantilla.
Elija del menú desplegable (título visible).
Get Started → la description se envía como texto del mensaje.
El mensaje se registra con el estado de entrega, el SID de Twilio y la dirección.

Proceso de aprobación (Meta)

Crear la plantilla: en Twilio o Meta Business Manager. Texto + categoría (marketing, transaccional, autenticación) + variables.
Revisión de Meta: de minutos a días.
Aprobación/rechazo: el panel de Twilio o Meta Business Manager muestra el estado.
Registro en Tesoro: las plantillas aprobadas aparecen en el menú desplegable.

Razones comunes de rechazo

Razón	Explicación
Contenido engañoso	Información incorrecta o engañosa
Sin opción de baja	Sin posibilidad de darse de baja para el destinatario
Contenido prohibido	Juegos de azar, alcohol, etc.
Formato incorrecto	Las variables o el formato no cumplen con los requisitos técnicos

Cuándo: primer mensaje o después de que expire la ventana de 24 horas
Cómo: seleccione la plantilla, el sistema envía la description
Archivos adjuntos: no compatible

Comparación:

Característica	Plantilla	Libre
Primer mensaje	✅ obligatorio	❌
Contenido	Predefinido	Libre
Longitud máxima	100 caracteres (límite de plantilla)	1.600 caracteres
Archivos adjuntos	❌	✅ (hasta 10)
Aprobación requerida	✅ (Meta)	❌

La ventana de conversación de 24 horas

Regla de WhatsApp para evitar el spam.

Usted envía un mensaje de plantilla → conversación abierta.
El contacto responde → comienza la ventana de 24 horas.
Durante 24 horas → puede enviar mensajes libres sin plantilla.
Sin respuesta en 24 h → la ventana se cierra. Se necesita una nueva plantilla para reabrir la conversación.

Qué hacer cuando la ventana ha expirado

¿Intenta enviar un mensaje libre después de 24 horas? WhatsApp lo rechaza.

Vuelva a la selección de plantillas.
Elija una plantilla aprobada.
Envíela; la ventana se reabre.
Espere la respuesta para los mensajes libres.

Mensajes multimedia: enviar archivos

Solo en mensajes libres, no en plantillas.

Cómo lo procesa Tesoro:

Cada archivo = un mensaje de WhatsApp independiente a través de Twilio con mediaUrl
El texto = un mensaje aparte
Los archivos se guardan en Tesoro y se vinculan al registro del mensaje

Tipos compatibles

Tipo	Ejemplos
Documentos	PDF, Word, Excel
Imágenes	JPEG, PNG, GIF, WebP
Audio	MP3, OGG
Vídeo	MP4
Archivos comprimidos	ZIP, RAR

Límites: máximo 10 archivos por mensaje, 1,5 MB cada uno.

Recibir archivos

El contacto envía un archivo → Tesoro:

Lo detecta mediante el webhook NumMedia de Twilio
Lo descarga desde la URL de medios de Twilio
Lo guarda en Tesoro con la extensión correcta (según el tipo MIME)
Lo vincula al registro del mensaje y al contacto

Estado de entrega y actualizaciones en tiempo real

Estados

Estado	Descripción
queued	En cola en Twilio
sent	Enviado a WhatsApp
delivered	En el dispositivo del destinatario
read	El destinatario lo ha leído
failed	No entregado

Actualizaciones en tiempo real

Mensaje entrante → notificación a todos los usuarios
Cambio de estado → actualización en vivo en la vista de chat (sin recargar la página)

Costos

Componente	Explicación
Tarifa de mensajes de Twilio	Por mensaje (entrante + saliente), varía según el país
Tarifa de conversación de WhatsApp	Por ventana de 24 horas; diferencia entre la iniciada por la empresa (plantilla) y la iniciada por el usuario (respuesta)
Categoría de la plantilla	Marketing > transaccional > autenticación
Mensajes multimedia	Costo adicional según el tipo + el tamaño

Permisos

Acción	Quién
Enviar mensajes (libres)	Admin, Employee
Enviar mensajes (plantilla)	Admin, Employee
Leer mensajes	Admin, Employee
Ver plantillas	Admin, Employee

Errores frecuentes

La plantilla no aparece: verifique el título + la description (ambos de 3 a 100 caracteres). Puede que no esté registrada en Twilio.
“The selected template doesn’t match our records”: el ID de la plantilla ya no existe (¿eliminada?).
Mensaje rechazado después de 24 horas: la ventana ha expirado. Envíe una nueva plantilla.
No se pueden adjuntar archivos en una plantilla: use un mensaje libre (después de la respuesta del contacto).
“Company with Twilio WhatsApp number attached not found”: el número del webhook de Twilio no coincide con ninguna empresa. Verifique Settings → Company Settings → Call Settings.

Próximos pasos

Conceptos básicos de WhatsApp y SMSCómo enviar y recibir, y qué configuración se necesita.

Llamadas telefónicasProgramar y llamar a través de Twilio.