Limites e boas práticas

Segurança do token

• Guarde o token em variável de ambiente ou cofre de segredos. Nunca em código-fonte, front-end, app mobile ou URL.
• Chame a API do seu servidor. Um token no navegador do cliente final dá acesso à sua conta para qualquer pessoa.
• Um token por integração, cada um com um usuário de permissões mínimas. Se um vazar, você exclui só aquele.

Créditos

Os envios feitos por automação consomem créditos da conta, como os disparos feitos pelo painel. Se a conta não tiver créditos suficientes, o contato é inscrito mas a mensagem não sai — confira o saldo em GET /v1/me antes de disparar em volume.

Volume e ritmo

• Hoje a API não aplica limite de requisições por token, mas trate como se aplicasse: até 5 requisições por segundo por integração é um ritmo seguro.
• Para disparar para muitos contatos, mande um POST /automations/enrollments com a lista em contacts, em vez de uma chamada por contato.
• Nas consultas, pagine (veja Paginação e filtros) em vez de pedir tudo de uma vez.
• Em 5xx ou erro de rede, tente de novo com espera crescente (1s, 2s, 4s…) e um teto de tentativas.

Idempotência

• POST /contacts/create-or-update é seguro para repetir: ele procura o contato pelo celular/e-mail antes de criar.
• POST /automations/enrollments não é idempotente: repetir a chamada pode inscrever (e enviar) de novo. Guarde do seu lado o que já foi disparado.

Janela de 24 horas do WhatsApp

Fora da janela de 24h aberta pelo cliente, o WhatsApp só aceita template aprovado pela Meta. Por isso, automações de disparo usam templates — o texto livre só funciona dentro de uma conversa ativa.

Datas e fuso

As datas da API vêm em ISO 8601 em UTC (2026-11-08T15:00:00.000Z). Converta para o fuso do seu usuário na exibição (Brasília é UTC−3).