{"id":564,"date":"2026-10-28T16:08:26","date_gmt":"2026-10-28T16:08:26","guid":{"rendered":"https:\/\/vectalk.com.br\/blog\/api-whatsapp-para-agencias\/"},"modified":"2026-10-28T16:08:28","modified_gmt":"2026-10-28T16:08:28","slug":"api-whatsapp-para-agencias","status":"publish","type":"post","link":"https:\/\/vectalk.com.br\/blog\/api-whatsapp-para-agencias\/","title":{"rendered":"API do WhatsApp para ag\u00eancias: como gerenciar o WhatsApp de v\u00e1rios clientes"},"content":{"rendered":"\n

Atualizado em 28\/10\/2026<\/em><\/p>\n\n\n\n

Para uma ag\u00eancia, a forma mais segura de gerenciar a API do WhatsApp de v\u00e1rios clientes \u00e9 manter cada cliente no pr\u00f3prio portf\u00f3lio empresarial da Meta, com a pr\u00f3pria conta do WhatsApp e a pr\u00f3pria conta de mensagens, e dar \u00e0 ag\u00eancia acesso como parceira. Assim, limite de envio, qualidade, templates e cobran\u00e7a ficam separados por cliente, e o n\u00famero continua sendo do cliente se o contrato acabar. Do lado t\u00e9cnico, a ag\u00eancia centraliza tudo numa integra\u00e7\u00e3o s\u00f3 e separa os clientes pelo phone_number_id<\/code>.<\/p>\n\n\n\n

Abaixo: estrutura, acesso, cobran\u00e7a, templates, webhooks e relat\u00f3rios por cliente.<\/p>\n\n\n\n

Um portf\u00f3lio por cliente: por que n\u00e3o juntar tudo<\/h2>\n\n\n\n

Pendurar todos os n\u00fameros num portf\u00f3lio da ag\u00eancia parece mais simples, mas v\u00e1rias regras da Meta s\u00e3o calculadas por portf\u00f3lio ou por conta, e isso mistura o risco de um cliente com o dos outros.<\/p>\n\n\n\n

Item<\/th>Onde fica na Meta<\/th>O que acontece se todos os clientes estiverem juntos<\/th><\/tr><\/thead>
Limite de mensagens (destinat\u00e1rios \u00fanicos fora da janela em 24 h)<\/td>Portf\u00f3lio empresarial<\/td>Todos os n\u00fameros dividem o mesmo limite; a campanha de um cliente consome a capacidade dos outros<\/td><\/tr>
Verifica\u00e7\u00e3o da empresa<\/td>Portf\u00f3lio empresarial<\/td>A verifica\u00e7\u00e3o \u00e9 da empresa dona do portf\u00f3lio, n\u00e3o de cada cliente<\/td><\/tr>
Templates<\/td>Conta de mensagens<\/td>Templates de clientes diferentes ficam na mesma lista e com o mesmo hist\u00f3rico de qualidade<\/td><\/tr>
Forma de pagamento<\/td>Conta de mensagens<\/td>Uma fatura s\u00f3, que a ag\u00eancia precisa ratear<\/td><\/tr>
Restri\u00e7\u00f5es por viola\u00e7\u00e3o de pol\u00edtica<\/td>Conta de mensagens<\/td>Uma campanha ruim de um cliente pode bloquear o envio dos demais<\/td><\/tr>
Nome de exibi\u00e7\u00e3o<\/td>N\u00famero<\/td>Precisa representar a empresa do cliente, n\u00e3o a ag\u00eancia<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

A documenta\u00e7\u00e3o de limites de mensagens<\/a> \u00e9 clara: o limite vale para o portf\u00f3lio, e todos os n\u00fameros dele compartilham a mesma cota. Um portf\u00f3lio novo come\u00e7a em 250 destinat\u00e1rios \u00fanicos em 24 horas e sobe para 2.000, 10.000, 100.000 e ilimitado. Com clientes separados, cada um tem a pr\u00f3pria escada de limite e a pr\u00f3pria reputa\u00e7\u00e3o. E, se o cliente trocar de ag\u00eancia, o n\u00famero vai junto, sem disputa.<\/p>\n\n\n\n

A nova estrutura da conta: conta do WhatsApp e conta de mensagens<\/h2>\n\n\n\n

Desde 23\/09\/2026, a antiga WABA foi dividida em duas partes. A conta do WhatsApp<\/strong> guarda o n\u00famero. A conta de mensagens<\/strong> guarda templates, cobran\u00e7a e webhooks. Para a ag\u00eancia, a consequ\u00eancia pr\u00e1tica \u00e9 que acesso e troca de fornecedor passam pela conta do WhatsApp: trocar de provedor \u00e9 compartilhar a conta do WhatsApp do cliente com o novo parceiro. Detalhamos a mudan\u00e7a em conta do WhatsApp x conta de mensagens<\/a>.<\/p>\n\n\n\n

Como a ag\u00eancia ganha acesso aos ativos do cliente<\/h2>\n\n\n\n

H\u00e1 dois caminhos comuns, e muitas ag\u00eancias usam os dois.<\/p>\n\n\n\n

1. Cadastro Incorporado (Embedded Signup)<\/h3>\n\n\n\n

O Cadastro Incorporado \u00e9 o fluxo da Meta, aberto a partir de um site ou portal, em que o cliente faz login, escolhe ou cria o portf\u00f3lio, registra o n\u00famero e autoriza o app a acessar esses ativos. A documenta\u00e7\u00e3o de parceiros<\/a> descreve variantes para clientes que j\u00e1 usam o app WhatsApp Business (coexist\u00eancia) e para contas criadas e compartilhadas pelo Meta Business Suite.<\/p>\n\n\n\n

Na pr\u00e1tica, o pr\u00f3prio dono do portf\u00f3lio conclui as telas numa chamada curta com a ag\u00eancia, sem compartilhar senha.<\/p>\n\n\n\n

2. Acesso de parceiro no portf\u00f3lio<\/h3>\n\n\n\n

Para tarefas que acontecem no painel da Meta (WhatsApp Manager, templates, pagamentos, verifica\u00e7\u00e3o), o cliente pode conceder ao portf\u00f3lio da ag\u00eancia acesso a ativos espec\u00edficos como parceiro. O passo a passo est\u00e1 na central de ajuda da Meta, em Como conceder acesso a ativos do seu portf\u00f3lio empresarial para um parceiro<\/a>.<\/p>\n\n\n\n

Pe\u00e7a s\u00f3 os ativos de que a ag\u00eancia precisa, atribua o acesso a pessoas nomeadas (nunca a um login compartilhado) e deixe no contrato que o administrador do portf\u00f3lio \u00e9 sempre o cliente.<\/p>\n\n\n\n

Quem verifica a empresa<\/h3>\n\n\n\n

A verifica\u00e7\u00e3o da empresa \u00e9 feita no portf\u00f3lio do cliente, com documentos do cliente. Ela \u00e9 um dos caminhos para subir o limite de 250 para 2.000. A Meta tamb\u00e9m prev\u00ea que o parceiro que fez o onboarding verifique a empresa em nome do cliente, conforme a p\u00e1gina de limites. Combine quem conduz.<\/p>\n\n\n\n

Quem paga a Meta: tr\u00eas modelos de cobran\u00e7a<\/h2>\n\n\n\n

A Meta cobra por mensagem entregue, pela categoria e pelo pa\u00eds do destinat\u00e1rio. H\u00e1 tr\u00eas modelos comuns:<\/p>\n\n\n\n

Modelo<\/th>Quem paga a Meta<\/th>Como a ag\u00eancia cobra o cliente<\/th><\/tr><\/thead>
Cliente com forma de pagamento pr\u00f3pria<\/td>O cliente, direto na conta de mensagens<\/td>Ag\u00eancia cobra s\u00f3 o servi\u00e7o dela<\/td><\/tr>
Provedor com linha de cr\u00e9dito<\/td>O provedor, que fatura o cliente<\/td>Ag\u00eancia cobra o servi\u00e7o; o provedor fatura o uso<\/td><\/tr>
Proxy gerenciado (como a Vectalk)<\/td>A Vectalk paga a Meta<\/td>Mensalidade mais saldo pr\u00e9-pago na Vectalk; cada mensagem entregue desconta do saldo; a ag\u00eancia decide se repassa<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

A documenta\u00e7\u00e3o de parceiros explica que, no caso dos Provedores de Tecnologia, o cliente cadastra a pr\u00f3pria forma de pagamento e a Meta cobra o uso diretamente dele; j\u00e1 os Parceiros de Solu\u00e7\u00f5es podem estender linha de cr\u00e9dito e faturar o cliente. Os tipos de parceiro est\u00e3o explicados em o que \u00e9 BSP e Tech Provider<\/a>.<\/p>\n\n\n\n

Para montar a proposta, use as tarifas oficiais para destinat\u00e1rios no Brasil, em vigor desde 1\u00ba\/10\/2026:<\/p>\n\n\n\n

Categoria<\/th>Tarifa Meta (Brasil)<\/th><\/tr><\/thead>
Marketing<\/td>R$ 0,3217 por mensagem entregue<\/td><\/tr>
Utilidade<\/td>R$ 0,0350<\/td><\/tr>
Autentica\u00e7\u00e3o<\/td>R$ 0,0350<\/td><\/tr>
Servi\u00e7o<\/td>R$ 0,0350, ap\u00f3s a franquia de 1.000 por m\u00eas por n\u00famero<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Desde outubro de 2026, utilidade dentro da janela de atendimento tamb\u00e9m \u00e9 cobrada. Explique isso ao cliente antes da primeira fatura. O artigo mensagens de utilidade na janela de atendimento<\/a> traz os detalhes.<\/p>\n\n\n\n

Templates por cliente<\/h2>\n\n\n\n

Os templates ficam na conta de mensagens de cada cliente. Isso \u00e9 bom: a reprova\u00e7\u00e3o ou a pausa de um template n\u00e3o afeta os outros clientes. O trabalho da ag\u00eancia \u00e9 manter um padr\u00e3o para n\u00e3o se perder em dezenas de contas.<\/p>\n\n\n\n

Uma conven\u00e7\u00e3o que funciona:<\/p>\n\n\n\n

Parte do nome<\/th>Exemplo<\/th>Para qu\u00ea<\/th><\/tr><\/thead>
Finalidade<\/td>pedido_confirmado<\/code><\/td>Saber o que o template faz<\/td><\/tr>
Variante<\/td>_v2<\/code><\/td>Trocar o texto sem apagar o hist\u00f3rico<\/td><\/tr>
Idioma (no campo language<\/code>)<\/td>pt_BR<\/code><\/td>Manter vers\u00f5es por idioma com o mesmo nome<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Mantenha uma biblioteca de textos aprovados por setor. Os modelos de template por setor<\/a> servem de ponto de partida. Antes de criar, confira a categoria: conte\u00fado promocional \u00e9 marketing, mesmo que pare\u00e7a um aviso. O guia como a Meta classifica seu template<\/a> explica os crit\u00e9rios.<\/p>\n\n\n\n

Na Vectalk, a cria\u00e7\u00e3o de template usa o token da inst\u00e2ncia do cliente, e a conta de mensagens \u00e9 resolvida pelo token:<\/p>\n\n\n\n

curl -X POST https:\/\/apis.vectalk.com.br\/api\/templates \\\n  -H \"Authorization: Bearer TOKEN_INSTANCIA_CLIENTE_A\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"name\": \"pedido_confirmado_v2\",\n    \"language\": \"pt_BR\",\n    \"category\": \"UTILITY\",\n    \"components\": [\n      { \"type\": \"BODY\", \"text\": \"Ol\u00e1 {{1}}, seu pedido #{{2}} foi confirmado.\",\n        \"example\": { \"body_text\": [[\"Ana\", \"4821\"]] } }\n    ]\n  }'<\/code><\/pre>\n\n\n\n
Webhooks e roteamento: uma integra\u00e7\u00e3o, v\u00e1rios clientes<\/h2>\n\n\n\n
Todo evento da Cloud API chega com o phone_number_id<\/code> em entry[].changes[].value.metadata<\/code>. \u00c9 por ele que a ag\u00eancia sabe de qual cliente \u00e9 a mensagem. Um roteador m\u00ednimo em Node.js, com o mapa de clientes no c\u00f3digo (em produ\u00e7\u00e3o, no banco):<\/p>\n\n\n\n
const CLIENTES = {\n  '1098765432': { nome: 'clinica-exemplo', destino: 'https:\/\/crm.agencia.com\/clinica' },\n  '2034567891': { nome: 'loja-exemplo', destino: 'https:\/\/crm.agencia.com\/loja' },\n};\n\nexport async function rotear(evento) {\n  for (const entry of evento.entry ?? []) {\n    for (const change of entry.changes ?? []) {\n      const id = change.value?.metadata?.phone_number_id;\n      const cliente = CLIENTES[id];\n      if (!cliente) {\n        console.warn('phone_number_id sem cliente', id);\n        continue;\n      }\n      await fetch(cliente.destino, {\n        method: 'POST',\n        headers: { 'Content-Type': 'application\/json' },\n        body: JSON.stringify(change.value),\n      });\n    }\n  }\n}<\/code><\/pre>\n\n\n\n
Se voc\u00ea integra direto com a Meta, valide a assinatura X-Hub-Signature-256<\/code> antes de rotear; o passo a passo est\u00e1 em como validar a assinatura do webhook<\/a>.<\/p>\n\n\n\n
Na Vectalk, voc\u00ea registra v\u00e1rias URLs por inst\u00e2ncia com POST \/api\/webhooks<\/code> (por exemplo, o CRM do cliente e o monitoramento da ag\u00eancia), e todas recebem o mesmo evento.<\/p>\n\n\n\n
Relat\u00f3rios por cliente<\/h2>\n\n\n\n
Separe por cliente e por m\u00eas: mensagens enviadas, entregues, lidas e com falha; envios por categoria (o que define o custo); erros recorrentes, como opt-out de marketing; e tempo de resposta, se a ag\u00eancia opera o atendimento. O custo estimado \u00e9 a soma dos entregues por categoria vezes a tarifa. Para m\u00e9tricas de atendimento, veja TMR, TMA e CSAT no WhatsApp<\/a>.<\/p>\n\n\n\n
Na Vectalk, GET \/api\/messages<\/code> aceita filtros de per\u00edodo, status e dire\u00e7\u00e3o. Com um token de inst\u00e2ncia, a consulta j\u00e1 fica restrita \u00e0quele cliente:<\/p>\n\n\n\n
curl \"https:\/\/apis.vectalk.com.br\/api\/messages?from=2026-10-01&to=2026-10-31&status=failed&direction=outbound\" \\\n  -H \"Authorization: Bearer TOKEN_INSTANCIA_CLIENTE_A\"<\/code><\/pre>\n\n\n\n
Checklist de entrada de um novo cliente<\/h2>\n\n\n\n
    \n
  1. Portf\u00f3lio pr\u00f3prio do cliente, com ele como administrador, e verifica\u00e7\u00e3o iniciada.<\/li>\n\n\n
  2. N\u00famero definido (novo ou em coexist\u00eancia) e nome de exibi\u00e7\u00e3o com a marca do cliente.<\/li>\n\n\n
  3. Cobran\u00e7a por escrito: quem paga a Meta e como o uso \u00e9 repassado.<\/li>\n\n\n
  4. Opt-in dos contatos documentado pelo cliente.<\/li>\n\n\n
  5. Templates aprovados, webhook testado com uma mensagem real e relat\u00f3rio mensal combinado.<\/li>\n\n<\/ol>\n\n\n\n
    Como fazer com a Vectalk<\/h2>\n\n\n\n
    A Vectalk \u00e9 um proxy da WhatsApp Cloud API oficial: os payloads e webhooks s\u00e3o os da Meta, e o cliente paga a Vectalk, que paga a Meta. Para ag\u00eancias, tr\u00eas recursos resolvem a maior parte do trabalho:<\/p>\n\n\n\n