> ## Documentation Index
> Fetch the complete documentation index at: https://docs.messagefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introdução

> Canais são a ponte entre a sua aplicação e os provedores de mensageria — entenda os tipos, o ciclo de vida e como gerenciá-los.

# 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.

<Note>
  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.
</Note>

## 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.

<CardGroup cols={2}>
  <Card title="Criar canal de WhatsApp" icon="plus" href="/api-reference/criar-canal">
    Cria um novo canal vinculado a um número de WhatsApp.
  </Card>

  <Card title="Iniciar Sessão" icon="qrcode" href="/comandos/iniciar-sessao">
    QR Code, Pair Code ou link de conexão para autenticar o número no WhatsApp.
  </Card>

  <Card title="Importar Sessão" icon="file-import" href="/comandos/importar-sessao">
    Importa uma sessão já autenticada (contorno para números com passkey).
  </Card>

  <Card title="Confirmar Passkey" icon="key" href="/comandos/confirmar-passkey">
    Responde à verificação por passkey exigida pelo WhatsApp.
  </Card>

  <Card title="Status do Canal" icon="signal" href="/comandos/status">
    Consulta o estado atual da conexão.
  </Card>

  <Card title="Desconectar" icon="power-off" href="/comandos/desconectar">
    Encerra a sessão do WhatsApp do canal.
  </Card>
</CardGroup>

### 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.

<CardGroup cols={2}>
  <Card title="Criar canal de Webhook" icon="webhook" href="/api-reference/criar-canal">
    Configura uma URL que receberá os eventos do MessageFy.
  </Card>

  <Card title="Recebendo Eventos" icon="bell" href="/recebendo-eventos">
    Como configurar seu endpoint, validar assinaturas e processar payloads.
  </Card>
</CardGroup>

<Tip>
  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.
</Tip>

## Ciclo de vida de um canal

<Steps>
  <Step title="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.
  </Step>

  <Step title="Autenticação (somente WhatsApp)">
    Para canais de WhatsApp, escolha um método de conexão:
    [`SESSION_START_QR_CODE`](/comandos/iniciar-sessao),
    [`SESSION_START_PAIR_CODE`](/comandos/iniciar-sessao) ou
    [`SESSION_START_LINK`](/comandos/iniciar-sessao) — em todos o usuário confirma a vinculação no
    celular. Para números que exigem verificação por *passkey*, use
    [`SESSION_IMPORT`](/comandos/importar-sessao) para importar uma sessão já autenticada e responda
    à verificação com [`PASSKEY_CONFIRM`](/comandos/confirmar-passkey). Você recebe um evento
    `CONNECTED` quando a sessão está pronta.
  </Step>

  <Step title="Operação">
    Com o canal ativo, envie mensagens, comandos e receba webhooks normalmente. Para canais de
    HTTP Sender, acompanhe os envios pelo [Outbox](/canais/outbox).
  </Step>

  <Step title="Atualização ou Deleção">
    Atualize configurações ([`PUT /api/v1/Admin/Channel/{id}`](/api-reference/atualizar-canal)) ou
    delete o canal ([`DELETE /api/v1/Admin/Channel/{id}`](/api-reference/deletar-canal)) quando ele
    não for mais necessário. A deleção é assíncrona — o evento
    [`CHANNEL_DELETION_COMPLETED`](/recebendo-eventos#administracao) sinaliza a conclusão.
  </Step>
</Steps>

## Operações disponíveis

<CardGroup cols={2}>
  <Card title="Listar canais" icon="list" href="/api-reference/listar-canais">
    Consulta todos os canais sob a sua gestão, com filtros e paginação.
  </Card>

  <Card title="Buscar por ID" icon="magnifying-glass" href="/api-reference/obter-canal">
    Recupera os detalhes de um canal específico.
  </Card>

  <Card title="Criar canal" icon="plus" href="/api-reference/criar-canal">
    Cria um canal de WhatsApp ou Webhook.
  </Card>

  <Card title="Atualizar canal" icon="pen" href="/api-reference/atualizar-canal">
    Modifica configurações de um canal existente.
  </Card>

  <Card title="Deletar canal" icon="trash" href="/api-reference/deletar-canal">
    Remove um canal (assíncrono — escute `CHANNEL_DELETION_COMPLETED`).
  </Card>

  <Card title="Transferir canal" icon="arrow-right-arrow-left" href="/canais/transferencia">
    Move um canal de WhatsApp entre *accounts* da mesma *organization*.
  </Card>
</CardGroup>

## Boas práticas

<AccordionGroup>
  <Accordion title="Use um canal de feedback dedicado para cada canal de WhatsApp">
    Configurar um canal de Webhook como *feedback* do seu canal de WhatsApp centraliza o
    recebimento de eventos e permite que o [Outbox](/canais/outbox) correlato funcione corretamente.
    Sem isso, eventos como `CHANNEL_DELETION_COMPLETED` não têm para onde ser entregues.
  </Accordion>

  <Accordion title="Monitore os eventos CONNECTED e SESSION_EXPIRED">
    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`](/comandos/iniciar-sessao#session_expired)
    e dispare uma nova autenticação automaticamente.
  </Accordion>

  <Accordion title="Não dependa do retorno HTTP para confirmar o envio">
    A API responde `200 OK` ao receber o pedido, mas o envio real é assíncrono. Use os eventos
    [`MESSAGE_SENT` / `MESSAGE_DELIVERED` / `MESSAGE_READ`](/recebendo-eventos) para acompanhar o
    ciclo de vida de cada mensagem.
  </Accordion>

  <Accordion title="Use o outbox como audit log e ferramenta de recovery">
    Mesmo que o seu sistema tenha sua própria fila local, o [Outbox](/canais/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.
  </Accordion>
</AccordionGroup>