Skip to main content

​
Administrando Canais

Os canais são o coração da comunicação na plataforma MessageFy. Um canal representa a ponte entre a sua aplicação e um serviço de mensageria (como o WhatsApp) ou um sistema de notificação (como um Webhook). É através de um canal que você envia e recebe mensagens. Antes de qualquer comunicação, configure pelo menos um canal — atualmente suportamos dois tipos, identificados pela chave channelType: Canal de WhatsApp (whatsapp-web) e Canal de Webhook (http-sender).

​
Mas afinal o que é um canal?

Tecnicamente, um canal é um container dentro da nossa infraestrutura, dedicado a prover um ambiente para a conexão do seu número (no caso do WhatsApp) ou para encaminhar eventos para a sua URL (no caso do Webhook). Cada canal corresponde a um único número ou destino. Se você precisa operar com mais números, crie mais canais — cada um vive em isolamento, com sua própria sessão, sua própria fila de mensagens e seu próprio histórico.
O MessageFy abstrai as particularidades de cada provedor (WhatsApp, HTTP genérico) atrás de uma API unificada. Você manipula um “canal” — internamente nós cuidamos da sessão, reconexão, sincronização e entrega.

​
Tipos de canal

​
Canal de WhatsApp

Identificado pelo channelType whatsapp-web, permite conectar um número de WhatsApp para enviar e receber mensagens diretamente pela nossa API. A conexão pode ser estabelecida por quatro métodos: QR Code, Pair Code, link de conexão ou importação de uma sessão já autenticada (contorno para números que exigem verificação por passkey). A partir da conexão, o canal fica disponível para envio e recebimento de mensagens em tempo real.

Criar canal de WhatsApp

Cria um novo canal vinculado a um número de WhatsApp.

Iniciar Sessão

QR Code, Pair Code ou link de conexão para autenticar o número no WhatsApp.

Importar Sessão

Importa uma sessão já autenticada (contorno para números com passkey).

Confirmar Passkey

Responde à verificação por passkey exigida pelo WhatsApp.

Status do Canal

Consulta o estado atual da conexão.

Desconectar

Encerra a sessão do WhatsApp do canal.

​
Canal de Webhook

Identificado pelo channelType http-sender, é utilizado para receber notificações em tempo real sobre eventos: novas mensagens, atualizações de status de envio, mudanças de conexão. O endereço de destino é informado em parameters.url na criação do canal, e o MessageFy envia um HTTP POST para essa URL sempre que um evento relevante ocorre.

Criar canal de Webhook

Configura uma URL que receberá os eventos do MessageFy.

Recebendo Eventos

Como configurar seu endpoint, validar assinaturas e processar payloads.
Todo canal de WhatsApp pode ter um canal de Webhook associado como feedback channel, que é onde os eventos do WhatsApp (mensagens recebidas, status, etc.) são entregues. Configure ambos para receber as notificações da sua operação.

​
Ciclo de vida de um canal

1

Criação

Você cria o canal informando o tipo (WhatsApp ou Webhook) e suas configurações iniciais. O canal começa em estado inativo, aguardando configuração.
2

Autenticação (somente WhatsApp)

Para canais de WhatsApp, escolha um método de conexão: SESSION_START_QR_CODE, SESSION_START_PAIR_CODE ou SESSION_START_LINK — em todos o usuário confirma a vinculação no celular. Para números que exigem verificação por passkey, use SESSION_IMPORT para importar uma sessão já autenticada e responda à verificação com PASSKEY_CONFIRM. Você recebe um evento CONNECTED quando a sessão está pronta.
3

Operação

Com o canal ativo, envie mensagens, comandos e receba webhooks normalmente. Para canais de HTTP Sender, acompanhe os envios pelo Outbox.
4

Atualização ou Deleção

Atualize configurações (PUT /api/v1/Admin/Channel/{id}) ou delete o canal (DELETE /api/v1/Admin/Channel/{id}) quando ele não for mais necessário. A deleção é assíncrona — o evento CHANNEL_DELETION_COMPLETED sinaliza a conclusão.

​
Operações disponíveis

Listar canais

Consulta todos os canais sob a sua gestão, com filtros e paginação.

Buscar por ID

Recupera os detalhes de um canal específico.

Criar canal

Cria um canal de WhatsApp ou Webhook.

Atualizar canal

Modifica configurações de um canal existente.

Deletar canal

Remove um canal (assíncrono — escute CHANNEL_DELETION_COMPLETED).

Transferir canal

Move um canal de WhatsApp entre accounts da mesma organization.

​
Boas práticas

Configurar um canal de Webhook como feedback do seu canal de WhatsApp centraliza o recebimento de eventos e permite que o Outbox correlato funcione corretamente. Sem isso, eventos como CHANNEL_DELETION_COMPLETED não têm para onde ser entregues.
A conexão do WhatsApp pode cair por motivos diversos (rede, desvinculação pelo usuário, expiração de sessão). Mantenha um monitor que reaja a SESSION_EXPIRED e dispare uma nova autenticação automaticamente.
A API responde 200 OK ao receber o pedido, mas o envio real é assíncrono. Use os eventos MESSAGE_SENT / MESSAGE_DELIVERED / MESSAGE_READ para acompanhar o ciclo de vida de cada mensagem.
Mesmo que o seu sistema tenha sua própria fila local, o Outbox do MessageFy registra todas as tentativas de entrega com request/response completos. Em incidentes, ele é frequentemente a fonte de verdade mais rápida para entender o que aconteceu.