Erros
Os erros usam códigos de status convencionais com umdetail legível por máquina:
Erros estruturados sempre carregam um
code estável sobre o qual você pode ramificar; as chaves adicionais (como conflicting_contact_id em um contato duplicado) fornecem o necessário para resolver. Cada formato de erro está publicado na referência da API.
Enviar um modelo
POST /v1/templates/{id}/send recusa a solicitação inteira em vez de enfileirar parte dela, então uma recusa nunca deixa você com o envio pela metade nem custa nada. Os códigos que vale ramificar:
GET /v1/templates/{id}/send-requirements diz o que um modelo precisa antes de enviar, então a maioria destes nunca precisa acontecer.
Limites de uso
Cada organização tem um orçamento compartilhado entre todas as suas chaves, definido pelo plano: 20 solicitações por segundo no Scale, 10 por segundo no Growth e 5 por segundo durante o teste gratuito. Acima do orçamento, as solicitações retornam429 com um cabeçalho Retry-After (segundos; sempre 1, porque a janela é de um segundo).
Cada resposta, inclusive o 429, carrega o seu orçamento atual, para você dosar sem contar chamadas por conta própria:
Leia
X-RateLimit-Remaining e reduza o ritmo conforme ele se aproxima de zero, em vez de correr até o 429. Se a sua integração realmente precisar de mais, fale com a gente.
Solicitações em andamento ao mesmo tempo
A API também limita quantas solicitações uma mesma chave pode ter em andamento ao mesmo tempo. Acima desse limite, ou quando a API como um todo está no limite de capacidade, uma solicitação retorna503 com "server_busy" e Retry-After: 1. A solicitação não foi executada e não conta contra o seu orçamento, então tente novamente depois da espera.
Chamadas que esperam a resposta da anterior não vão ver isso; uma rajada de muitas chamadas em paralelo pode. Para enviar um modelo a muitas pessoas, inclua até 100 destinatários em cada POST /v1/templates/{id}/send em vez de fazer uma chamada por destinatário.
Uma solicitação é uma solicitação, não importa quanto ela faça.
POST /v1/templates/{id}/send conta uma vez só, leve um destinatário ou cem, então agrupar destinatários em um único envio é a forma mais barata de ficar dentro do orçamento. O que limita o volume real de mensagens é o próprio limite móvel de 24 horas do WhatsApp, não este.Repetir com segurança
POST /v1/templates/{id}/send aceita um cabeçalho Idempotency-Key. Envie a mesma chave de novo dentro de 24 horas e você recebe a campanha original em vez de um segundo envio. Use isso depois de um timeout, quando não dá para saber se a solicitação chegou. Use uma chave nova para cada envio distinto.
Paginação
Os endpoints de listagem retornam:next_cursor de volta como ?cursor= para buscar a próxima página; um cursor null significa que você chegou ao fim. Os cursores são opacos, então não os interprete.
As listas de propriedades e etapas do funil não são paginadas: retornam o conjunto completo, sem next_cursor.
Compatibilidade
Esta é uma API jovem e muda com frequência. Dois hábitos mantêm sua integração estável:- A maioria das mudanças é aditiva: novos endpoints, novos parâmetros opcionais, novos campos de resposta, novos valores em campos de texto. Tolere campos e valores desconhecidos e ignore o que não reconhecer.
- Cada mudança do contrato aparece no changelog. Confira quando algo parecer diferente.