Plantillas de WhatsApp y 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í es como funciona en Tesoro a través de Twilio.

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

¿Cuándo es relevante?

El primer mensaje a un contacto falla, 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 → My Company → 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. Obligatorio para el primer mensaje a un contacto.

En Tesoro, cada plantilla tiene:

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

Ver plantillas

Se cargan automáticamente cuando abre 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).
Haga clic en Get Started → se envía la description 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: 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 cancelación	Sin posibilidad de darse de baja para el destinatario
Contenido prohibido	Juegos de azar, alcohol, etc.
Formato incorrecto	Variables o 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 plantilla, el sistema envía 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 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 24h → 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íe, la ventana se reabre.
Espere la respuesta para 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
Texto = mensaje independiente
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
Video	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:

Detecta mediante el webhook NumMedia de Twilio
Descarga desde la URL multimedia de Twilio
Guarda en Tesoro con la extensión correcta (del tipo MIME)
Vincula al registro del mensaje y al contacto

Estado de entrega y actualizaciones en tiempo real

Estados

Estado	Qué significa
queued	En cola en Twilio
sent	Enviado a WhatsApp
delivered	Entregado 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 necesidad de recargar la página)

Costos

Componente	Explicación
Tarifa de mensaje de Twilio	Por mensaje (entrante + saliente), varía según el país
Tarifa de conversación de WhatsApp	Por ventana de 24 horas, difiere entre iniciada por empresa (plantilla) e iniciada por usuario (respuesta)
Categoría de plantilla	Marketing > transaccional > autenticación
Mensajes multimedia	Costos adicionales según tipo y 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 comunes

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

Pasos siguientes

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

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