Ir al contenido

Enviar WhatsApp desde Laravel y PHP ​

ZAPPIO es una API HTTP + JSON: en Laravel basta el cliente Http que ya trae el framework. Envías el mensaje con una petición y recibes las respuestas de tus clientes por webhook en una ruta de tu aplicación.

Antes de empezar necesitas una cuenta, una instancia conectada y una API key: sigue el Quickstart (pasos 1 a 7). Guarda los valores en tu .env:

dotenv
ZAPPIO_API_URL=https://zappio.cloud
ZAPPIO_API_KEY=zp_...
ZAPPIO_INSTANCE=ins_...
ZAPPIO_WEBHOOK_SECRET=zpwh_...
php
// config/services.php
'zappio' => [
    'url' => env('ZAPPIO_API_URL'),
    'key' => env('ZAPPIO_API_KEY'),
    'instance' => env('ZAPPIO_INSTANCE'),
    'webhook_secret' => env('ZAPPIO_WEBHOOK_SECRET'),
],

Enviar un mensaje ​

php
<?php

namespace App\Support;

use Illuminate\Support\Facades\Http;

class Zappio
{
    /** Queues a WhatsApp text and returns the message (id msg_..., status "queued"). */
    public static function send(string $to, string $text, ?string $idempotencyKey = null): array
    {
        $response = Http::withToken(config('services.zappio.key'))
            ->withHeaders(array_filter(['Idempotency-Key' => $idempotencyKey]))
            ->post(config('services.zappio.url').'/api/v1/messages', [
                'instance' => config('services.zappio.instance'),
                'to' => $to,
                'type' => 'text',
                'text' => $text,
            ]);

        $response->throw(); // 4xx/5xx: el cuerpo trae error.code y error.message

        return $response->json('data');
    }
}
php
use App\Support\Zappio;

$message = Zappio::send('5215500000000', 'Hola desde Laravel 👋', 'saludo-1');
// $message['id'] => "msg_...", $message['status'] => "queued"
  • to es el número con código de país (en México, 52 y el número; los espacios y el + se ignoran).
  • La API responde 202 Accepted: el mensaje queda en cola y sale en segundo plano. Si lo envías desde un job de la cola de Laravel, usa Idempotency-Key para que un reintento del job no lo mande dos veces (Idempotencia).
  • Los códigos de error están en Errores.

Recibir respuestas por webhook ​

Registra en el panel un webhook con la URL de tu ruta y el evento message.received. Cada petición viene firmada; la función de verificación (sin dependencias, probada contra el vector de prueba):

php
<?php

/**
 * Verifies a ZAPPIO webhook. Pass the RAW request body (the exact bytes received), the X-Zappio-Timestamp header and the
 * X-Zappio-Signature header. No dependencies.
 */
function verifyZappioWebhook(string $secret, string $timestamp, string $signatureHeader, string $rawBody, ?int $now = null, int $tolerance = 300): bool
{
    // Reject stale or future timestamps: a captured request cannot be replayed later.
    if (! ctype_digit($timestamp) || abs(($now ?? time()) - (int) $timestamp) > $tolerance) {
        return false;
    }

    $expected = 'v1='.hash_hmac('sha256', $timestamp.'.'.$rawBody, $secret);

    return hash_equals($expected, $signatureHeader); // constant-time comparison
}

// --- Self-check against the shared test vector: php verify-webhook.php webhook-signature-vector.json
if (PHP_SAPI === 'cli' && isset($argv[1]) && realpath($_SERVER['SCRIPT_FILENAME']) === __FILE__) {
    $vector = json_decode((string) file_get_contents($argv[1]), true, flags: JSON_THROW_ON_ERROR);
    $failed = 0;
    foreach ($vector['cases'] as $case) {
        $ok = verifyZappioWebhook($case['secret'], $case['timestamp'], $case['signature'], $case['body'], $case['now'], $vector['tolerance_seconds']);
        if ($ok !== $case['valid']) {
            fwrite(STDERR, "FAIL php: {$case['name']}\n");
            $failed++;
        }
    }
    echo $failed === 0 ? 'php: '.count($vector['cases'])." cases OK\n" : '';
    exit($failed === 0 ? 0 : 1);
}

Guárdala, por ejemplo, en app/Support/verify-webhook.php y cárgala desde composer.json ("autoload": { "files": ["app/Support/verify-webhook.php"] }, luego composer dump-autoload).

La ruta va en routes/api.php, así no le aplica la protección CSRF de los formularios:

php
// routes/api.php
use App\Support\Zappio;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::post('/webhooks/zappio', function (Request $request) {
    $valid = verifyZappioWebhook(
        (string) config('services.zappio.webhook_secret'),
        (string) $request->header('X-Zappio-Timestamp'),
        (string) $request->header('X-Zappio-Signature'),
        $request->getContent(), // el cuerpo crudo, tal como llegó
    );
    abort_unless($valid, 401);

    $event = $request->json()->all();
    if ($event['type'] === 'message.received') {
        $message = $event['data']['message'];
        if ($message['group_id'] === null && $message['type'] === 'text') {
            dispatch(fn () => Zappio::send($message['from'], 'Recibimos tu mensaje, te respondemos pronto.'));
        }
    }

    return response()->noContent(); // 204: responde rápido, el envío va en la cola
});
  • Responde un 2xx en menos de 10 segundos; lo pesado, en un job (reintentos y duplicados).
  • Un mismo evento puede llegar más de una vez: deduplica por $event['id'].

Sin Laravel (PHP puro) ​

php
<?php
$ch = curl_init(getenv('ZAPPIO_API_URL').'/api/v1/messages');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer '.getenv('ZAPPIO_API_KEY'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'instance' => getenv('ZAPPIO_INSTANCE'),
        'to' => '5215500000000',
        'type' => 'text',
        'text' => 'Hola desde PHP 👋',
    ]),
]);
$body = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), ' ', $body['data']['id'] ?? $body['error']['code'], PHP_EOL;

Siguientes pasos ​

Pruébalo gratis

Crea tu cuenta: 50 mensajes de prueba, sin tarjeta y sin límite de días.