Raphael Serafim· Publicado em 10 de setembro de 2026· 9 min de leitura

SDK PHP para WhatsApp, Instagram e Messenger: os três canais em 15 linhas

O SDK PHP oficial da WAME manda mensagem no WhatsApp, Instagram e Messenger com a mesma chamada — só muda o provider. Instalação via Composer, envio de texto, mídia, botões e listas, e o parser de webhook que já vem pronto.

Ver como Markdown

PHP move a maior parte dos sistemas de gestão feitos no Brasil. ERP, sistema de clínica, controle de oficina, portal de imobiliária — muita coisa que roda bem e fatura bem é PHP. E o cliente desses sistemas quer WhatsApp dentro deles.

Este guia mostra o SDK PHP da WAME do zero até receber mensagem, com os três canais.

Instalação

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',
]);

A chave sai do portal ao criar a instância. Guarde no .env como qualquer credencial — nunca no código versionado.

Enviar a primeira mensagem

$to = "5566996852025";   // internacional, só dígitos

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

if ($result) {
    $data = json_decode($result);
    echo "Enviada! ID: " . $data->data->key->id;
} else {
    echo "Falha no envio.";
}

São as 15 linhas do título, composer require incluído.

Guarde o key->id retornado: é ele que aparece no webhook de status de entrega, e é por ele que você amarra "mandei" com "foi entregue".

Os três canais, a mesma chamada

Aqui está a diferença que costuma decidir a escolha do fornecedor. O provider pode valer para o client inteiro:

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', 'Oi! Vi que você comentou no post.');

Ou por mensagem:

$wa->message->sendText('5511999999999', 'Oi', Provider::WHATSAPP);
$wa->message->sendText('IG_USER_ID',    'Oi', Provider::INSTAGRAM);
$wa->message->sendText('PSID_MESSENGER','Oi', Provider::MESSENGER);

Mesmo método, mesma assinatura, mesmo tratamento de erro. Não são três integrações — é uma instância cobrindo os três canais.

Além do texto

// Imagem por URL pública
$wa->message->sendImage($to, 'https://exemplo.com/nota-fiscal.jpg', 'Sua NF-e');

// Documento
$wa->message->sendDocument($to, 'https://exemplo.com/boleto.pdf', 'boleto-outubro.pdf');

// Áudio
$wa->message->sendAudio($to, 'https://exemplo.com/audio.mp3');

Para botões e menus de lista, o guia de envio pela API tem os formatos completos — os endpoints são os mesmos que o SDK encapsula.

Receber: configurar o webhook

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

O webhookFormat => 'meta' importa: é ele que faz os eventos chegarem no envelope padrão da Cloud API, o mesmo para os três canais.

Receber: o parser pronto

Sem SDK, você navegaria o JSON aninhado na mão e escreveria as guardas que faltam na primeira versão de todo mundo. O SDK já faz:

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

use Api\Wame\Wame;

// Responda 200 ANTES de processar. Webhook que demora é reenviado,
// e o cliente recebe a mesma resposta duas ou três vezes.
http_response_code(200);
header('Content-Type: application/json');
echo '{"ok":true}';

if (function_exists('fastcgi_finish_request')) {
    fastcgi_finish_request();   // devolve ao cliente e segue processando
}

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

// Status de entrega também cai aqui. Sem esta guarda,
// o sistema responde a si mesmo.
if (!$msg || $msg['type'] !== 'text') {
    exit;
}

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

O fastcgi_finish_request() é o detalhe que separa quem já apanhou de quem vai apanhar: em PHP-FPM ele devolve a resposta HTTP e continua a execução em segundo plano. Sem isso, o webhook fica aberto durante todo o processamento e a plataforma reenvia por timeout.

Em Laravel

Nada de especial — é um pacote 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'),
]));

E o webhook como rota normal, com o processamento numa Job para responder rápido:

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

    ProcessarMensagemWame::dispatch($req->all());
    return response()->json(['ok' => true]);   // 200 na hora; a Job processa depois
});

O segredo no caminho da URL é o mínimo de proteção: sem ele, qualquer um que descubra o endereço posta evento forjado. As camadas seguintes estão em webhook em produção.

Quando o SDK não é o caminho

Se o seu sistema é PHP legado sem Composer, ou se você só precisa de um envio pontual, a API REST resolve com curl puro:

$ch = curl_init("https://us.api-wa.me/SUA_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' => 'Olá!']),
]);
$res = curl_exec($ch);

Mesma API por trás. O SDK poupa o boilerplate e o parser; ele não é obrigatório.

Conclusão

Colocar WhatsApp num sistema PHP é composer require mais 15 linhas. O que costumava ser projeto — app na Meta, verificação de negócio, três integrações para três canais — não está mais no caminho.

Se você trabalha em Node, o SDK JavaScript e TypeScript tem a mesma cobertura com tipagem completa. E se você entrega esse módulo para vários clientes, vale ver como provisionar instância por API — o mesmo SDK cria e desativa conta sem ninguém abrir painel.

A referência completa está em docs/sdk/php.

Pronto para automatizar seu WhatsApp?

Crie sua conta gratuita e comece a enviar mensagens pela API em minutos.

Começar grátis

Perguntas frequentes

Como instalar o SDK PHP da WAME?+

Via Composer: composer require raphaelvserafim/client-php-api-wa-me. Depois basta instanciar a classe Wame com o servidor e a chave da instância. Não há dependência de extensão exótica — funciona em qualquer PHP moderno, com ou sem framework.

O SDK PHP funciona com Laravel?+

Sim. É um pacote Composer comum, sem service provider obrigatório. Você pode instanciar direto onde precisar ou registrar como singleton no container, guardando a chave da instância no config e no .env como qualquer outra credencial.

Dá para enviar no Instagram e no Messenger com o mesmo SDK?+

Sim, e com o mesmo método. O provider pode ser definido uma vez ao criar o client, valendo para todas as chamadas, ou passado por mensagem como último argumento. O código de envio é idêntico nos três canais.

Como receber mensagens em PHP?+

Configure o webhook da instância com webhookFormat 'meta' e aponte para um endpoint seu. O SDK traz o parser parseMeta() que lê o envelope da Cloud API e devolve os campos já extraídos, então você não precisa navegar no JSON aninhado à mão.

Preciso de servidor próprio para usar o SDK PHP?+

Para enviar, não: qualquer script PHP com acesso à internet basta, inclusive uma hospedagem compartilhada. Para receber mensagens você precisa de uma URL pública em HTTPS, porque o webhook é uma requisição que chega de fora até o seu código.