Changelog

POST /api/v1/messages/send-interactive envia mensagens que o usuário responde com um toque, com o mesmo formato de requisição no WhatsApp, Instagram e Messenger: botões de resposta e de link, cards com imagem, título e botões que rolam como carrossel, chips de resposta rápida no Instagram e no Messenger e listas no WhatsApp. Cada canal recebe sua mensagem nativa; um formato que o canal não tem é recusado com um 400 claro em vez de ser trocado por outra coisa. Disponível no Pro, dentro da janela de 24 horas. Docs: Enviando Mensagens

Um toque em botão, resposta rápida, linha de lista, botão de modelo, item de menu ou ice breaker continua chegando como message.received de type: "text" com o rótulo em text, e agora também traz button_id — o id que você definiu, ou o payload configurado para o botão em outro lugar. Os botões de resposta rápida dos modelos do WhatsApp recebem esse id no envio, em variables.buttons. Docs: Recebendo Mensagens

Quando o roteamento de conversas da Meta entrega conversas a outro app, à caixa de entrada da Meta ou à Meta AI, as respostas pela Fiwano a essas conversas são recusadas. A página do canal no portal agora mostra isso como um aviso — se a conta envia novas conversas a outro app ou se apenas algumas conversas estão temporariamente sendo atendidas em outro lugar — em vez de e-mails frequentes sobre cada mensagem recebida assim. Uma resposta recusada pela Meta continua sendo informada como antes. Docs: Canais

Modelos com cabeçalho de imagem, vídeo ou documento agora podem ser enviados pela API: passe o arquivo em header_media_url. Modelos de autenticação com botão de copiar código podem ser criados pela API e pelo portal e são enviados com o código informado uma única vez. Os detalhes do modelo agora trazem o rejected_reason e o quality_score da Meta, a atualização de status a partir da Meta foi aprimorada e alguns casos específicos no tratamento de modelos foram refinados. O parâmetro sync da lista de modelos não é mais necessário e não tem efeito. Docs: Modelos do WhatsApp

Nos compartilhamentos do Instagram e do Messenger (type: "share"), caption agora significa o mesmo que na mídia: o texto que o usuário escreveu junto com o compartilhamento, se houver. Até agora o campo também podia trazer a legenda do próprio post compartilhado, de modo que as palavras do autor e as do usuário não se distinguiam, e o texto do usuário enviado com um post legendado não chegava. A legenda do post compartilhado não é mais incluída; share.url aponta para o post. Docs: Recebendo Mensagens

Todo canal em GET /api/v1/channels agora traz health: status é ok, ou action_required quando a Meta deixa de permitir que a Fiwano trabalhe com a conta ou o número — acesso ou permissão revogados, um número de WhatsApp removido ou fora da Business Platform, uma conta bloqueada pela Meta. reason é o erro da Meta com o código, since é quando o problema foi detectado. No portal, cada canal tem uma página Delivery problems com os últimos 7 dias: mensagens aguardando nova tentativa ou com falha, com o código e o texto da Meta, e entregas de webhook ao seu endpoint em nova tentativa, com falha ou recuperadas, com o erro do seu endpoint. Docs: Canais

O message.failed agora está disponível no Instagram e no Facebook Messenger. Em todos os canais ele também informa as mensagens que receberam queued e acabaram não sendo entregues — as novas tentativas se esgotaram, a Meta rejeitou a mensagem em uma nova tentativa ou nunca a confirmou, ou o canal foi desconectado enquanto a mensagem aguardava. O payload é o mesmo que o WhatsApp já usa: error é um motivo curto em texto, sempre presente; errors é um array com os detalhes completos do erro da Meta — código, título, mensagem — incluído quando a falha foi causada pela Meta. Adicione message.failed a webhook_events para recebê-lo. Docs: Recebendo Mensagens

A API agora também aceita sua chave como Authorization: Bearer <chave>, para ferramentas e conectores que só suportam bearer token. O X-API-Key continua sendo o header principal e prevalece quando os dois são enviados. Docs: Autenticação

A especificação OpenAPI (/api/v1/openapi.json e .yaml) agora pode ser importada por URL em ferramentas que rodam no navegador, como a importação de API dos construtores de apps com IA. Docs: Construtores de apps com IA

Os pedidos de suporte agora ficam registrados na sua conta Fiwano. Fale conosco pelo Contact no portal ou envie um e-mail para support@fiwano.com a partir do endereço da sua conta: cada pedido vira um ticket no portal, com o status atual e todo o histórico da conversa.

Pequenas melhorias no fluxo de conexão do WhatsApp, Instagram e Messenger: status mais claro junto ao botão de conexão, e tentar de novo depois de fechar a janela da Meta agora funciona de forma confiável. Docs: Canais

Todas as operações da API pública, exceto o envio de mensagens, agora são limitadas a 20 requisições por segundo por API key. É uma proteção contra loops descontrolados, não uma cota: integrações normais ficam muito abaixo disso. Ao exceder o limite, a API retorna 429 com Retry-After, como no limite de envio por canal. Docs: Capacidades

Quando uma conversa começa a partir de um anúncio Click-to-WhatsApp, Click-to-Instagram ou Click-to-Messenger, ou de um link m.me / ig.me com parâmetro ref, a Meta anexa a atribuição ao primeiro evento recebido. A Fiwano agora a repassa como data.referral nesse message.received: source (ad, link, product), text (o texto do anúncio que o usuário viu), image_url (o criativo, ou a miniatura de um vídeo), o seu ref e raw — o objeto de atribuição da Meta exatamente como recebido, com o id do anúncio, o ctwa_clid para a Conversions API e a mensagem de boas-vindas do WhatsApp. No Instagram e no Messenger, o novo evento opcional conversation.referral avisa quando um usuário que retorna clica em um anúncio ou link em uma conversa existente sem escrever; o clique reabre a janela de 24 horas. O recurso sai como beta, que esperamos manter até novembro de 2026: as quatro chaves normalizadas e o evento conversation.referral podem ser ajustados, raw permanece como está. Se você pretende depender das chaves normalizadas ou de conversation.referral, avise-nos em contact@fiwano.com: se algo mudar, informaremos antes da mudança. Docs: Recebendo Mensagens

Três coisas que os usuários fazem em uma conversa e que antes chegavam como unsupported agora têm uma forma própria. Um post, reel ou menção em story compartilhado no Instagram ou no Messenger é type: "share" com share_type, o link em share.url e a legenda do post em caption. Um toque em qualquer opção que você ofereceu — botão de resposta rápida de template do WhatsApp, botão interativo ou linha de lista, resposta rápida ou postback do Instagram ou do Messenger (Get Started, ice breakers, menu) — é um type: "text" comum cujo texto é o rótulo que o usuário viu, então um único handler de texto cobre respostas digitadas e toques. E uma resposta a uma mensagem específica traz reply_to.message_id: o mesmo id que você já tem para a mensagem citada (seu UUID do Fiwano ou o id do provedor que você recebeu), em todos os canais, para message.received e message.echo; uma resposta a story do Instagram traz reply_to.story. As prévias de link do Messenger não escondem mais o texto da mensagem, e o unsupported_type do WhatsApp agora nomeia o conteúdo real (edit, poll_creation, …). Docs: Recebendo Mensagens

Figurinhas (stickers) agora chegam da mesma forma nos três canais: como um evento image comum, então uma integração que já trata imagens as recebe sem código extra. No WhatsApp e no Facebook Messenger o evento vem marcado adicionalmente com media.sticker: true, e figurinhas do Messenger também trazem o media.sticker_id persistente da Meta; no Instagram uma figurinha não se distingue de uma imagem comum. Figurinhas também podem ser enviadas: media_type: "sticker" recebe um arquivo WebP no WhatsApp ou um sticker_id do catálogo da Meta no Messenger. O valor type: "sticker", exclusivo do WhatsApp, deixou de ser usado; se seu código o verificava, use media.sticker. Docs: Enviando Mensagens

Quando a Meta deixa de aceitar o acesso da Fiwano a uma conta conectada (o app foi removido nas configurações do Meta Business, uma permissão obrigatória foi revogada, ou a Página ou a conta do WhatsApp ficou indisponível), o canal agora é marcado como Needs reconnect no portal e o dono da conta recebe um e-mail. Nada é desfeito: o canal continua conectado, o tráfego de entrada e saída não é bloqueado, e a marcação some sozinha se o acesso voltar do lado da Meta. Reconectar é o mesmo fluxo de conexão para a mesma conta e agora funciona também para um canal ativo, mantendo seu channel_id, as configurações de webhook e o histórico. Docs: Canais

POST /api/v1/channels/setup-url agora diz exatamente o que está no caminho. 402 significa uma única coisa: a conta não tem assinatura ativa. Quando há assinaturas, mas todos os slots daquele tipo de canal estão ocupados, a resposta é 409 com detail.code no_free_slot e detail.occupied_by listando os canais que ocupam os slots, para você saber o que reconectar ou liberar. O fluxo de setup hospedado também devolve o resultado ao seu redirect URI: slot_occupied quando o usuário conectou uma conta Meta diferente da que ocupa o seu slot, access_denied quando ele cancelou, setup_failed para qualquer outro caso. Docs: Erros

Esta página. Novos recursos e melhorias relevantes, do mais recente ao mais antigo, com um feed Atom e uma cópia no GitHub.

status.fiwano.com: status ao vivo por componente, histórico de uptime e um registro de incidentes mantido em git público, para que eventos passados não possam ser reescritos em silêncio.

Conversas controladas por outro app via protocolo de handover da Meta são tratadas explicitamente: mensagens que chegam enquanto seu canal está em standby continuam sendo entregues como message.received, e um envio para essa conversa é recusado com uma dica acionável em vez de um erro genérico da Meta. Docs: Erros

message.echo entrega uma cópia das mensagens que sua empresa envia fora da Fiwano (app WhatsApp Business, caixa de entrada do Instagram, caixa de entrada da Página no Facebook, Meta Business Suite, outra integração), com status opcionais de entregue e lido para esses ecos. Opt-in por canal. Docs: Tipos de evento

Um número do WhatsApp, conta do Instagram ou Página já conectados em outra conta Fiwano são informados claramente no momento da conexão, com um caminho de contato, em vez de falhar em silêncio.

Os envios são cadenciados por canal para respeitar os limites da Meta. Quando um canal ou a plataforma está momentaneamente no limite, a API responde com uma dica explícita de nova tentativa (429 ou 503 com Retry-After) em vez de uma chamada rejeitada pela Meta. Docs: Enviando Mensagens

Nossa infraestrutura de alta disponibilidade foi reconstruída com meta de 99,99% de uptime: recuperação mais rápida e totalmente automática de falhas de componentes, com as mensagens recebidas preservadas o tempo todo.

As notificações de falha para donos de canal foram consolidadas em um único e-mail de resumo por canal, com o erro exato e o que fazer, em vez de um e-mail por evento.

Destinatários claramente inválidos são recusados antes de qualquer chamada à Meta, com o motivo específico na resposta. Docs: Enviando Mensagens

O endpoint de perfil do remetente retorna perfis mais completos no Messenger (nome e foto, quando a Meta os fornece), com fontes alternativas quando a consulta principal não está disponível. Docs: Perfil do remetente

Envios de template do WhatsApp recebem o mesmo ID de mensagem Fiwano e os mesmos eventos de status de entrega que mensagens livres. Docs: Templates

GET /subscriptions lista seus planos e slots de canal livres, para que uma integração verifique a capacidade antes de conectar um canal. Docs: Assinaturas

Conectar ficou mais conveniente e confiável quando um usuário do Facebook administra várias contas do Instagram ou Páginas: escolha a certa no diálogo da Meta em um único login, e a Fiwano resolve a seleção de ativos da Meta de forma confiável mesmo quando as contas mudam com o tempo. Docs: Canais

O cookbook da Fiwano: um playbook de integração passo a passo com a referência da API ao lado, escrito para agentes de código com IA e para pessoas.

Documentação reconstruída em páginas por tarefa, com Início Rápido, spec OpenAPI e referência interativa da API; também disponível como um único arquivo Markdown para agentes de IA. Docs

As conexões do Instagram e do Messenger migraram para o Facebook Login for Business da Meta: menos passos, seleção de ativos dentro do próprio diálogo da Meta. Qualquer canal pode ser reconectado no lugar: mesmo ID de canal, mesmas configurações de webhook, mesma licença. Docs: Canais

Envios de mídia são validados antes da chamada à Meta (URL, tipo) e retornam erros específicos em vez de uma falha genérica da Meta. Docs: Enviando Mensagens

Páginas localizadas para o Brasil (pt-BR, incluindo a documentação) e a Índia, com preços de referência em BRL e INR.

n8n-nodes-fiwano é um community node verificado pelo n8n: WhatsApp, Instagram e Messenger em workflows n8n sem código. Docs: n8n

Conecte um número do WhatsApp pelo fluxo oficial Embedded Signup da Meta em minutos: Cloud API, ou Coexistência para continuar usando o app WhatsApp Business junto com a API. Docs: Canais

O caminho de entrada dos webhooks foi reconstruído para maior throughput e menor latência de repasse da Meta até o seu endpoint.

Entregas de webhook e envios que falham são repetidos com backoff; o status de entrega é informado assim que o resultado é conhecido. Docs: Política de novas tentativas

Escolha quais eventos cada canal entrega (message.received, message.delivered, message.read e outros). Nada é entregue até você ativar. Docs: Tipos de evento

A Fiwano abre ao público: fiwano.com, cadastro self-service, licenças e cobrança. O contrato da API v1 fica congelado a partir deste ponto.

Terceiro canal atrás da mesma API: conecte uma Página do Facebook e receba e envie mensagens do Messenger com os mesmos formatos de requisição e webhook.

Os status enviado, entregue e lido chegam como eventos de webhook.

Crie, envie para aprovação e dispare templates do WhatsApp pelo portal e pela API.

Alguns integradores que conhecemos começam a construir sobre a API. Primeiro tráfego de produção fora da nossa própria plataforma.

A Fiwano se torna Meta Tech Provider: empresas conectam WhatsApp e Instagram pelo app verificado da Fiwano, sem app próprio na Meta nem app review.

Construída para a nossa própria plataforma de clientes: conversas do WhatsApp e do Instagram atrás de uma única interface.