Trabalhando com um agente de IA? Baixe a documentação completa como arquivo Markdown para usar como contexto.
Baixar .md completoUm 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.
Antes de conectar qualquer canal — WhatsApp, Instagram ou Facebook Messenger — garanta que as condições abaixo sejam atendidas. Elas valem igualmente para o fluxo do Portal e o fluxo da API; se uma das duas primeiras faltar, a Meta interrompe o popup de OAuth antes que um canal possa ser criado.
10.Use isto para conectar seus próprios canais, sem necessidade de código.
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. Portas explícitas
de 1 a 65535 são suportadas; credenciais embutidas e fragmentos de URL não são.
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. Portas explícitas de 1 a 65535 são suportadas,
inclusive portas HTTPS não padrão, como https://yourapp.com:4426/callback. URIs
exatos são mais seguros e recomendados. Quando um curinga for necessário, ele pode
aparecer no caminho/query ou como um rótulo completo mais à esquerda do hostname
(*.example.com), mas não pode substituir todo o hostname, parte de um rótulo ou
a porta. Credenciais embutidas, fragmentos de URL e as chaves de query reservadas
code, status, channel_type e error são rejeitados.
Para associar um fluxo de setup ao tenant ou administrador autenticado, gere um
nonce opaco, de alta entropia e uso único, armazene-o no servidor junto com esse
contexto e coloque somente o nonce no redirect URI. Cadastre um padrão restrito,
como https://yourapp.com/callback?state=*, e solicite a setup URL com
https://yourapp.com/callback?state=NONCE_BASE64URL. A Fiwano preserva state e
acrescenta seus próprios parâmetros, por exemplo
?state=NONCE_BASE64URL&code=...&status=success&channel_type=whatsapp. Use um
valor URL-safe e não coloque IDs de tenant/usuário nem outros dados sensíveis
diretamente na URI.
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}.
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.
Um evento tem um ajuste extra: message.echo (cópias de mensagens que sua empresa envia
fora da Fiwano) entrega apenas a mensagem por padrão. Defina o campo booleano
echo_statuses do canal — na chamada de conexão, via PATCH /api/v1/channels/{id} ou no
Portal — para receber também os status delivered/read das mensagens ecoadas pelos seus
eventos de status habituais. Detalhes: message.echo.
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). Payloads de webhook entregues com sucesso não são retidos
para repasse; falhas são armazenadas de forma criptografada para novas tentativas. Comportamento completo:
Webhooks → Política de novas tentativas.
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:
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 (no máximo 64 caracteres) 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.
| 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, ou o vínculo de assinatura | 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.
Cada assinatura concede um slot por tipo de canal — um WhatsApp, um Instagram, um Facebook. Um slot permanece ocupado enquanto um canal estiver vinculado a ele, inclusive um canal desativado: é esse vínculo que permite reconectar aquele canal depois sem comprar outra assinatura.
GET /api/v1/subscriptions mostra qual canal ocupa cada slot e quantos estão
livres; cada canal, por sua vez, informa seu próprio subscription.id.
Envie subscription_id em PATCH /api/v1/channels/{channel_id} para mudar isso.
Um ID de assinatura move o canal para lá — sem indisponibilidade, e ele não
precisa ser desativado antes, mas mover para uma assinatura Starter interrompe o
envio de mídia e de templates imediatamente. Uma string vazia libera o slot, e
isso só é permitido para um canal já desativado com
DELETE /api/v1/channels/{channel_id}, de modo que um slot nunca é liberado como
efeito colateral de uma atualização de configuração.
Liberar um slot é, na prática, permanente. Assim que outro canal ocupar o slot liberado, o canal liberado não poderá mais ser reconectado até que haja um slot livre novamente. Ele não é apagado e sua identidade Meta continua pertencendo à sua conta Fiwano — mas trate a liberação como aposentar aquele canal, não como pausá-lo.
Substituindo um canal quando você tem apenas uma assinatura:
GET /api/v1/subscriptions → encontre a assinatura e seu slot ocupado
DELETE /api/v1/channels/{old_id} → desative o canal que será substituído
PATCH /api/v1/channels/{old_id} → {"subscription_id": ""} libera o slot
POST /api/v1/channels/setup-url → usuário conecta a nova conta Meta
POST /api/v1/channels/exchange-code → novo canal ocupa o slot livre
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):
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.contact@fiwano.com para solicitar a liberação da titularidade.