Raphael Serafim· Publicado el 10 de septiembre de 2026· 9 min de lectura

SDK de PHP para WhatsApp, Instagram y Messenger: los tres canales en 15 líneas

El SDK oficial de PHP de WAME envía mensajes en WhatsApp, Instagram y Messenger con la misma llamada — solo cambia el provider. Instalación con Composer, envío de texto y archivos, y el parser de webhook que ya viene listo.

Ver como Markdown

PHP mueve buena parte de los sistemas de gestión hechos en América Latina. ERP, sistema de clínica, control de taller, portal inmobiliario — mucho de lo que funciona y factura está escrito en PHP. Y el cliente de esos sistemas quiere WhatsApp adentro.

Esta guía va desde cero hasta recibir mensajes, con los tres canales.

Instalación

composer require raphaelvserafim/client-php-api-wa-me

<?php
require 'vendor/autoload.php';

use Api\Wame\Wame;

$wa = new Wame([
    'server' => 'https://server.api-wa.me',
    'key'    => 'YOUR_INSTANCE_KEY',
]);

La key sale del panel al crear la instancia. Guárdala en el .env como cualquier credencial — nunca en el código versionado.

El primer mensaje

$to = "525512345678";   // internacional, solo dígitos

$result = $wa->message->sendText($to, "Tu pedido #1042 salió para entrega 🚚");

if ($result) {
    $data = json_decode($result);
    echo "¡Enviado! ID: " . $data->data->key->id;
} else {
    echo "Falló el envío.";
}

Esas son las 15 líneas del título, composer require incluido.

Guarda el key->id que devuelve: es el que aparece en el webhook de estado de entrega, y es por él que unes "envié" con "se entregó".

Los tres canales, la misma llamada

Aquí está la diferencia que suele decidir la elección del proveedor. El provider puede valer para todo el cliente:

use Api\Wame\Provider;

$wa = new Wame([
    'server'   => 'https://server.api-wa.me',
    'key'      => 'YOUR_INSTANCE_KEY',
    'provider' => Provider::INSTAGRAM,
]);

$wa->message->sendText('IG_USER_ID', '¡Hola! Vi que comentaste en la publicación.');

O por mensaje:

$wa->message->sendText('525512345678', 'Hola', Provider::WHATSAPP);
$wa->message->sendText('IG_USER_ID',   'Hola', Provider::INSTAGRAM);
$wa->message->sendText('PSID',         'Hola', Provider::MESSENGER);

Mismo método, misma firma, mismo manejo de errores. No son tres integraciones: es una instancia cubriendo los tres canales.

Más allá del texto

// Imagen por URL pública
$wa->message->sendImage($to, 'https://ejemplo.com/factura.jpg', 'Tu factura');

// Documento
$wa->message->sendDocument($to, 'https://ejemplo.com/recibo.pdf', 'recibo-octubre.pdf');

// Audio
$wa->message->sendAudio($to, 'https://ejemplo.com/audio.mp3');

Para botones y menús de lista, cómo enviar mensajes por la API tiene los formatos completos.

Recibir: configurar el webhook

$wa->instance->updateWebhook([
    'allowWebhook'   => true,
    'allowNumber'    => 'all',
    'webhookFormat'  => 'meta',
    'webhookMessage' => 'https://tusistema.com/webhook/wame',
]);

El webhookFormat => 'meta' importa: es lo que hace que los eventos lleguen en el sobre estándar de la Cloud API, el mismo para los tres canales.

Recibir: el parser incluido

Sin SDK tendrías que navegar el JSON anidado a mano y escribir las guardas que le faltan a la primera versión de todo el mundo. El SDK ya lo hace:

<?php
require 'vendor/autoload.php';

use Api\Wame\Wame;

// Responde 200 ANTES de procesar. Un webhook que tarda se reenvía,
// y el cliente recibe la misma respuesta dos o tres veces.
http_response_code(200);
header('Content-Type: application/json');
echo '{"ok":true}';

if (function_exists('fastcgi_finish_request')) {
    fastcgi_finish_request();   // devuelve al cliente y sigue procesando
}

$payload = json_decode(file_get_contents('php://input'), true);
$msg = Wame::parseMeta($payload);

// Los estados de entrega también caen aquí. Sin esta guarda,
// el sistema termina respondiéndose a sí mismo.
if (!$msg || $msg['type'] !== 'text') {
    exit;
}

registrarEnSistema([
    'canal'     => $msg['provider'],   // whatsapp | instagram | messenger
    'de'        => $msg['from'],
    'texto'     => $msg['text'],
    'messageId' => $msg['id'],
]);

El fastcgi_finish_request() es el detalle que separa a quien ya se golpeó de quien se va a golpear: en PHP-FPM devuelve la respuesta HTTP y sigue ejecutando en segundo plano. Sin eso, el webhook queda abierto durante todo el procesamiento y la plataforma reenvía por timeout.

En Laravel

Nada especial — es un paquete Composer:

// config/wame.php
return [
    'server' => env('WAME_SERVER', 'https://server.api-wa.me'),
    'key'    => env('WAME_KEY'),
];

// AppServiceProvider::register()
$this->app->singleton(Wame::class, fn () => new Wame([
    'server' => config('wame.server'),
    'key'    => config('wame.key'),
]));

Y el webhook como una ruta normal, con el procesamiento en un Job para responder rápido:

Route::post('/webhook/wame/{secreto}', function (Request $req, string $secreto) {
    abort_unless(hash_equals(config('wame.webhook_secret'), $secreto), 404);

    ProcesarMensajeWame::dispatch($req->all());
    return response()->json(['ok' => true]);   // 200 ya; el Job procesa después
});

El secreto en la ruta es la protección mínima: sin él, cualquiera que descubra la URL puede publicar eventos falsos.

Cuando el SDK no es el camino

Si tu sistema es PHP heredado sin Composer, o solo necesitas un envío puntual, la API REST resuelve con curl puro:

$ch = curl_init("https://us.api-wa.me/TU_KEY/message/text");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode(['to' => $to, 'text' => '¡Hola!']),
]);
$res = curl_exec($ch);

La misma API por detrás. El SDK ahorra el boilerplate y el parser; no es obligatorio.

Conclusión

Poner WhatsApp en un sistema PHP es composer require más 15 líneas. Lo que antes era un proyecto —app en Meta, verificación de negocio, tres integraciones para tres canales— ya no está en el camino.

Si trabajas en Node, el SDK de JavaScript y TypeScript cubre el mismo terreno con tipado completo.

La referencia completa está en docs/sdk/php.

¿Listo para automatizar tu WhatsApp?

Crea tu cuenta gratis y empieza a enviar mensajes por la API en minutos.

Empezar gratis

Preguntas frecuentes

¿Cómo instalo el SDK de PHP de WAME?+

Con Composer: composer require raphaelvserafim/client-php-api-wa-me. Después basta con instanciar la clase Wame indicando el servidor y la key de la instancia. No depende de ninguna extensión exótica y funciona en cualquier PHP moderno, con o sin framework.

¿El SDK de PHP funciona con Laravel?+

Sí. Es un paquete Composer común, sin service provider obligatorio. Puedes instanciarlo donde lo necesites o registrarlo como singleton en el contenedor, guardando la key en el config y el .env como cualquier otra credencial.

¿Puedo enviar a Instagram y Messenger con el mismo SDK?+

Sí, y con el mismo método. El provider se define una vez al crear el cliente, valiendo para todas las llamadas, o se pasa por mensaje como último argumento. El código de envío es idéntico en los tres canales.

¿Cómo recibo mensajes en PHP?+

Configura el webhook de la instancia con webhookFormat en 'meta' y apúntalo a un endpoint tuyo. El SDK trae el parser parseMeta(), que lee el sobre de la Cloud API y devuelve los campos ya extraídos, sin navegar el JSON anidado a mano.

¿Necesito un servidor propio?+

Para enviar, no: cualquier script PHP con acceso a internet basta, incluso un hosting compartido. Para recibir mensajes sí necesitas una URL pública con HTTPS, porque el webhook es una petición que llega desde afuera hasta tu código.