Canais

Um canal é um ativo Meta conectado — um número de WhatsApp, uma conta do Instagram ou uma Página do Facebook — pelo qual você envia e recebe mensagens. Esta página cobre como conectar, gerenciar e reconectar canais.

Para o schema exato de request/response de cada endpoint de canal (campos, tipos, códigos de status), veja a Referência da API. Esta página é o guia em nível de tarefa; ela não repete as tabelas de campos.

Pré-requisitos

Antes de conectar qualquer canal — WhatsApp, Instagram ou Facebook Messenger — garanta que ambas as condições abaixo sejam atendidas. Elas valem igualmente para o fluxo do Portal e o fluxo da API; se alguma faltar, a Meta interrompe o popup de OAuth antes que um canal possa ser criado.

O ativo pertence a um Meta Business Portfolio (Business Manager). O "ativo" é a WABA do número de WhatsApp, a Página do Facebook ou — no caso do Instagram — uma conta do Instagram Business ou Creator vinculada a uma Página do Facebook que seja de propriedade de um Business Portfolio.
O usuário do Facebook que faz login tem direitos completos de admin nesse Business Portfolio e no próprio ativo. Um usuário sem papel de admin vê a opção relevante desabilitada no popup.

Opção A: Via Portal (self-service)

Use isto para conectar seus próprios canais, sem necessidade de código.

Vá em Channels → Connect Channel no portal.
Selecione o tipo de canal (WhatsApp, Instagram ou Facebook Messenger).
Conclua o fluxo de OAuth da Meta na janela popup.
Configure a Webhook URL e selecione os Webhook Events nas configurações do canal.
Por padrão, nenhum evento está habilitado — selecione quais eventos encaminhar ao seu endpoint.

Definir uma webhook URL no Portal não cria um webhook_secret. Defina um explicitamente para que as entregas recebidas sejam assinadas — veja Segredo do webhook. A URL deve ser uma URL HTTPS absoluta e acessível pela Fiwano.

Opção B: Via API (programática)

Use isto quando sua aplicação conecta canais em nome dos seus usuários finais.

Passo 1 — Cadastre seu redirect URI na whitelist. Por segurança, o usuário só pode ser redirecionado de volta a uma URL que você tenha pré-registrado para a sua chave de API. Registre a(s) URL(s) onde os usuários chegam após o OAuth (coringas são permitidos, ex.: https://*.example.com/callback):

curl -X POST https://fiwano.com/api/v1/redirects \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"uri_pattern": "https://yourapp.com/callback"}'

Os padrões de redirect URI devem usar HTTPS e não podem apontar para localhost nem para um endereço de loopback literal.

Você os gerencia com GET /api/v1/redirects e DELETE /api/v1/redirects/{id}.

Passo 2 — Solicite uma setup URL. Passe um dos seus redirect URIs da whitelist. A URL é válida até o expires_at retornado na resposta — abra-a em um navegador ou popup para o usuário:

curl -X POST https://fiwano.com/api/v1/channels/setup-url \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel_type": "whatsapp", "redirect_uri": "https://yourapp.com/callback"}'

O mesmo endpoint também reconecta canais; não existe uma API de reconnect separada. Se a identidade da Meta já pertencer a um canal inativo seu, a Fiwano reativa essa mesma linha e exchange-code retorna o channel_id existente. Quando um asset realmente novo e um asset inativo estão disponíveis ao mesmo tempo, o asset novo tem prioridade.

Passo 3 — O usuário conclui o OAuth da Meta. Após a aprovação, o usuário é redirecionado ao seu redirect_uri com um parâmetro code de uso único:

https://yourapp.com/callback?code=abc123...

Em caso de falha, o redirect leva dois query params — ramifique sua lógica apenas no error:

Query param	Como usar
`error`	Código legível por máquina. Ramifique nisto. `access_denied` — o usuário cancelou o diálogo da Meta. `setup_failed` — o setup não pôde ser concluído (ex.: nenhuma conta do Instagram Business estava acessível com as permissões concedidas).
`message`	Explicação legível por humanos em inglês, codificada em URL, segura para exibir ao usuário. Formato livre e pode mudar — nunca faça parse ou ramifique no texto dela.

Exemplo de redirect de falha:

https://yourapp.com/callback?error=setup_failed&message=We%20couldn%27t%20access%20any%20Instagram%20Business%20account...

Passo 4 — Troque o code. Em até 5 minutos (uso único), troque o code pelo canal. Você pode configurar o webhook na mesma chamada:

curl -X POST https://fiwano.com/api/v1/channels/exchange-code \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "abc123...",
    "webhook_url": "https://yourapp.com/webhooks/meta",
    "webhook_events": ["message.received", "message.delivered", "message.failed"]
  }'

A resposta retorna seu channel_id (guarde-o — toda outra chamada o utiliza). Quando você define webhook_url e não fornece um webhook_secret, a Fiwano gera um automaticamente e o retorna aqui. Ele é retornado apenas nesta resposta — o GET nunca o mostra de novo — então guarde-o para verificar as assinaturas dos webhooks (Segredo do webhook). Todos os campos exceto code são opcionais e podem ser definidos depois via PATCH /api/v1/channels/{id}.

Eventos de webhook

A entrega de webhooks é opt-in por canal: por padrão nenhum evento é entregue. Você escolhe o que recebe definindo webhook_events — na chamada de conexão, no Portal, ou depois via PATCH /api/v1/channels/{id}. Até fazer isso, seu endpoint não recebe nada.

Os eventos disponíveis dependem do tipo de canal — o WhatsApp expõe mais (message.sent, message.failed) do que Instagram e Facebook. A lista completa com os payloads está na página de Webhooks. Um evento que você listar e que não seja válido para o tipo de canal é simplesmente ignorado, não é um erro.

Seu endpoint cumpre a outra metade desse contrato. Uma vez habilitados os eventos, a Fiwano faz POST de cada um para seu webhook_url, e seu endpoint precisa responder com HTTP 2xx em até ~5 segundos. Uma resposta não-2xx ou um timeout conta como entrega falha: a Fiwano tenta novamente com backoff e envia e-mail para você — um aviso após a 3ª tentativa falha e um alerta quando as tentativas se esgotam. Por isso, habilite apenas os eventos que você realmente trata e retorne 2xx assim que aceitar o payload (faça o trabalho mais lento depois). Mensagens recebidas são salvas do nosso lado mesmo se o relay falhar. Comportamento completo de entrega e retentativas: Webhooks → Política de novas tentativas.

Segredo do webhook

O webhook_secret é a chave HMAC que a Fiwano usa para assinar as entregas de webhook, para que seu endpoint possa confirmar que a requisição realmente veio da Fiwano e não foi alterada no caminho. Quando um canal tem um segredo, cada entrega traz um cabeçalho X-Webhook-Signature: sha256=<hmac> — veja Webhooks para o trecho de verificação. Um canal sem segredo recebe entregas sem assinatura.

Como um segredo aparece pela primeira vez difere conforme você conecta — e este é o único ponto em que o Portal e a API se comportam propositalmente de forma diferente:

Portal (Opção A): um canal novo não tem segredo, e salvar uma webhook URL não cria um. Defina-o você mesmo nas configurações do canal: clique em Generate random para um segredo aleatório de 64 caracteres, ou digite o seu próprio e clique em Save (mínimo de 16 caracteres). O valor é revelado uma única vez, logo em seguida.
API (Opção B): quando você define webhook_url e o canal ainda não tem segredo, a Fiwano gera um automaticamente (hex de 64 caracteres) e o retorna na resposta de exchange-code / PATCH /api/v1/channels/{id} — ou seja, canais conectados via API são assinados por padrão. Para usar um valor específico, forneça o seu próprio webhook_secret nessa mesma chamada.

Lendo de volta. O valor só é retornado no momento em que é definido ou alterado — na revelação única do Portal, ou nas respostas de exchange-code e PATCH /api/v1/channels/{id}. GET /api/v1/channels e GET /api/v1/channels/{id} nunca o retornam; eles apenas informam has_webhook_secret: true | false. Guarde o valor quando ele for exibido — se você o perder, a única opção é definir um novo.

Rotacionando. Defina um novo segredo a qualquer momento fornecendo um novo webhook_secret ao PATCH /api/v1/channels/{id}, ou com as ações Generate random / Save do Portal. Atualizar apenas webhook_url/webhook_events mantém o segredo intacto. A mudança tem efeito na próxima entrega — não há janela de sobreposição, então troque seu verificador para o novo segredo no mesmo momento, ou as assinaturas não vão corresponder.

Restrições e recomendações.

Use uma string aleatória de alta entropia com 16–64 caracteres (o Portal exige o mínimo de 16 caracteres; o campo armazena até 64). Segredos gerados automaticamente têm 64 caracteres hex — prefira-os, a menos que tenha um motivo para usar o seu próprio.
O segredo é por canal — cada canal tem o seu, independente dos demais.
Reconectar um canal inativo mantém o segredo existente (veja Reconectando um canal inativo abaixo).
Trate-o como uma senha: armazene-o em um gerenciador de segredos, nunca o inclua no controle de versão e verifique as assinaturas usando comparação de tempo constante (como no exemplo de Webhooks).

Gerenciando canais

Tarefa	Endpoint
Listar todos os canais (ativos e inativos), cada um com seu estado de assinatura atual	`GET /api/v1/channels`
Inspecionar um canal	`GET /api/v1/channels/{id}`
Atualizar webhook URL / secret / events	`PATCH /api/v1/channels/{id}`
Desativar um canal	`DELETE /api/v1/channels/{id}`

Cada canal traz um bloco subscription descrevendo seu estado de cobrança — veja Assinaturas e Cobrança para o que as combinações significam. As listas completas de campos estão na Referência da API.

A desativação é um soft delete. O DELETE impede o canal de enviar e receber, mas não o apaga — seu channel_id e histórico são preservados para que você possa reconectar depois. O canal também continua pertencendo à mesma conta Fiwano: a desativação não libera seu número do WhatsApp, conta do Instagram ou Página do Facebook para conexão com outra conta Fiwano. Se o canal precisar ser movido entre contas, entre em contato com contact@fiwano.com.

O Fiwano também cancela a inscrição do recurso de webhook da Meta do canal apenas quando é seguro: uma inscrição de WABA é mantida se outro canal de WhatsApp ativo usar a mesma WABA, e uma inscrição de Página é mantida se outro canal de Instagram/Facebook ativo usar a mesma Página.

Reconectando um canal inativo

Um canal fica inativo quando é desativado (DELETE /api/v1/channels/{id}) ou quando sua conexão com a Meta não pode mais ser mantida (por exemplo, o dono da conta revogou o acesso na Meta). Para trazê-lo de volta, execute o mesmo fluxo de conexão novamente para a mesma conta Meta (mesmo número de WhatsApp, conta do Instagram ou Página do Facebook):

O canal existente é reativado no lugar — seu channel_id, webhook URL/secret/events e histórico são preservados. Nenhum canal novo é criado e o seu mapeamento de channel_id armazenado continua válido.
A reconexão exige uma licença ativa: o canal ainda deve ter uma, ou você deve ter um slot de licença livre. Caso contrário, o fluxo é recusado — vincule uma licença em Billing primeiro.
Uma conta Meta pertencente a outra conta Fiwano não pode ser conectada, mesmo quando o canal estiver inativo. Se o canal for seu, entre em contato com contact@fiwano.com para solicitar a liberação da titularidade.