Início Rápido

A Fiwano coloca WhatsApp, Instagram e Messenger atrás de uma única REST API. Este é o ciclo central em quatro passos — autenticar, conectar um canal, receber uma mensagem, responder — mais um quinto opcional para enviar mensagens fora da janela de 24 horas. Toda requisição usa a base URL https://fiwano.com e leva sua chave no header X-API-Key.

1. Obtenha e verifique sua chave de API

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. Abra API Keys no portal e crie uma chave: a chave completa é exibida apenas uma vez, começa com mip_live_ e é armazenada somente como hash — chaves perdidas não podem ser recuperadas, então revogue e recrie se preciso. Guarde-a em uma variável de ambiente (ex.: FIWANO_API_KEY); nunca a deixe fixa no código nem a comite.

Verifique se a chave funciona listando os canais:

curl https://fiwano.com/api/v1/channels -H "X-API-Key: $FIWANO_API_KEY"

Uma chave válida em uma conta nova (ainda sem canais) retorna 200 com uma lista vazia — esse é o sinal de sucesso de que você está autenticado e pronto para o passo 2:

{ "channels": [], "total": 0 }

Uma chave inválida ou ausente retorna 401. Formatos de erro e códigos de status: Erros.

2. Conecte um canal

Há duas formas de conectar — escolha a que combina com quem é o dono da conta, ambas detalhadas em Canais:

Seu próprio canal — conecte-o no portal (Channels → Connect), sem código. Melhor quando você mesmo opera as contas. Os pré-requisitos (o ativo deve pertencer a um Meta Business Portfolio, e você deve ser admin dele) estão detalhados lá.
Os canais dos seus usuários finais — um fluxo OAuth incorporado que seu app conduz: cadastre um redirect_uri na whitelist, crie uma setup URL, o usuário conclui o login da Meta dentro dela, e você troca o code retornado (de uso único) por um channel_id.

Operações OpenAPI deste passo:

Gerenciar canais: GET /api/v1/channels, GET /api/v1/channels/{channel_id}, PATCH /api/v1/channels/{channel_id}, DELETE /api/v1/channels/{channel_id}
Fluxo de conexão incorporado: POST /api/v1/channels/setup-url, POST /api/v1/channels/exchange-code
Whitelist de redirect URI: GET /api/v1/redirects, POST /api/v1/redirects, DELETE /api/v1/redirects/{redirect_id}

Sucesso: você tem um channel_id (o fluxo incorporado o retorna direto do exchange-code), e GET /api/v1/channels agora lista o canal com "is_active": true — ele pode enviar e receber. Esse channel_id é o que você passa em toda chamada de envio e recebimento daqui em diante.

3. Receba uma mensagem

Responder mensagens recebidas é o caso de uso central da Fiwano, então configure o recebimento antes do envio. Duas partes:

1. Ative os eventos no canal. A entrega é opt-in — por padrão nenhum evento é entregue. Defina webhook_events (e uma webhook_url) no canal e ative apenas os eventos que você realmente trata (comece por message.received). A lista de eventos por canal e como configurá-la estão em Canais.

2. Trate o webhook. A Fiwano envia um POST de cada evento ativado para a sua webhook_url. Seu endpoint deve verificar a X-Webhook-Signature (HMAC-SHA256 com o webhook_secret do canal) e responder HTTP 2xx em ~5 segundos — caso contrário a Fiwano tenta novamente com backoff e envia um e-mail. Os formatos de payload e a verificação de assinatura estão em Recebendo Mensagens.

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 partir de um handler, você também costuma chamar:

PATCH /api/v1/channels/{channel_id} — define ou atualiza webhook_events / webhook_url
GET /api/v1/media/{media_id} — baixa a mídia recebida
GET /api/v1/channels/{channel_id}/profile/{user_id} — consulta o perfil do remetente

Sucesso: mande uma mensagem para o seu canal conectado de um aparelho real; seu endpoint recebe um webhook message.received com assinatura válida e retorna 2xx. Você já está recebendo.

4. Responda a ela

Com o recebimento no lugar, faça o envio. O caso do dia a dia é uma resposta em formato livre dentro da janela de 24 horas depois que um usuário te escreve — texto ou mídia, sem aprovação. 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!"}'

Enviar: POST /api/v1/messages/send (texto), POST /api/v1/messages/send-media (mídia)

Sucesso: a chamada retorna uma mensagem aceita com um message_id; se você ativou os eventos de entrega no passo 3, você então recebe os webhooks message.sent / message.delivered acompanhando-a. Leia Enviando Mensagens para mídia e mais.

Isso cobre o ciclo central — conectar, receber, responder. O passo 5 é opcional.

5. Modelos do WhatsApp — mensagens fora da janela de 24 horas (opcional)

Mensagens em formato livre só alcançam um usuário dentro da janela de 24 horas. Para iniciar uma conversa, ou para responder depois que a janela fechou, o WhatsApp exige um modelo (template) pré-aprovado (somente WhatsApp). Pule este passo se você sempre responde dentro da janela — veja a janela de 24 horas em Capacidades.

Leia Modelos do WhatsApp para o ciclo de criação/revisão e então envie o modelo aprovado.

Enviar um modelo: POST /api/v1/messages/send-template
Gerenciar modelos: GET /api/v1/channels/{channel_id}/templates, POST /api/v1/channels/{channel_id}/templates, GET|PUT|DELETE /api/v1/channels/{channel_id}/templates/{template_id}

Próximos passos

Sem código? Use o node n8n verificado — mesmos canais, mesmos eventos, arrastar e soltar.
Mídia e modelos — Enviando Mensagens.
Limites, janelas e planos — Capacidades.
O contrato completo legível por máquina — Referência da API.