Get in Touch

Have a question about the platform, need help with your integration, or want to discuss partnership opportunities and enterprise pricing? Drop us an email — we’ll do our best to get back to you within 3–4 hours.

contact@fiwano.com
Menu da documentação

Trabalhando com um agente de IA? Baixe a documentação completa como arquivo Markdown para usar como contexto.

Baixar .md completo

WhatsApp, Instagram e Messenger em Apps Criados com IA

Você está criando um app no Lovable, Bolt, Replit, Base44, v0, Emergent, Rocket ou Hercules, e ele precisa conversar com as pessoas onde elas já estão: WhatsApp, Instagram Direct e Facebook Messenger. Este guia mostra como adicionar os três canais com a Fiwano, o que pedir ao seu construtor e os poucos detalhes de cada plataforma que decidem se os webhooks chegam.

O que os construtores oferecem por conta própria

Alguns construtores já têm uma opção de mensagens. Verifique primeiro — se ela atende o seu caso, você não precisa de mais nada. Em outubro de 2026:

  • Lovable tem um conector de WhatsApp Business: um número comercial por conexão, sem Instagram nem Messenger, e sem forma de os clientes do seu app conectarem os números deles.
  • Base44 pode colocar um agente de IA do app no WhatsApp, em um número que a Base44 atribui ao agente, e não no número da sua empresa.
  • Replit, Rocket e Emergent oferecem Twilio (SMS, e WhatsApp via Twilio no Emergent). Os conectores de Instagram do Replit e do Rocket leem posts e feeds, não mensagens diretas.

Quando a Fiwano faz sentido

  • Os três canais em uma API — WhatsApp, Instagram Direct e Messenger chegam em um único formato de webhook e são respondidos com uma única chamada de envio.
  • Seus clientes conectam as próprias contas. Se você está criando um SaaS, cada cliente pode conectar o próprio número de WhatsApp, conta do Instagram ou Página do Facebook por um fluxo hospedado, e o seu app recebe um channel_id para ela. Veja Canais.
  • Seu próprio número e marca, sem app de desenvolvedor Meta para criar ou aprovar — a Fiwano é Tech Provider verificada da Meta.

Como a integração funciona

Todo construtor produz as mesmas quatro peças. A versão passo a passo com os payloads está no Início Rápido.

  1. Chave de API como segredo do backend. Crie uma chave no portal da Fiwano e guarde-a nos segredos do construtor, nunca em uma variável que chega ao navegador (como VITE_… ou NEXT_PUBLIC_…). Envie-a no header X-API-Key, ou como Authorization: Bearer se a ferramenta só aceitar bearer token.
  2. Um canal conectado. Conecte no portal, ou deixe seus clientes conectarem os deles pela API.
  3. Um receptor de webhooks. Uma função de backend com URL HTTPS pública. Defina-a como webhook_url do canal e ative message.received em webhook_events — a entrega é opt-in. Verifique a X-Webhook-Signature, responda 200 na hora e processe depois; veja a política de novas tentativas.
  4. Respostas a partir do backend. POST /api/v1/messages/send com o channel_id do webhook e data.from como recipient.

A Fiwano não guarda histórico de mensagens. Se o seu app mostra conversas, salve as mensagens recebidas e enviadas no seu próprio banco de dados.

Um prompt para colar no seu construtor

Uma frase basta — o contrato completo da API e dos webhooks está no llms-full.txt, escrito para agentes de IA:

Add WhatsApp, Instagram and Messenger messaging to this app with Fiwano, following https://fiwano.com/llms-full.txt.

O prompt está em inglês de propósito: a documentação da API é em inglês. Quando o construtor pedir a chave de API, informe-a como segredo. Depois, defina a URL do endpoint de webhook que ele criou como webhook do canal no portal da Fiwano e envie uma mensagem de teste do seu celular.

Notas por plataforma

Construtor Onde roda o código de backend URL do webhook Atenção
Lovable Edge functions (Lovable Cloud) A URL da função (Cloud → Edge functions → Copy URL) Edge functions exigem JWT por padrão e recusam webhooks com 401 antes de o seu código rodar. Peça ao Lovable para desativar a verificação de JWT da função do webhook — a verificação de assinatura é a autenticação dela
Bolt Server functions (Bolt Cloud) ou Supabase Edge Functions A URL da função No Supabase, a mesma configuração de JWT do Lovable
Replit O servidor do seu app A URL do deployment (*.replit.app) Aponte o webhook para o deployment, não para o preview do workspace
Base44 Backend functions (Deno) https://<domínio-do-seu-app>/functions/<nome> Chamadas de webhook não têm sessão de usuário — a função lê e grava dados como service role
v0 / Vercel Route handlers do Next.js Seu domínio de produção Deployments de preview ficam atrás da proteção de deployment da Vercel e respondem aos webhooks com 401
Hercules Backend Convex Uma rota de API pública Rode o trabalho lento em uma função agendada, não dentro da requisição
Emergent, Rocket O backend do app ou Supabase Edge Functions A URL do endpoint Guarde a chave de API nos segredos da plataforma

Em plataformas serverless, "processar em segundo plano" significa usar o mecanismo da própria plataforma — por exemplo EdgeRuntime.waitUntil() nas Supabase Edge Functions ou waitUntil() na Vercel. Trabalho iniciado sem ele pode parar quando a resposta é enviada.

Conectando pelo conector do construtor

Vários construtores permitem registrar uma API REST externa uma vez e reutilizá-la entre projetos. Isso facilita chamar a Fiwano; para receber mensagens, o endpoint de webhook acima continua necessário.

  • Lovable — custom connector (admin do workspace): URL base da API https://fiwano.com, chave de API em um header personalizado X-API-Key, requisição de teste GET /api/v1/channels. Adicione o Início Rápido como arquivo de conhecimento.
  • Base44 — workspace integration: importe a especificação OpenAPI de https://fiwano.com/api/v1/openapi.json e defina o header X-API-Key.
  • Replit — custom connector: escolha autenticação por bearer token e cole sua chave de API.
  • Rocket — importação de API: importe a mesma URL do OpenAPI.

Se algo não funcionar

  • "Blocked by CORS policy" ou "Failed to fetch" no navegador — a chamada está rodando no código do frontend. Mova-a para uma função de backend.
  • Nenhum webhook chega — confira se message.received está ativado no canal e se o endpoint responde 2xx (um 401 da plataforma, por JWT ou proteção de preview, parece silêncio do seu lado). A Fiwano envia um e-mail após falhas repetidas de entrega.
  • O bot responde duas vezes — o handler esperou a resposta da IA antes de responder, então o webhook foi reenviado. Responda primeiro, processe depois e deduplique por message_id.

Usa n8n? Veja Integração n8n. Comparando abordagens em geral? Veja Formas de Conectar.

Perguntas frequentes

Posso adicionar WhatsApp a um app criado com Lovable, Bolt ou Replit?

Sim. Guarde a chave de API da Fiwano como segredo do backend, chame a API a partir de uma função de backend e receba as mensagens em um endpoint de webhook público. O guia traz um prompt para colar no seu construtor.

Os clientes do meu app podem conectar o próprio WhatsApp ou Instagram?

Sim. Seu backend solicita um link de setup, o cliente conecta o próprio número de WhatsApp, conta do Instagram ou Página do Facebook em um fluxo hospedado, e o seu app recebe um channel_id para ela.

Preciso de um app de desenvolvedor Meta para usar WhatsApp no meu app criado com IA?

Não. A Fiwano é Tech Provider verificada da Meta, então você conecta canais sem criar nem aprovar o seu próprio app Meta.

Por que os webhooks da Fiwano não chegam à minha função do Lovable ou do Supabase?

As Supabase Edge Functions, usadas pelo Lovable Cloud, exigem JWT por padrão e respondem aos webhooks com 401. Desative a verificação de JWT da função do webhook; a verificação da X-Webhook-Signature autentica a requisição.