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.
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ível | O que representa | O que fica nele |
|---|---|---|
| Organização | A agência | A assinatura, a fatura e o acesso ao painel |
| Projeto | Um cliente (ou um sistema de um cliente) | Chaves de API, endereço de webhook e segredo de assinatura |
| Conexão | Um número de WhatsApp | Sessão, fila de envio, aquecimento e proxy |
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:
| Componente | Escopos |
|---|---|
| Sistema do cliente que envia avisos | messages:send |
| Painel interno que mostra o status dos números | connections:read |
| Rotina de onboarding que cria conexões e mostra o QR code | connections:read, connections:write |
| Configuração do segredo de webhook | webhooks: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:
- Assine sobre o corpo bruto. Converter o JSON e serializar de novo muda os bytes, e a assinatura deixa de conferir.
- A entrega é pelo menos uma vez. O mesmo evento pode chegar duas vezes: processe de forma idempotente, pelo
data.messageIdnas mensagens. - 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ção | Quando usar | Como funciona |
|---|---|---|
| Proxy compartilhado do pool | O padrão para a maioria dos clientes | Incluso no número, IP brasileiro |
| IP dedicado (adicional, PRO) | Clientes com operação sensível ou que exigem um endereço só deles | O número ganha um IP próprio, cobrado na mesma assinatura e de forma proporcional |
| Proxy do próprio cliente | O cliente já tem um proxy e quer que o número saia por ele | Configurado 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)
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
- 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.
- Defina o
externalIdde cada número a partir do código do cliente no seu CRM ou ERP. - Monte a tabela de escopos por componente e gere uma chave para cada peça, guardada num cofre de segredos.
- Aponte o webhook de cada projeto para o servidor certo, com um segredo por projeto, e teste a verificação da assinatura.
- 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: