API ou painel: o que uma agência usa para gerir vários números de WhatsApp
Agência pequena começa pelo painel e faz bem. O problema aparece quando o onboarding vira gargalo: criar a instância, anotar o cliente, configurar o webhook e conferir o custo, tudo à mão, para o décimo, o vigésimo, o quadragésimo cliente. Esse é o ponto em que a API começa a pagar o próprio custo de desenvolvimento. Este guia mostra o que fazer em cada um, as chamadas que mais ajudam e o que ainda é do painel. Tudo se refere à ZapZap, uma API não oficial.
Publicado em · 4 min de leitura
Quando o painel basta
Até algumas dezenas de números, com poucos clientes novos por mês, o painel resolve: criar a instância, conectar por QR code, ligar o aquecimento, montar a IA e o Flow Builder e configurar o portal do cliente. Cada ação leva minutos, e você aprende o produto antes de automatizar. Automatizar cedo demais é gastar tempo de desenvolvimento em um processo que ainda vai mudar.
O painel também é o lugar de tudo o que é visual e de decisão: montar fluxos, ajustar o tom da IA, olhar conversas, configurar a marca do cliente e as seções do portal. Isso não está na API de gestão.
Quando a API compensa
A API compensa quando o mesmo trabalho se repete: cada cliente novo exige as mesmas cinco etapas. Um sinal claro é o onboarding competir com a entrega pelo tempo da equipe. Outro é você já ter um sistema próprio (CRM, ERP, portal da agência) onde o cliente nasce, e querer que a instância nasça junto.
A API de gestão cria, lista, consulta e remove instâncias com chave e segredo, devolve o custo antes da criação e permite gravar um campo metadata na instância. A documentação de autenticação e a referência trazem todos os campos.
As chamadas que mais ajudam
A primeira é consultar o custo (GET /instances/cost), para a sua automação conferir saldo antes de criar. A segunda é criar a instância (POST /instances) gravando o identificador do cliente e o plano no metadata. A terceira é registrar o webhook da instância (PUT /instances/{id}/webhook), apontando para o seu sistema; cada evento chega com o metadata, então você sabe de quem é.
O exemplo abaixo junta as duas primeiras. Guarde chave e segredo em variáveis de ambiente, nunca no código nem no front-end.
Check cost and create the client instance
# Create a new client instance and store who the client is in metadata
curl -X POST "https://api.zapzapapi.com/api/v1/instances" \
-H "Content-Type: application/json" \
-H "x-api-key: $ZAPZAP_API_KEY" \
-H "x-api-secret: $ZAPZAP_API_SECRET" \
-d '{"name":"cliente-a-loja-centro","metadata":{"customerId":"cli_123","plan":"basico"}}'
# Before that, to see the activation fee and the balance needed:
curl "https://api.zapzapapi.com/api/v1/instances/cost" \
-H "x-api-key: $ZAPZAP_API_KEY" -H "x-api-secret: $ZAPZAP_API_SECRET"O que continua no painel mesmo com API
Mesmo uma agência 100% automatizada volta ao painel para: escanear o QR code (feito pelo cliente, pelo link de conexão), configurar a marca do cliente, montar e copiar fluxos, ajustar a IA, abrir o portal e acompanhar os sinais de cada número. O desenho que funciona é híbrido: API para o que repete, painel para o que exige julgamento.
Para o cliente, o portal é a camada de painel que ele usa. Ele abre por link ou por número e senha, vê leads e vendas e reconecta o QR code, sem acessar a sua conta. Veja a página de revenda com a marca do cliente.
Um caminho em três etapas
Etapa 1, até uns 10 números: tudo pelo painel, com a planilha de operação (veja como organizar dezenas de números). Etapa 2, de 10 a 30: automatize a criação e o webhook por API, mantendo o resto no painel. Etapa 3, acima disso: ligue a criação de instâncias ao seu CRM, receba os eventos num único endpoint e acompanhe a saúde dos números numa visão sua.
Em todas as etapas, o custo é o mesmo por número: R$15 ao mês, sem cobrança por mensagem. Veja quanto custa operar 10, 25 ou 50 números e a página de agências.
Cuidados ao automatizar
Automação cria números rápido, e número criado rápido demais vira chip disparado cedo demais. Trave a criação em lote: a sua automação deve criar a instância, mas o início de envios depende da fase de aquecimento. Verifique idempotência na criação (não crie duas vezes a instância de um mesmo cliente) e registre erros de saldo insuficiente, que devem alertar uma pessoa.
Automatizar não reduz o risco do canal não oficial. O WhatsApp pode limitar ou bloquear números, e a API de WhatsApp não muda isso.
Resumo rápido
- Painel basta para os primeiros clientes e para tudo o que é visual: fluxos, IA, marca e portal.
- A API compensa quando o onboarding se repete e vira gargalo, ou quando o cliente já nasce no seu sistema.
- Três chamadas resolvem a maior parte: custo, criar instância com metadata e registrar webhook.
- O metadata volta em cada webhook, então você identifica o cliente sem tabela paralela.
- Automatizar a criação não dispensa o aquecimento: a fase do número é que libera o envio.
Continue lendo
Perguntas frequentes
Dá para criar instâncias por API?
Sim. A API de gestão cria, lista, consulta e remove instâncias com chave e segredo, e GET /instances/cost mostra a taxa de ativação e o saldo necessário antes da criação.
O que é o campo metadata?
É um campo livre da instância onde você grava, por exemplo, o identificador do cliente e o plano. Ele volta na consulta da instância e em cada webhook.
Preciso de desenvolvedor para usar a ZapZap numa agência?
Não para começar: o painel faz o essencial sem código. A API entra quando a repetição do onboarding justifica automatizar.
A API cobre a configuração da marca do cliente?
Não de ponta a ponta. Nome, logo, cor e as seções do portal são configurados no painel, por instância.
Automatizar a criação aumenta o risco de bloqueio?
Pode, se a automação liberar envio logo após criar o número. Mantenha o aquecimento por fase como condição para disparar, e lembre que o canal não oficial tem risco mesmo com boas práticas.
Crie a primeira instância por API
Crie a conta, gere a chave de API e rode as chamadas do guia. R$15 por número ativo ao mês, sem cobrança por mensagem. Ao verificar o telefone há crédito de boas-vindas, sujeito à campanha vigente.