Pular para o conteúdo
apiwpp

Como agências gerenciam dezenas de números de WhatsApp

Projetos por cliente, chaves com escopo, webhooks separados e uma fatura só: como uma agência organiza dezenas de números de WhatsApp numa API.

Equipe apiwpp · 11 min de leitura · Atualizado em

Com dois ou três clientes, dá para cuidar do WhatsApp de cada um no improviso: uma planilha com os acessos, um servidor que recebe tudo, uma fatura aqui e outra ali. Com vinte clientes, o improviso vira risco. Uma chave de API compartilhada dá acesso a todos os números de uma vez, uma mensagem recebida vai parar no CRM errado e ninguém sabe dizer quanto custa, no fim do mês, o WhatsApp de cada cliente.

Este guia mostra como uma agência organiza dezenas de números numa API de WhatsApp sem misturar acessos, eventos e cobranças. Os exemplos usam a apiwpp, mas a lógica vale para qualquer operação com vários clientes: separar o que precisa ficar separado, juntar o que precisa ficar junto e acompanhar tudo de um lugar só.

O problema de vários clientes, vários números

Uma agência que coloca o WhatsApp nos processos dos clientes costuma esbarrar em três problemas ao mesmo tempo:

  • Acesso misturado. Se todos os números vivem sob a mesma chave, o sistema de um cliente consegue enviar pelo número de outro. Uma chave vazada compromete a carteira inteira.
  • Eventos misturados. Mensagens recebidas, confirmações de entrega e quedas de conexão de todos os clientes chegam no mesmo endpoint, e o seu código precisa adivinhar de quem é cada uma.
  • Cobrança espalhada. Quando cada cliente contrata a própria API, a agência passa a administrar logins, cartões e vencimentos diferentes. Quando tudo fica numa conta sem separação, fica difícil saber quanto cada cliente custa.

A saída é um modelo em três níveis, que é o que a apiwpp usa:

NívelO que representaO que fica nele
OrganizaçãoA agênciaA assinatura, a fatura e o acesso ao painel
ProjetoUm cliente (ou um sistema de um cliente)Chaves de API, endereço de webhook e segredo de assinatura
ConexãoUm número de WhatsAppSessão, fila de envio, aquecimento e proxy
A agência é a organização; cada cliente vira um projeto; cada número é uma conexão dentro do projeto.

Projetos não têm custo: uma organização pode ter até 20 no padrão. O que entra na conta é a quantidade de números conectados.

Um projeto por cliente

A regra mais simples, e a que dá menos trabalho depois, é um projeto por cliente. Se um cliente tem dois sistemas que não devem enxergar os eventos um do outro (o e-commerce e o sistema de cobrança, por exemplo), use um projeto para cada sistema.

Cada projeto nasce com o endereço que vai receber os webhooks dele. Os números você cria pela API, dentro do projeto, até a quantidade que a sua organização contratou. O passo a passo está no recurso de projetos e chaves de API.

Crie cada número com o identificador do cliente

Ao criar a conexão, informe o tenantId do projeto e um externalId: o código daquele cliente ou daquela unidade no seu sistema. Ele volta em todos os eventos do número, o que resolve o roteamento sem tabela de tradução.

curl -X POST https://api.apiwpp.com/connections \
  -H "Authorization: Bearer $APIWPP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tenantId":"'"$TENANT_ID"'","externalId":"padaria-central-loja-1"}'
{
  "connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
  "externalId": "padaria-central-loja-1"
}

Depois disso, o número é pareado como um aparelho conectado, por QR code ou por um código de pareamento de 8 caracteres digitado no celular do cliente. O guia de conexão por QR code cobre o fluxo completo, inclusive como mostrar o QR code dentro do seu próprio painel.

Se a organização já estiver usando todos os números contratados, a criação responde 402 com code: number_limit_reached. É o sinal para aumentar a quantidade de números antes de receber o cliente novo.

Chaves com escopo para cada peça do sistema

Cada chave de API pertence a um projeto e tem escopos. Em vez de uma chave "que faz tudo", dê a cada componente só o que ele precisa:

ComponenteEscopos
Sistema do cliente que envia avisosmessages:send
Painel interno que mostra o status dos númerosconnections:read
Rotina de onboarding que cria conexões e mostra o QR codeconnections:read, connections:write
Configuração do segredo de webhookwebhooks:write

Com essa divisão, uma chave de envio vazada não desconecta números, e uma chave de leitura não recebe o QR code (com só connections:read, o campo qr vem null). As chaves têm validade, podem ser revogadas e são rotacionadas com uma janela de sobreposição: a nova passa a valer antes de a antiga expirar, e a troca acontece sem derrubar a integração do cliente.

Webhooks separados, mesmo num servidor só

Cada projeto tem o próprio endereço de webhook e o próprio segredo de assinatura. Se cada cliente tem um servidor, aponte cada projeto para o dele. Se a agência centraliza tudo num serviço próprio, use um caminho por cliente e um segredo por projeto: assim, um segredo vazado não permite forjar eventos de outro cliente.

Toda entrega traz os cabeçalhos X-Sales-Timestamp e X-Sales-Signature, um HMAC-SHA256 de timestamp + "." + corpo bruto. O exemplo abaixo, em Node.js com Express, recebe os eventos de vários projetos, confere a assinatura com o segredo certo e só então aceita o evento:

import { createHmac, timingSafeEqual } from 'node:crypto'
import express from 'express'

// Um projeto por cliente: o id do projeto e o segredo de cada um vêm do seu cofre de segredos
const CLIENTES = new Map([
  ['padaria-central', { tenantId: process.env.TENANT_PADARIA, secret: process.env.SECRET_PADARIA }],
  ['clinica-sorriso', { tenantId: process.env.TENANT_CLINICA, secret: process.env.SECRET_CLINICA }],
])

function isSigned(secret, rawBody, timestamp, signature) {
  if (!secret || !/^\d+$/.test(timestamp ?? '') || !signature) return false
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false
  const mac = createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest('hex')
  const expected = Buffer.from(`sha256=${mac}`)
  const received = Buffer.from(signature)
  return expected.length === received.length && timingSafeEqual(expected, received)
}

const app = express()

app.post('/whatsapp/:cliente', express.raw({ type: 'application/json' }), (req, res) => {
  const cliente = CLIENTES.get(req.params.cliente)
  const ok = cliente && isSigned(cliente.secret, req.body, req.get('x-sales-timestamp'), req.get('x-sales-signature'))
  if (!ok) return res.sendStatus(401)

  const event = JSON.parse(req.body.toString('utf8'))
  if (event.tenantId !== cliente.tenantId) return res.sendStatus(401)

  // Responda 2xx em até 10 s e processe depois, numa fila sua
  res.sendStatus(200)
  enqueue(req.params.cliente, event)
})

function enqueue(cliente, event) {
  // BullMQ, SQS, uma tabela de jobs: o que a agência já usa
  console.log(cliente, event.type, event.externalId)
}

app.listen(3000)

Três cuidados valem para qualquer linguagem:

  1. Assine sobre o corpo bruto. Converter o JSON e serializar de novo muda os bytes, e a assinatura deixa de conferir.
  2. A entrega é pelo menos uma vez. O mesmo evento pode chegar duas vezes: processe de forma idempotente, pelo data.messageId nas mensagens.
  3. Ignore tipos que você não conhece. O contrato só cresce; um tipo novo não deve derrubar o seu roteador.

O envelope é o mesmo em todos os eventos (type, connectionId, tenantId, externalId, timestamp, data), então o roteamento por cliente e por número fica em duas linhas. O passo a passo da verificação, com a versão em PHP, está no guia de webhooks do WhatsApp. Se um endpoint de cliente ficar fora do ar, a apiwpp faz até 6 tentativas, guarda o histórico de entregas e permite reenviar as que falharam, como detalha o recurso de webhooks assinados.

Uma fatura só, cobrada por número

Na apiwpp a cobrança é por número conectado, por mês, com mensagens ilimitadas dentro dos limites de envio. Não há tarifa por mensagem, então o custo de cada cliente é previsível: é a quantidade de números dele, multiplicada pelo preço do plano, mais os IPs dedicados, se houver. Os valores de LITE, PRO e do IP dedicado estão em preços, com uma calculadora.

A organização inteira paga uma assinatura só, com uma fatura para todos os números, por PIX, boleto ou cartão, escolhido na página de cada fatura. Para a agência, isso muda a rotina de três jeitos:

  • Cliente novo no meio do mês. O número adicional fica disponível na hora, e o restante do mês é cobrado de forma proporcional, numa cobrança avulsa.
  • Cliente que sai. A redução vale a partir da fatura seguinte, nunca abaixo dos números em uso. Apague a conexão do cliente antes de reduzir.
  • Repasse ao cliente. A apiwpp cobra a agência; a cobrança dos seus clientes, com a margem que você definir, continua no seu processo. Não há, hoje, faturamento separado por cliente final.

Como o plano vale para a organização, escolha pelo cliente mais exigente. O PRO libera editar e apagar mensagens enviadas pela API, marcar como lida, controlar a presença ("digitando…", "gravando áudio") e o IP dedicado. Se nenhum cliente precisa disso, o LITE já envia e recebe mensagens, mídias e templates, com webhooks, fila e proxy.

Isolar a rede de cada cliente: proxy e IP dedicado

Para o WhatsApp, o endereço de onde o número se conecta faz parte da reputação dele. Por isso cada número conectado na apiwpp sai por um proxy brasileiro do pool, com um cliente por IP e verificações de saúde que tiram o número de um proxy com problema.

Quando um cliente pede mais isolamento, há duas opções por conexão:

OpçãoQuando usarComo funciona
Proxy compartilhado do poolO padrão para a maioria dos clientesIncluso no número, IP brasileiro
IP dedicado (adicional, PRO)Clientes com operação sensível ou que exigem um endereço só delesO número ganha um IP próprio, cobrado na mesma assinatura e de forma proporcional
Proxy do próprio clienteO cliente já tem um proxy e quer que o número saia por eleConfigurado na conexão com PUT /connections/{id}/proxy, verificado antes de parear

O proxy próprio é verificado antes de ser salvo, e nenhum QR code é mostrado a partir de uma saída que não passou na verificação. A URL fica gravada criptografada e nunca é devolvida pela API. Mais detalhes em proxy e IP dedicado e na definição de IP dedicado.

A operação do dia a dia

Com dezenas de números, o trabalho da equipe é perceber problemas antes do cliente. Quatro hábitos ajudam.

Acompanhe o status de cada conexão

O evento connection.status avisa quando um número abre ou fecha, com o motivo (reason) e se a apiwpp vai reconectar sozinha (willReconnect). Alerte a equipe na hora num fechamento com willReconnect: false, como um logged_out, que exige um QR code novo no celular do cliente.

Para um painel interno ou uma rotina de verificação, a rota GET /connections lista as conexões que a chave alcança, com status, projeto e externalId:

const res = await fetch('https://api.apiwpp.com/connections', {
  headers: { Authorization: `Bearer ${process.env.APIWPP_KEY}` },
})
const { connections } = await res.json()

const foraDoAr = connections.filter((c: { status: string }) => c.status !== 'open')
for (const c of foraDoAr) console.log(c.tenantName, c.externalId, c.status)
Uma visão por cliente: cada número com o status da conexão e o identificador do seu sistema.

Respeite a fila de cada número

Cada número tem a própria fila, com limites por minuto, por hora e por dia, intervalo aleatório entre envios e um teto de destinatários novos a cada 24 horas. Um cliente que tenta enviar demais não afeta o número de outro. Explique isso ao cliente antes de ligar o número: o envio responde 202 e entra na fila, não sai no mesmo segundo. Os valores estão em fila anti-bloqueio.

Planeje o aquecimento dos números novos

Todo número recém-pareado passa por um aquecimento de 14 dias, com limites que crescem por etapa. Não prometa ao cliente o volume cheio no primeiro dia, e evite reconectar números sem necessidade: parear de novo recomeça o aquecimento. O guia de aquecimento de número mostra a tabela e o que fazer nesse período.

Use os registros antes de abrir um chamado

O painel mostra os projetos, as conexões e os registros de mensagens e de entregas de webhook, guardados por 7 dias no padrão. Envie sempre com um clientRef (o id do pedido ou do aviso no sistema do cliente): além de evitar mensagens duplicadas, ele permite achar o envio no registro com GET /messages?q=<clientRef>. Para saber se o problema é da plataforma, a página de status pública mostra a saúde de cada componente.

Como começar hoje

  1. Liste os clientes e os sistemas de cada um e decida quantos projetos você precisa: um por cliente, ou um por sistema quando os eventos não podem se misturar.
  2. Defina o externalId de cada número a partir do código do cliente no seu CRM ou ERP.
  3. Monte a tabela de escopos por componente e gere uma chave para cada peça, guardada num cofre de segredos.
  4. Aponte o webhook de cada projeto para o servidor certo, com um segredo por projeto, e teste a verificação da assinatura.
  5. Crie sua conta na apiwpp e conecte o número de um cliente piloto nos 7 dias de teste. Veja também o caso de uso completo de API de WhatsApp para agências.

Perguntas frequentes

Cada cliente da agência precisa de uma conta na apiwpp?

Não. A agência tem uma organização com uma assinatura só, e cada cliente vira um projeto dentro dela, com chaves de API, webhook e números próprios. Projetos não têm custo: a conta é feita pelos números conectados.

Um cliente consegue acessar os números de outro?

Não pelas chaves de API: cada chave pertence a um projeto e só alcança as conexões dele. Os eventos de cada número também só são entregues no webhook do projeto a que ele pertence, assinados com o segredo daquele projeto.

Posso emitir uma fatura da apiwpp para cada cliente?

Não hoje. A apiwpp emite uma fatura para a organização, calculada pelos números conectados. A cobrança de cada cliente, com a margem que a agência definir, continua no seu processo, e o custo por cliente é fácil de calcular porque o preço é por número.

O que acontece se a fatura da agência atrasar?

Há 5 dias de carência. Depois disso, a organização é suspensa: os números são desconectados com a sessão guardada e voltam sem novo QR code quando o pagamento é confirmado. Como a fatura é única, a suspensão vale para todos os clientes, então vale manter o pagamento em dia com antecedência.

Dá para misturar LITE e PRO entre clientes?

O plano é da organização, não de cada projeto. Por isso, escolha pelo cliente mais exigente: se algum precisa editar ou apagar mensagens, marcar como lida ou de IP dedicado, o PRO atende a todos. Se nenhum precisa, o LITE cobre envio, recebimento, mídias, templates e webhooks.

Usar vários números para o mesmo cliente aumenta o volume de envio?

Cada número tem a própria fila e os próprios limites, então um cliente com duas lojas pode ter um número para cada uma. Mas dividir a mesma lista fria entre vários números só multiplica as denúncias. Números extras servem para operações diferentes, não para contornar o ritmo de envio.


Leia também:

Conecte seu primeiro número hoje.

7 dias grátis, sem cartão de crédito.