Apariencia
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"toes el número con código de país (en México,52y 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, usaIdempotency-Keypara 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
2xxen 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
- Multimedia: con
Http::attach()envías imágenes y documentos (ver enviar facturas). - Encuestas: recordatorios de citas con confirmación.
- Notificaciones de pedidos y bot de respuestas.
Pruébalo gratis
Crea tu cuenta: 50 mensajes de prueba, sin tarjeta y sin límite de días.