WhatsApp Business

Permiso: settings.view
→ Módulos y permisos

¿Qué es?

La integración de WhatsApp Business permite enviar directamente desde Sonata:

• 📄 Facturas, cotizaciones y pedidos en PDF.
• 🎫 Cupones de descuento.
• 📅 Confirmaciones y recordatorios de citas (módulo Agenda).
• 🎂 Cupones de cumpleaños automáticos (módulo Marketing).

La integración usa Evolution API, una plataforma de código abierto que actúa como puente entre Sonata y WhatsApp Business.

Requisito previo

Necesitas una instancia de Evolution API activa y un número de WhatsApp Business conectado a ella. Puedes instalarla en tu servidor o contratar el servicio con tu proveedor de Sonata.

---

Opción A — Contratar con tu proveedor

Si tu proveedor de Sonata ya ofrece Evolution API como servicio:

1. Solicita las credenciales (URL de instancia + API key).
2. Salta directo a Conectar en Sonata.

---

Opción B — Instalar Evolution API propio

Requisitos del servidor

Componente	Mínimo recomendado
OS	Ubuntu 20.04+ / Debian 11+
RAM	1 GB
CPU	1 vCPU
Docker	Versión 20+
Dominio o IP pública	Para el webhook

Instalación con Docker

# 1. Clonar el repositorio oficial
git clone https://github.com/EvolutionAPI/evolution-api.git
cd evolution-api

# 2. Copiar el archivo de configuración
cp .env.example .env

# 3. Editar las variables obligatorias en .env
#    AUTHENTICATION_API_KEY=tu-clave-segura-aqui
#    AUTHENTICATION_EXPOSE_IN_FETCH_INSTANCES=true

# 4. Levantar el contenedor
docker-compose up -d

# La API queda disponible en http://tu-servidor:8080

Usar HTTPS

Para entornos de producción, coloca un reverse proxy (nginx + Certbot) delante de Evolution API para que trabaje sobre HTTPS. WhatsApp requiere webhooks en HTTPS.

Conectar el número de WhatsApp

1. Abre la interfaz de Evolution API en tu navegador: http://tu-servidor:8080.
2. Usa el Swagger UI (o la API directamente) para crear una instancia:

   POST /instance/create
   {
     "instanceName": "sonata",
     "token": "tu-api-key"
   }

3. Obtén el QR code:

   GET /instance/qrcode/sonata

4. Abre WhatsApp Business en el teléfono → Dispositivos vinculados → Vincular dispositivo.
5. Escanea el QR. La instancia queda conectada.

Estabilidad del número

Usa un número dedicado exclusivamente a Sonata. Si el número se desconecta (cierre de sesión en el teléfono, inactividad), perderás la integración hasta reconectar.

---

Conectar en Sonata

Con la instancia de Evolution API activa y el número conectado:

1. Ve a Configuración → WhatsApp (o desde el menú: ⚙️ → WhatsApp).
2. Completa los campos:

Campo	Descripción
URL de la instancia	Base URL de tu Evolution API. Ej: https://whatsapp.miempresa.com
Nombre de la instancia	Nombre de la instancia que creaste (ej. sonata).
API Key	La clave configurada en AUTHENTICATION_API_KEY del .env.

3. Haz clic en Probar conexión.
   • ✅ Éxito: "Instancia conectada — número activo".
   • ❌ Error: revisa la URL, la API key y que el contenedor esté corriendo.
4. Guarda la configuración.

Una vez guardado, todos los botones "Enviar por WhatsApp" del sistema quedan habilitados automáticamente.

---

Usos en el sistema

Enviar un documento al cliente

Desde el detalle de cualquier factura, cotización o pedido:

1. Haz clic en Enviar por WhatsApp.
2. El sistema usa el teléfono registrado en el cliente.
3. El mensaje incluye un saludo personalizado + el PDF adjunto.

Número del cliente

El cliente debe tener un teléfono registrado en su perfil para que el botón funcione. El número debe incluir el código de país (ej. +507 6xxx-xxxx para Panamá). → Clientes

Enviar cupones

Desde Marketing → Cupones → detalle del cupón → Enviar por WhatsApp. Selecciona el cliente y envía.

Confirmaciones de citas (Agenda)

Al crear o reagendar una cita, si el paciente tiene teléfono registrado y WhatsApp está conectado, el sistema envía automáticamente la confirmación.

Campañas de cumpleaños

El cupón de cumpleaños se envía por WhatsApp a las 07:00 del día del cumpleaños del cliente. → Campañas de marketing

---

Solución de problemas

Síntoma	Causa probable	Solución
Botón de WhatsApp deshabilitado	WhatsApp no configurado o desconectado	Verifica en Configuración → WhatsApp
"Error al enviar" al hacer clic	La instancia se desconectó	Reconecta el QR en Evolution API
El cliente no recibe el mensaje	Número incorrecto o sin código de país	Edita el teléfono del cliente con el formato +507 XXXX-XXXX
El servidor de Evolution API no responde	Contenedor caído	Ejecuta docker-compose up -d en el servidor
Mensajes que demoran en llegar	Límite de velocidad de WhatsApp	Normal en envíos masivos; los mensajes llegan en minutos

---

Preguntas frecuentes

¿Puedo enviar mensajes de texto (no solo PDFs)?
Actualmente Sonata envía el PDF con un mensaje de texto predefinido. Mensajes libres de texto están en el plan de mejoras.

¿Hay límite de mensajes por día?
WhatsApp Business tiene límites por nivel de verificación de la cuenta de negocios. Para volúmenes altos (miles de mensajes/día), considera usar la API Oficial de Meta.

¿Funciona con un número personal (no Business)?
Técnicamente sí con Evolution API, pero WhatsApp puede suspender números personales usados para envíos masivos. Usa siempre un número de WhatsApp Business.

¿Qué pasa si el cliente tiene el número en lista negra (bloqueó la empresa)?
El mensaje no se entrega y Evolution API devuelve un error. El sistema lo registra en el log.