Trabalhando com um agente de IA? Baixe a documentação completa como arquivo Markdown para usar como contexto.
Baixar .md completoO que cada canal suporta, os planos de licença e os limites da plataforma.
| Recurso | Facebook Messenger | ||
|---|---|---|---|
| Texto de saída — tamanho máximo | 4096 chars | 1000 chars | 2000 chars |
| Mídia de saída (Pro) | image, audio, video, document, sticker (arquivo WebP) | image, audio, video, document | image, audio, video, document, sticker (sticker_id do catálogo da Meta) |
| Mensagens interativas (Pro) | botões de resposta / link, cards (carrossel), lista | botões de resposta / link, cards (carrossel), respostas rápidas | botões de resposta / link, cards (carrossel), respostas rápidas |
| Mensagens de modelo (Pro) | ✅ Obrigatórias fora da janela de 24h | ❌ Não suportado | ❌ Não suportado |
| Webhooks recebidos — texto | ✅ type: "text" |
✅ type: "text" |
✅ type: "text" |
| Webhooks recebidos — mídia (Pro) | image, audio, video, document (figurinhas como image + media.sticker) |
image, audio, video, document | image, audio, video, document (figurinhas como image + media.sticker) |
| Status de entrega | sent delivered read failed |
delivered read failed |
delivered read failed |
| Formato do destinatário | Número de telefone sem + |
IGSID | PSID |
| Contorno da janela de 24h | Usar modelos aprovados | Nenhum — aguardar o usuário enviar mensagem | Nenhum — aguardar o usuário enviar mensagem |
| Identificador do canal | phone_number_id |
ig_account_id |
page_id |
| Perfil do remetente | data.from_name (dos contatos da Meta) |
Via endpoint de perfil | Via endpoint de perfil |
Observação: Cada conta Meta (número de telefone, conta do Instagram ou Página do Facebook) só pode estar conectada a uma conta Fiwano por vez.
O Fiwano oferece dois planos de licença. Cada canal conectado exige uma licença ativa.
| Plano | Mensal | Capacidades |
|---|---|---|
| Starter | US$ 12 | Mensagens de texto recebidas e enviadas ilimitadas, status de entrega |
| Pro | US$ 19 | Tudo do Starter + mídia recebida com arquivos, mídia enviada via URL HTTPS (URLs assinadas suportadas), mensagens interativas (botões, cards, respostas rápidas, listas), gerenciamento e envio de modelos do WhatsApp |
Contas novas começam com um período de teste gratuito de 7 dias (plano Pro). Para o ciclo de cobrança e como o estado de assinatura de um canal é reportado, veja Assinaturas e Cobrança. Para entender como essa taxa fixa se relaciona com as tarifas por mensagem da própria Meta, veja Custos de Mensagens Explicados.
Os envios são limitados a 10 tentativas de envio aceitas por segundo por canal,
somadas entre todas as API keys. Texto, mídia e modelos compartilham esse limite:
criar outra key não aumenta a capacidade de um canal, enquanto uma única key pode
operar vários canais de forma independente. Ao excedê-lo, a API retorna HTTP 429
com Retry-After.
Todas as outras operações da API pública (canais, assinaturas, templates, perfis
do remetente, download de mídia, redirects) são limitadas a 20 requisições por
segundo por API key. É uma proteção contra loops descontrolados, não uma cota:
uma integração normal fica muito abaixo disso, e uma key com problema não afeta as
outras keys da mesma conta. Ao excedê-lo, a API retorna HTTP 429 com
Retry-After. Faça leituras disparadas por eventos (download de mídia, perfil do
remetente) com nova tentativa em 429, não em uma rajada paralela sem limite — a
mídia recebida fica disponível por 60 minutos.
Em saturação excepcional do envio, uma tentativa pode retornar brevemente HTTP
503 + Retry-After; respeite o header e tente novamente. A Meta também aplica
limites próprios por canal e destinatário (fora do controle do Fiwano).
A Meta restringe quando você pode enviar mensagem a um usuário fora de uma conversa aberta:
POST /api/v1/messages/send-template. Isso é política da Meta. As respostas
dentro da janela são gratuitas nas primeiras 1.000 por mês por número; a Meta
cobra as respostas depois disso, e todos os modelos. Sem forma de pagamento na
conta WhatsApp Business, as 1.000 gratuitas continuam sendo entregues, e as
respostas seguintes não são entregues (erro 131042) —
veja Custos de Mensagens.A Meta baixa sua media_url e aplica seus próprios limites por plataforma. O
Fiwano não reverifica o arquivo, então um arquivo acima do limite é rejeitado
pela Meta com error_code 100 e a mensagem não é repetida — veja
Erros.
| Tipo de mídia | Facebook Messenger | ||
|---|---|---|---|
| Imagem | 5 MB (JPEG, PNG) | 8 MB (JPEG, PNG) | 8 MB (JPEG, PNG, GIF) |
| Figurinha | 100 KB estática / 500 KB animada (WebP, 512×512 px) | não disponível | sem arquivo — enviada pelo sticker_id do catálogo da Meta |
| Vídeo | 16 MB (MP4, 3GPP) | 25 MB (MP4, OGG, AVI, MOV, WebM) | 25 MB |
| Áudio | 16 MB (AAC, AMR, MP3, MP4, OGG) | 25 MB (AAC, M4A, WAV, MP4) | 25 MB |
| Documento | 100 MB (PDF, Office, texto) | 25 MB (PDF) | 25 MB |
Estes são limites da Meta e podem mudar; a sobrecarga de codificação pode ultrapassar o limite mesmo quando o tamanho em disco parece seguro. A Meta não lista de forma completa os formatos aceitos por tipo, então trate a rejeição por tamanho ou formato não suportado em vez de confiar em uma lista fixa.
GET /api/v1/media/{media_id} prontamente após o
webhook. Tamanho máximo de arquivo: 10 MB, qualquer tipo de arquivo. Um
arquivo maior chega com download_url: null e o file_size real.type: "unsupported" com
upgrade_required: "pro". Veja Assinaturas e Cobrança.