Pular para o conteúdo

API e SDK

Limites

Os limites da API do Messajo, do envio por número, da Meta e da retenção de dados.

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.

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.

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.

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.

Canal Regra
WhatsApp 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.

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)
Instagram 100 mensagens/s 10 mensagens/s (gasta também uma ficha de texto)
Messenger 100 mensagens/s 100 mensagens/s
Limite Instagram 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.

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
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.

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.

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.