WhatsApp Manager
🇪🇸 Español 🇬🇧 English

🚀 Primeros Pasos

⚙️ Configuración

💬 Gestión de Mensajes

📋 Plantillas

📡 Eventos en Tiempo Real

🔧 Avanzado

Inicio Inicio Rápido

Inicio Rápido

Envía tu primer mensaje de WhatsApp en menos de 5 minutos.

Prerequisitos

Asegúrate de haber completado la instalación del paquete.

1. Configurar Credenciales

Obtén tus credenciales de la consola de Meta for Developers:

# .env
WHATSAPP_API_URL=https://graph.facebook.com
WHATSAPP_API_VERSION=v21.0
WHATSAPP_VERIFY_TOKEN=tu-token-de-verificacion

2. Registrar un Número de WhatsApp

  • Registra una cuenta de negocios en WhatsApp Business API.
    Registra y sincroniza cuentas empresariales de WhatsApp con sus números de teléfono asociados.
    • Se hace la peticion a la API de whatsapp, se obtienen los datos de la cuenta y se almacenan en la base de datos. Este metodo obtiene los datos de la cuenta, los telefonos de whatsapp asociados a la cuenta y el perfil de cada numero de telefono.
    • Se usa para Obtener los datos desde la API y alojarlos en la base de datos.

⚠️Observations:

  • Requiere un token de acceso válido con los permisos whatsapp_business_management.
  • El business_id debe ser el ID numérico de tu cuenta empresarial de WhatsApp.
use ScriptDevelop\WhatsappManager\Facades\Whatsapp;

// Al registrar una cuenta, automáticamente se suscriben los webhooks configurados
$account = Whatsapp::account()->register([
    'api_token' => '***********************',
    'business_id' => '1243432234423'
]);

// Durante el registro también se:
// - Registran automáticamente todos los números de teléfono asociados
// - Suscriben los webhooks configurados por defecto
// - Configuran los perfiles de negocio

3. Enviar tu Primer Mensaje

Mensaje de Texto Simple

use ScriptDevelop\WhatsappManager\Facades\Whatsapp;
use ScriptDevelop\WhatsappManager\Models\WhatsappBusinessAccount;

$account = WhatsappBusinessAccount::first();
$phone = $account->phoneNumbers->first();

$response = Whatsapp::message()->sendTextMessage(
    $phone->phone_number_id, // ID del número de teléfono
    '57',                        // Código de país
    '3237121901',                // Número de teléfono
    'Hola, este es un mensaje de prueba.' // Contenido del mensaje
);

Mensaje con Imagen

Enviar mensajes con Imágenes

⚠️ Advertencia: Asegúrate de que la imagen que envíes cumpla con los requisitos de WhatsApp:

  • Formato soportado: JPEG, PNG
  • Tamaño máximo recomendado: 5 MB
  • Dimensiones recomendadas: al menos 640x640 px
    Si la imagen no cumple con estos requisitos, el envío puede fallar.
use ScriptDevelop\WhatsappManager\Facades\Whatsapp;
use ScriptDevelop\WhatsappManager\Models\WhatsappBusinessAccount;

$account = WhatsappBusinessAccount::first();
$phone = $account->phoneNumbers->first();

$filePath = storage_path('app/public/laravel-whatsapp-manager.png');
$file = new \SplFileInfo($filePath);

$message = Whatsapp::message()->sendImageMessage(
    $phone->phone_number_id, // ID del número de teléfono
    '57',                        // Código de país
    '3237121901',                // Número de teléfono
    $file                       // Archivo de imagen.
);

Mensaje con Botones

Enviar mensajes con botones interactivos:

use ScriptDevelop\WhatsappManager\Facades\Whatsapp;
use ScriptDevelop\WhatsappManager\Models\WhatsappBusinessAccount;

$account = WhatsappBusinessAccount::first();
$phone = $account->phoneNumbers->first();

//EJEMPLO 1
$buttonResponse = Whatsapp::sendButtonMessage($phone->phone_number_id)
    ->to('57', '31371235638')
    ->withBody('¿Confirmas tu cita para mañana a las 3 PM?')
    ->addButton('confirmar', '✅ Confirmar')
    ->addButton('reagendar', '🔄 Reagendar')
    ->withFooter('Por favor selecciona una opción')
    ->send();

//EJEMPLO 2
$buttonResponse = Whatsapp::sendButtonMessage($phone->phone_number_id)
    ->to('57', '31371235638')
    ->withBody('¿Cómo calificarías nuestro servicio?')
    ->addButton('excelente', '⭐️⭐️⭐️⭐️⭐️ Excelente')
    ->addButton('bueno', '⭐️⭐️⭐️⭐️ Bueno')
    ->addButton('regular', '⭐️⭐️⭐️ Regular')
    ->withFooter('Tu opinión nos ayuda a mejorar')
    ->send();

//EJEMPLO 3
// Obtener ID de un mensaje anterior (debes tener uno real)
$contextMessage = \ScriptDevelop\WhatsappManager\Models\Message::first();
$contextId = $contextMessage->wa_id;

$buttonResponse = Whatsapp::sendButtonMessage($phone->phone_number_id)
    ->to('57', '31371235638')
    ->withBody('Selecciona el tipo de soporte que necesitas:')
    ->addButton('soporte-tecnico', '🛠️ Soporte Técnico')
    ->addButton('facturacion', '🧾 Facturación')
    ->addButton('quejas', '📣 Quejas y Reclamos')
    ->withFooter('Horario de atención: L-V 8am-6pm')
    ->inReplyTo($contextId)  // Aquí especificas el mensaje al que respondes
    ->send();

// EJEMPLOS CON HEADER texto
$buttonResponse = Whatsapp::sendButtonMessage($phone->phone_number_id)
    ->to('57', '313714R3534')
    ->withHeader('Catálogo Digital')
    ->withBody('¿Confirmas tu cita para mañana a las 3 PM?')
    ->addButton('confirmar', '✅ Confirmar')
    ->addButton('reagendar', '🔄 Reagendar')
    ->withFooter('Por favor selecciona una opción')
    ->send();

// EJEMPLOS CON HEADER imagen
$file = new \SplFileInfo(storage_path('app/public/laravel-whatsapp-manager.png'));

$buttonResponse = Whatsapp::sendButtonMessage($phone->phone_number_id)
    ->to('57', '313714R3534')
    ->withHeader($file)
    ->withBody('¿Confirmas tu cita para mañana a las 3 PM?')
    ->addButton('confirmar', '✅ Confirmar')
    ->addButton('reagendar', '🔄 Reagendar')
    ->withFooter('Por favor selecciona una opción')
    ->send();

4. Recibir Mensajes

Configurar el Webhook

Primero, configura tu webhook en Meta for Developers siguiendo la guía de instalación.

Escuchar Eventos

Crea un listener para mensajes entrantes:

// app/Listeners/HandleIncomingMessage.php
namespace App\Listeners;

use ScriptDevelop\WhatsappManager\Events\TextMessageReceived;
use Illuminate\Contracts\Queue\ShouldQueue;

class HandleIncomingMessage implements ShouldQueue
{
    public function handle(TextMessageReceived $event)
    {
        $message = $event->message;
        $contact = $event->contact;

        logger()->info("Mensaje de {$contact->name}: {$message->body}");

        // Tu lógica aquí
        // Por ejemplo, responder automáticamente:
        Whatsapp::sendTextMessage(
            phoneId: $message->whatsapp_phone_id,
            to: $contact->whatsapp_id,
            message: "¡Hola {$contact->name}! Recibimos tu mensaje: '{$message->body}'"
        );
    }
}

Registra el listener en app/Providers/EventServiceProvider.php:

use ScriptDevelop\WhatsappManager\Events\TextMessageReceived;
use App\Listeners\HandleIncomingMessage;

protected $listen = [
    TextMessageReceived::class => [
        HandleIncomingMessage::class,
    ],
];

5. Trabajar con Plantillas

Las plantillas son mensajes pre-aprobados por WhatsApp que puedes enviar a cualquier usuario:

// Enviar plantilla
use ScriptDevelop\WhatsappManager\Facades\Whatsapp;
use ScriptDevelop\WhatsappManager\Models\WhatsappBusinessAccount;

$account = WhatsappBusinessAccount::first();
$phone = $account->phoneNumbers->first();

// Enviar plantilla 1: plantilla sin botones o sin necesidad de proporcionar parámetros para botones
$message = Whatsapp::template()
    ->sendTemplateMessage($phone)
    ->to('57', '3137555908')
    ->usingTemplate('order_confirmation_4')
    ->addBody(['12345'])
    ->send();

Ejemplos Completos

Sistema de Respuestas con Listas

use ScriptDevelop\WhatsappManager\Facades\Whatsapp;
use ScriptDevelop\WhatsappManager\Models\WhatsappBusinessAccount;

$account = WhatsappBusinessAccount::first();
$phone = $account->phoneNumbers->first();

// EJEMLPO 1 - SIN ENCADENAR
$listBuilder = Whatsapp::sendListMessage($phone->phone_number_id)
    ->to('57', '31371235638')
    ->withButtonText('Ver Productos')
    ->withBody('Nuestros productos destacados:')
    ->withHeader('Catálogo Digital')
    ->withFooter('Desliza para ver más opciones');

$listBuilder->startSection('Laptops')
    ->addRow('laptop-pro', 'MacBook Pro', '16" - 32GB RAM - 1TB SSD')
    ->addRow('laptop-air', 'MacBook Air', '13" - M2 Chip - 8GB RAM')
    ->endSection();

$listBuilder->startSection('Smartphones')
    ->addRow('iphone-15', 'iPhone 15 Pro', 'Cámara 48MP - 5G')
    ->addRow('samsung-s23', 'Samsung S23', 'Pantalla AMOLED 120Hz')
    ->endSection();

$response = $listBuilder->send();

// EJEMLPO 2 - ENCADENADO
$listBuilder = Whatsapp::sendListMessage($phone->phone_number_id)
    ->to('57', '31371235638')
    ->withButtonText('Ver Servicios')
    ->withBody('Selecciona el servicio que deseas agendar:')
    ->withFooter('Desliza para ver todas las opciones')
    ->startSection('Cortes de Cabello')
        ->addRow('corte-mujer', 'Corte Mujer', 'Estilo profesional')
        ->addRow('corte-hombre', 'Corte Hombre', 'Técnicas modernas')
        ->addRow('corte-niños', 'Corte Niños', 'Diseños infantiles')
    ->endSection()
    ->startSection('Tratamientos')
        ->addRow('keratina', 'Keratina', 'Tratamiento reparador')
        ->addRow('coloracion', 'Coloración', 'Tintes profesionales')
        ->addRow('mascarilla', 'Mascarilla', 'Hidratación profunda')
    ->endSection();

$response = $listBuilder->send();

// EJEMLPO 3 - respuesta a mensajes o reply
// Obtener ID de un mensaje anterior (debes tener uno real)
$contextMessage = \ScriptDevelop\WhatsappManager\Models\Message::first();
$contextId = $contextMessage->wa_id;

$listBuilder = Whatsapp::sendListMessage($phone->phone_number_id)
    ->to('57', '31371235638')
    ->withButtonText('Seleccionar Servicio')
    ->withBody('Para el tipo de cita que mencionaste, tenemos estas opciones:')
    ->inReplyTo($contextId); // Aquí especificas el mensaje al que respondes

$listBuilder->startSection('Consultas')
    ->addRow('consulta-general', 'Consulta General', '30 min - $50.000')
    ->addRow('consulta-especial', 'Consulta Especializada', '60 min - $90.000')
    ->endSection();

$listBuilder->startSection('Tratamientos')
    ->addRow('tratamiento-basico', 'Tratamiento Básico', 'Sesión individual')
    ->addRow('tratamiento-premium', 'Tratamiento Premium', 'Incluye seguimiento')
    ->endSection();

$response = $listBuilder->send();

// EJEMPLO CON HEADER texto
$listBuilder = Whatsapp::sendListMessage($phone->phone_number_id)
    ->to('57', '313714R3534')
    ->withButtonText('Ver Productos')
    ->withHeader('Catálogo Digital') // HEADER DE TECTO
    ->withBody('Nuestros productos destacados:')
    ->withFooter('Desliza para ver más opciones')
    ->startSection('Laptops')
        ->addRow('laptop-pro', 'MacBook Pro', '16" - 32GB RAM - 1TB SSD')
        ->addRow('laptop-air', 'MacBook Air', '13" - M2 Chip - 8GB RAM')
    ->endSection()
    ->startSection('Smartphones')
        ->addRow('iphone-15', 'iPhone 15 Pro', 'Cámara 48MP - 5G')
        ->addRow('samsung-s23', 'Samsung S23', 'Pantalla AMOLED 120Hz')
    ->endSection()
    ->send();

Verificar el Estado del Mensaje

Todos los mensajes enviados se guardan en la base de datos:

use ScriptDevelop\WhatsappManager\Models\WhatsappMessage;

$message = WhatsappMessage::where('wa_id', 'wamid.xxxxx')->first();

echo "Estado: {$message->status}\n";
echo "Enviado a: {$message->message_to}\n";
echo "Tipo: {$message->message_type}\n";

Logs y Debugging

Todos los eventos se registran en storage/logs/whatsapp.log:

# Ver logs en tiempo real
tail -f storage/logs/whatsapp.log

Próximos Pasos

¡Felicitaciones! Ya enviaste tu primer mensaje. Ahora puedes:

Solución de Problemas

Error: "Invalid Phone Number"

Asegúrate de incluir el código de país sin el signo +:

// ❌ Incorrecto
to: '+5491234567890'

// ✅ Correcto
to: '5491234567890'

Error: "Invalid Access Token"

Verifica que el token esté activo y tenga los permisos necesarios en Meta for Developers.

No recibo mensajes

  1. Verifica que el webhook esté configurado correctamente
  2. Revisa los logs: storage/logs/whatsapp.log
  3. Confirma que los eventos estén suscritos en Meta

¿Necesitas más ayuda? Abre un issue en GitHub.

Compartir esta página

Editar esta página en GitHub