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

  1. Abra Fluxos. Cada fluxo de integração é um número.
  2. Na aba Canais, conecte o WhatsApp pelo login da Meta.
  3. 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.

VARIÁVEL DE AMBIENTE
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:

NODE.JS
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
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.