API e SDK
Limites
Os limites da API do Messajo, do envio por número, da Meta e da retenção de dados.
API do Messajo
Seção intitulada “API do Messajo”Cada chave e cada organização têm um limite de requisições por minuto. Os dois valem ao mesmo tempo: a chamada passa só se couber nos dois.
| Escopo | Limite padrão |
|---|---|
| Por chave de API | 600 requisições/min (ajustável por chave até 6.000/min) |
| Por organização (todas as chaves somadas) | soma da vazão das conexões ativas × 60 × 1,25, no mínimo 1.200 requisições/min |
Os dois limites valem para os dois tipos de chave (organização mj_ e conexão mjc_). O limite por chave é de cada chave: cada chave de conexão tem o seu próprio contador de 600 requisições/min. O limite da organização é um só e soma o tráfego de todas as chaves, inclusive as de conexão, então várias chaves de conexão juntas ainda dividem a mesma vazão da organização.
Toda resposta da API /v1 traz os cabeçalhos da janela atual:
| Cabeçalho | O que é |
|---|---|
X-RateLimit-Limit |
Limite da janela |
X-RateLimit-Remaining |
Quantas chamadas ainda cabem na janela |
X-RateLimit-Reset |
Quando a janela reinicia (Unix, em segundos) |
Passou do limite, a resposta é 429 com o código rate_limited, o cabeçalho Retry-After (segundos) e o campo retry_after_ms no corpo. Espere esse tempo antes de repetir.
O limite da organização acompanha as conexões: dois números de 80 e 20 mensagens/s dão 7.500 requisições/min (100 × 60 × 1,25). Instagram e Messenger só entram na soma se tiverem vazão registrada. O valor é recalculado a cada 60 s, então conectar ou remover um número leva até 1 minuto para valer; X-RateLimit-Limit mostra o limite em vigor. Os demais valores podem mudar por plano.
Envio por número
Seção intitulada “Envio por número”Cada número tem uma vazão máxima, que depende do modo da conexão. O Messajo lê a vazão junto com a saúde do número, a cada 15 minutos, e mostra em Velocidade na página da conexão:
| Modo | Vazão |
|---|---|
| Coexistência (app do celular + API) | 20 mensagens/s |
| Só API | 80 mensagens/s |
| Só API, com vazão alta liberada pela Meta | 1.000 mensagens/s (a Meta sobe sozinha) |
Cada número tem um balde de fichas com a capacidade da vazão (20, 80 ou 1.000) e que enche nesse ritmo por segundo. Cada chamada que vai para a Meta gasta uma ficha: o envio, pela camada simples ou pelo espelho, e o typing. Sem ficha, o Messajo responde 429 com o código connection_rate_limited, o cabeçalho Retry-After e o retry_after_ms no corpo, sem chamar a Meta. Nada é enfileirado: espere esse tempo e repita com a mesma Idempotency-Key.
Se a própria Meta recusar por vazão (130429, 80007 ou 4 em meta_code), a resposta é 429 meta_rate_limited. Como a Meta não processou o pedido, o Messajo repete sozinho quando a espera cabe em 2,5 s; acima disso, devolve o erro com o retry_after_ms que a Meta informar.
Limite de mensagens da Meta
Seção intitulada “Limite de mensagens da Meta”A Meta limita quantos usuários únicos o portfólio (Business Manager) alcança com mensagens iniciadas pela empresa em 24 horas móveis. O limite é do portfólio e é compartilhado entre todos os números dele.
Os degraus são 250 → 2.000 → 10.000 → 100.000 → ilimitado. Para subir:
- verificar a empresa no portfólio, ou
- manter boa qualidade e enviar para pelo menos metade do limite atual dentro de 7 dias.
A Meta reavalia o portfólio a cada 6 horas e sobe o degrau sozinha quando as condições são cumpridas. O Messajo lê o degrau atual (campo whatsapp_business_manager_messaging_limit do número) junto com a saúde e mostra em Faixa de envio na página da conexão; quando ele muda, sai connection.updated com reason: "limit_changed". Respostas dentro de uma conversa aberta pelo contato não contam neste limite. As campanhas param sozinhas em 95 % da faixa e voltam quando ela libera.
Detalhes oficiais: limites de mensagens da Meta.
Limite por par
Seção intitulada “Limite por par”A Meta também limita quantas mensagens um número manda para o mesmo contato em pouco tempo (da ordem de uma mensagem a cada 6 segundos, com pequenas rajadas). Acima disso, a resposta é 429 pair_rate_limited, com 131056 em meta_code e retry_after_ms de 6.000: espere e espace os envios para esse contato. O Messajo nunca repete esse erro sozinho.
Janelas
Seção intitulada “Janelas”| Canal | Regra |
|---|---|
| Até 24 horas depois da última mensagem do contato, qualquer mensagem. Fora disso, só template aprovado. | |
| Instagram e Messenger | Até 24 horas depois da última mensagem do contato; 7 dias depois de o contato responder a um anúncio. Com tag: "human_agent" (só resposta de pessoa), até 7 dias. Fora disso, 422 antes de chamar a Meta. |
No WhatsApp, o Messajo confere a janela antes de chamar a Meta: mensagem que não é template, fora da janela, volta 422 outside_service_window, com o fim da janela em details[0].message. Só a mensagem do contato abre a janela; o que você manda pelo app do celular na coexistência não abre.
Instagram e Messenger
Seção intitulada “Instagram e Messenger”Cada conta do Instagram e cada Página do Messenger têm um balde de fichas, como os números do WhatsApp. Sem ficha, a resposta é 429 connection_rate_limited, sem chamar a Meta.
| Canal | Texto, reação, curtida, botões e cards | Mídia (imagem, images, áudio, vídeo, PDF) |
|---|---|---|
| 100 mensagens/s | 10 mensagens/s (gasta também uma ficha de texto) | |
| Messenger | 100 mensagens/s | 100 mensagens/s |
| Limite | Messenger | |
|---|---|---|
| Texto | 1.000 bytes | 2.000 caracteres |
| Imagens por mensagem | até 10 (images) |
1 |
| Anexo | imagem até 8 MB; áudio, vídeo e PDF até 25 MB | 25 MB |
| Publicações | 100 por conta em 24 h (publicações) | — |
Se a própria Meta recusar por vazão (4, 17, 32, 613 ou 80006), a resposta é 429 meta_rate_limited com o retry_after_ms que a Meta informar. Não há envio em massa nem campanhas no Instagram e no Messenger: a Meta não permite. Os números acima vêm da documentação da Plataforma do Instagram e da Plataforma do Messenger e ainda são conferidos em conta real.
Ligações, grupos, Flows e pedidos
Seção intitulada “Ligações, grupos, Flows e pedidos”| Limite | Valor |
|---|---|
| Pedido de permissão de chamada (Meta) | 1 a cada 24 h e 2 a cada 7 dias para o mesmo contato (Ligações) |
| SDP de uma ligação | 64 KiB |
| Participantes por grupo | 8 (Grupos) |
| JSON de um Flow | 10 MiB; PUT /v1/flows/{id}/json até 30 por minuto por organização |
| Trocas no endpoint de um Flow | 1.200 por minuto por Flow; o seu handler tem 7 s e até 256 KiB de resposta (Flows) |
| Itens por pedido | 100 (Vendas) |
Upload de mídia (POST /v1/media) |
120 por minuto por organização |
Tamanho do corpo
Seção intitulada “Tamanho do corpo”| Rota | Máximo |
|---|---|
/v1 (JSON) |
1 MiB |
POST /v1/media |
100 MiB |
POST /v1/campaigns/{id}/recipients |
20 MiB |
PUT /v1/flows/{id}/json |
10 MiB |
Painel (/rpc) |
2 MiB |
Acima disso, a resposta é 413 body_too_large, sem processar nada.
Retenção
Seção intitulada “Retenção”| Dado | Prazo |
|---|---|
| Evento bruto recebido da Meta | 7 dias |
| Eventos e registro das entregas | 30 dias (ou o prazo da organização, se for menor) |
| Logs do painel (requisições da API) | 30 dias (ou o prazo da organização, se for menor) |
| Mensagens, mídias, conversas e contatos | 90 dias por padrão; o dono escolhe de 7 até o teto da instância |
Depois do prazo, o dado é apagado no expurgo diário. Detalhes em Dados e privacidade.
Idempotency-Key
Seção intitulada “Idempotency-Key”Mande o cabeçalho Idempotency-Key (um valor único por operação, por exemplo um UUID) nas chamadas que criam algo, como o envio de mensagem. A chave vale por 24 horas: repetir a mesma chave nesse prazo devolve a resposta original, sem executar de novo. É assim que se repete um envio com segurança depois de um timeout.