Guia
Como começar a integrar
Do cadastro à primeira mensagem enviada pelo seu sistema. Para a lista completa de rotas e eventos, veja a referência da API.
1Conecte o número
- Abra Fluxos. Cada fluxo de integração é um número.
- Na aba Canais, conecte o WhatsApp pelo login da Meta.
- Se o número for de um cliente seu, gere o link de conexão e envie a ele: quem conecta precisa ser dono da conta da Meta.
Já atende por um fluxo padrão da Ruvz? Abra o fluxo, vá na aba Integração e ligue Acesso por API. O atendimento continua como está; veja o que muda em Fluxo padrão com Acesso por API.
2Crie o token
Em Configurações, na aba API, crie um token e escolha os fluxos que ele alcança. O valor aparece uma única vez: guarde no seu cofre de segredos. Se perder, revogue e crie outro.
export RUVZ_TOKEN="rvz_live_..."3Configure o webhook
Abra o fluxo, vá até a aba Integração, informe a URL do seu sistema e salve. A chave de assinatura aparece uma única vez. O botão Testar webhook envia um evento de exemplo e mostra a resposta do seu servidor.
Valide a assinatura em toda entrega, usando o corpo cru da requisição:
const crypto = require("crypto");
function verifyRuvz(rawBody, headers, secret) {
const ts = Number(headers["x-ruvz-timestamp"]);
if (!ts || Math.abs(Date.now() / 1000 - ts) > 300) return false;
const expected =
"sha256=" +
crypto
.createHmac("sha256", secret)
.update(ts + ".")
.update(rawBody)
.digest("hex");
const got = headers["x-ruvz-signature-256"] || "";
const a = Buffer.from(expected);
const b = Buffer.from(got);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}4Envie a primeira mensagem
Peça para alguém mandar uma mensagem para o número conectado. O evento message.received chega no seu webhook e abre a janela de 24 horas. Responda:
curl -X POST https://api.ruvz.com.br/v1/messages \
-H "Authorization: Bearer $RUVZ_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 4f3c2b1a-..." \
-d '{
"from": "5511988880000",
"to": "5511999990000",
"text": "Recebemos sua mensagem."
}'A resposta pending significa que a mensagem foi aceita e está na fila. A entrega é confirmada pelo evento message.status.
5Fora da janela de 24 horas
Sem mensagem recente do cliente, a Meta só aceita modelos aprovados. Consulte os seus em GET /v1/templates e envie pelo mesmo POST /v1/messages, como descrito na referência.