🚀 Instalación Completa

Esta guía te llevará paso a paso en la instalación y configuración del paquete WhatsApp API Manager para Laravel.

📋 Requisitos Previos

Antes de instalar el paquete, necesitarás:

• PHP 8.2 o superior
• Laravel 12 o superior
• Una cuenta de WhatsApp Business API Cloud

🔧 Pasos de Instalación

1. Instalar el Paquete

Instala el paquete a través de Composer:

composer require scriptdevelop/whatsapp-manager

2. Publicar Archivos de Configuración

Este comando publicará los archivos de configuración base del paquete:

php artisan vendor:publish --tag=whatsapp-config

Esto creará:

• config/whatsapp.php - Configuración principal del paquete
• Actualizaciones en config/logging.php - Canal de logs para WhatsApp

3. Configurar Canal de Logging

Añade el canal de WhatsApp en tu archivo config/logging.php:

'channels' => [
    // ... otros canales

    'whatsapp' => [
        'driver' => 'daily',
        'path' => storage_path('logs/whatsapp.log'),
        'level' => 'debug',
        'days' => 7,
        'tap' => [\ScriptDevelop\WhatsappManager\Logging\CustomizeFormatter::class],
    ],
],

4. Publicar Migraciones (Opcional)

Las migraciones se ejecutarán automáticamente con php artisan migrate. Si deseas personalizarlas, publícalas primero:

php artisan vendor:publish --tag=whatsapp-migrations

5. Publicar Rutas del Webhook

Este paso es obligatorio para recibir notificaciones de mensajes entrantes:

php artisan vendor:publish --tag=whatsapp-routes

6. Excluir Webhook de CSRF

Añade la ruta del webhook a las excepciones de CSRF en bootstrap/app.php:

->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: [
        '/whatsapp-webhook',
    ]);
})

7. Configurar Variables de Entorno

Añade estas variables a tu archivo .env:

# Configuración de WhatsApp API
WHATSAPP_API_URL=https://graph.facebook.com
WHATSAPP_API_VERSION=v21.0
WHATSAPP_VERIFY_TOKEN=your-verify-token
WHATSAPP_USER_MODEL=App\Models\User
WHATSAPP_BROADCAST_CHANNEL_TYPE=private

# Variables opcionales para OAuth
META_CLIENT_ID=123456789012345
META_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
META_REDIRECT_URI=https://tudominio.com/meta/callback
META_SCOPES=whatsapp_business_management,whatsapp_business_messaging

🗃️ Configuración de Base de Datos

1. Ejecutar Migraciones

Ejecuta las migraciones para crear las tablas necesarias:

php artisan migrate

Esto creará las siguientes tablas:

• whatsapp_phones - Números de teléfono de WhatsApp Business
• whatsapp_contacts - Contactos
• whatsapp_messages - Mensajes enviados y recibidos
• whatsapp_templates - Plantillas de mensajes
• Y más...

2. Poblar Tabla de Idiomas

Los seeders son necesarios para trabajar con plantillas de WhatsApp:

# Publicar seeders
php artisan vendor:publish --tag=whatsapp-seeders

# Ejecutar seeder de idiomas
php artisan db:seed --class=WhatsappTemplateLanguageSeeder

📁 Configuración de Archivos Multimedia

1. Estructura de Directorios

El paquete necesita una estructura de carpetas para almacenar archivos multimedia:

storage/app/public/whatsapp/
├── audios/
├── documents/
├── images/
├── stickers/
└── videos/

2. Crear Estructura Automáticamente (Recomendado)

Publica la estructura de medios con un solo comando:

php artisan vendor:publish --tag=whatsapp-media

3. Crear Enlace Simbólico

Para que los archivos sean accesibles públicamente:

php artisan storage:link

🔗 Configuración de Webhooks en Meta

Para recibir mensajes entrantes, configura el webhook en Meta Developers:

Pasos en Meta for Developers

1. Accede a Meta for Developers
2. Selecciona tu aplicación de WhatsApp
3. Navega a Productos > WhatsApp > Configuración
4. En la sección Webhooks, configura:

🛠️ Desarrollo Local con ngrok

Para probar el webhook en tu entorno local, usa ngrok:

1. Descargar e Instalar ngrok

Descarga ngrok desde ngrok.com

2. Iniciar el Servidor Local

php artisan serve

3. Exponer el Servidor con ngrok

# Opción 1: Simple
ngrok http 8000

# Opción 2: Con reescritura de host (recomendado)
ngrok http --host-header=rewrite 8000

4. Usar la URL de ngrok

ngrok te proporcionará una URL como:

https://xxxxxx.ngrok.io

Usa esta URL en Meta como tu webhook:

https://xxxxxx.ngrok.io/whatsapp-webhook

🔍 Validación Final

Después de completar la instalación, verifica:

• [ ] Las rutas del webhook están publicadas y accesibles
• [ ] El token de verificación coincide en .env y Meta
• [ ] Los directorios multimedia tienen permisos de escritura
• [ ] El enlace simbólico de storage funciona correctamente
• [ ] Los eventos seleccionados en Meta cubren tus necesidades
• [ ] El canal de logging está configurado

Prueba Rápida

Envía un mensaje de prueba a tu número de WhatsApp Business y verifica que aparece en los logs:

tail -f storage/logs/whatsapp.log

🚨 Solución de Problemas

Error: "Route not found"

Asegúrate de haber publicado las rutas:

php artisan vendor:publish --tag=whatsapp-routes
php artisan route:list | grep whatsapp

Error: "Directory not writable"

Verifica los permisos de las carpetas de almacenamiento:

chmod -R 775 storage/app/public/whatsapp

Webhook no recibe mensajes

1. Verifica que el webhook esté correctamente configurado en Meta
2. Revisa los logs: storage/logs/whatsapp.log
3. Verifica que la URL sea accesible públicamente
4. Confirma que el token de verificación sea correcto

📚 Próximos Pasos

Una vez completada la instalación, continúa con:

• Configuración de API - Configura tus credenciales de Meta
• Envío de Mensajes - Comienza a enviar mensajes
• Webhook - Aprende sobre el manejo de webhooks

¿Necesitas ayuda? Consulta nuestro GitHub o abre un issue.