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

Início Rápido

O caminho rápido conecta suas próprias contas de WhatsApp, Instagram ou Facebook pelo portal — se você está construindo um serviço que conecta as contas dos seus clientes, veja a observação no passo 3.

1. Crie uma conta

Toda conta nova ganha um período de teste gratuito de 7 dias com funcionalidade completa — todos os tipos de canal, mídia e modelos, sem necessidade de cartão.

2. Crie uma chave de API

Abra API Keys no portal e crie uma chave. A chave completa (ela começa com mip_live_) é exibida apenas uma vez — guarde-a em local seguro. Toda requisição a leva no header X-API-Key.

3. Conecte um canal

No portal, vá em Channels → Connect Channel, escolha WhatsApp, Instagram ou Facebook Messenger e conclua o popup de login da Meta. Você recebe de volta um channel_id — guarde-o, toda chamada de envio e recebimento o utiliza. Os pré-requisitos (o ativo deve pertencer a um Meta Business Portfolio, e você deve ser admin dele) estão detalhados em Canais.

Construindo uma plataforma para seus clientes? Seu app conduz a conexão por conta própria, em vez do portal: cadastre um redirect URI na whitelist, solicite uma setup URL e então troque o code retornado por um channel_id. Esse é o fluxo de API em Canais → Via API. Os passos 1, 2, 4 e 5 são idênticos.

4. Receba uma mensagem

Quando um usuário escreve para o seu canal, o Fiwano envia um POST com um payload assinado para a sua Webhook URL. Defina a URL e escolha os Webhook Events no canal (nas configurações do canal no portal, ou via webhook_url / webhook_events pela API) — por padrão nenhum evento é entregue, então ative message.received. Verifique a assinatura X-Webhook-Signature (HMAC-SHA256 com o webhook_secret do canal) antes de confiar em um payload.

Um message.received recebido carrega os dois identificadores que você precisa para responder (destacados abaixo):

{
  "event": "message.received",
  "channel_id": "a1b2c3d4e5f67890",   // ← qual dos seus canais o recebeu
  "channel_type": "whatsapp",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "message_id": "wamid.xxx",
    "from": "1234567890",              // ← quem enviou — responda para este
    "from_name": "John Doe",
    "type": "text",
    "text": "Hello!"
  }
}
  • channel_id (nível superior) — o canal em que a mensagem chegou.
  • data.from — o id do remetente: número de telefone (WhatsApp), IGSID (Instagram) ou PSID (Facebook). É exatamente o que você passa de volta como recipient.

A lista completa de eventos, os payloads por canal e a verificação de assinatura estão em Recebendo Mensagens.

5. Responda a ela

Este é o movimento central: responda ao remetente devolvendo os mesmos identificadores — o channel_id do webhook como channel_id, e data.from como recipient:

curl -X POST https://fiwano.com/api/v1/messages/send \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"channel_id": "a1b2c3d4e5f67890", "recipient": "1234567890", "text": "Thanks for your message!"}'

A resposta carrega um message_id que você pode acompanhar pelos webhooks de status de entrega. Responder dentro de 24 horas da última mensagem do usuário é sempre em formato livre. Para abrir uma conversa do zero (fora dessa janela, somente WhatsApp) você usa um modelo aprovado — veja Enviando Mensagens e a janela de 24 horas em Capacidades.

Próximos passos

Documentação da API Fiwano