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

# Quick Start

> Envie sua primeira mensagem em 5 minutos

# Quick Start

Este guia mostra como configurar o MessageFy e enviar sua primeira mensagem WhatsApp.

<Note>
  Você precisa de acesso ao painel administrativo ou a uma API Key já configurada.
  Se ainda não tem, entre em contato com o suporte.
</Note>

## Como o fluxo funciona

A **Organization** (nível mais alto de agrupamento) é criada automaticamente no seu cadastro.
Dentro dela você cria **Accounts**, e cada Account contém seus **canais**. Neste guia você vai:

1. Criar uma **Account** (que já vem com uma API Key `acc_` própria).
2. Criar um canal de **Webhook** (`http-sender`) para receber os eventos.
3. Criar um canal de **WhatsApp** (`whatsapp-web`) apontando o feedback para o canal de Webhook.
4. Conectar o WhatsApp.
5. Enviar a primeira mensagem.

## Passo a Passo

<Steps>
  <Step title="Crie uma Account">
    A Account é o agrupamento onde vivem os seus canais. Ela é criada dentro da Organization
    (que já existe desde o seu cadastro).

    ```bash theme={null}
    curl -X POST https://api-dev.messagefy.io/api/v1/Admin/Account \
      -H "Content-Type: application/json" \
      -H "X-API-KEY: sua-api-key" \
      -d '{
        "name": "Minha Empresa",
        "description": "Account principal"
      }'
    ```

    <Note>
      Ao criar uma Account, uma **API Key exclusiva com prefixo `acc_`** é gerada automaticamente
      para ela. É essa chave que você deve usar no header `X-API-KEY` dos próximos passos.
      Veja mais em [Administrando API Keys](/api-keys/introducao).
    </Note>

    <Tip>
      Se você já tem uma Account e a respectiva chave `acc_`, pule para o passo 2.
    </Tip>
  </Step>

  <Step title="Crie o canal de Webhook (http-sender)">
    O canal de **Webhook** é um canal separado, do tipo `http-sender`, responsável por **entregar
    os eventos** (mensagens recebidas, status de envio, mudanças de conexão) à sua aplicação.
    A URL de destino vai em `parameters.url`.

    ```bash theme={null}
    curl -X POST https://api-dev.messagefy.io/api/v1/Admin/Channel \
      -H "Content-Type: application/json" \
      -H "X-API-KEY: sua-api-key" \
      -d '{
        "name": "Webhook de Eventos",
        "channelType": "http-sender",
        "accountId": "uuid-da-sua-account",
        "parameters": {
          "url": "https://sua-app.com/webhook"
        }
      }'
    ```

    Anote o `channelId` retornado — ele será o **feedback channel** do canal de WhatsApp no próximo passo.
  </Step>

  <Step title="Crie o canal de WhatsApp (whatsapp-web)">
    O canal de WhatsApp não-oficial usa o tipo `whatsapp-web` (provider `whatsmeow`). Ele **não**
    recebe uma URL de webhook diretamente: os eventos são entregues através do canal `http-sender`
    criado antes, referenciado em `feedbackChannelId`. O `parameters` fica vazio (`{}`).

    ```bash theme={null}
    curl -X POST https://api-dev.messagefy.io/api/v1/Admin/Channel \
      -H "Content-Type: application/json" \
      -H "X-API-KEY: sua-api-key" \
      -d '{
        "name": "WhatsApp Vendas",
        "channelType": "whatsapp-web",
        "accountId": "uuid-da-sua-account",
        "feedbackChannelId": "channel-id-do-webhook",
        "parameters": {}
      }'
    ```

    Anote o `channelId` deste canal `whatsapp-web` — é ele que você vai usar para conectar e enviar mensagens.
  </Step>

  <Step title="Conecte o WhatsApp">
    Inicie uma sessão via QR Code:

    ```bash theme={null}
    curl -X POST https://api-dev.messagefy.io/api/v1/message/SendCommand \
      -H "Content-Type: application/json" \
      -H "X-API-KEY: sua-api-key" \
      -d '{
        "channelId": "channel-id-do-whatsapp-web",
        "content": {
          "type": "SESSION_START_QR_CODE",
          "commandType": "SESSION_START_QR_CODE"
        }
      }'
    ```

    Você receberá um webhook `GENERATE_QR_CODE_RESPONSE` com o QR Code em base64.
    Escaneie com o WhatsApp do celular. Após conectar, você receberá um webhook `CONNECTED`.

    <Tip>
      Além do QR Code, existem outros métodos de conexão — todos detalhados em
      [Iniciar Sessão](/comandos/iniciar-sessao):

      * **Pair Code** (`SESSION_START_PAIR_CODE`) — código de pareamento digitado no celular.
      * **Link de conexão** (`SESSION_START_LINK`) — retorna um `connectionLink` para o usuário abrir.
      * **Importar Sessão** ([`SESSION_IMPORT`](/comandos/importar-sessao)) — importa uma sessão
        `web.whatsapp.com` já autenticada, sem pareamento. É o contorno recomendado para números que
        exigem verificação por **passkey**, resolvida com [`PASSKEY_CONFIRM`](/comandos/confirmar-passkey).
    </Tip>
  </Step>

  <Step title="Envie sua primeira mensagem">
    ```bash theme={null}
    curl -X POST https://api-dev.messagefy.io/api/v1/message/SendMessage \
      -H "Content-Type: application/json" \
      -H "X-API-KEY: sua-api-key" \
      -d '{
        "channelId": "channel-id-do-whatsapp-web",
        "content": {
          "type": "TEXT",
          "to": {
            "type": "WHATSAPP",
            "number": "5511999999999"
          },
          "text": "Olá! Esta é minha primeira mensagem via MessageFy 🎉"
        }
      }'
    ```

    Resposta:

    ```json theme={null}
    {
      "packageId": "550e8400-e29b-41d4-a716-446655440000"
    }
    ```

    O `packageId` é o identificador de rastreamento do envio. Você receberá webhooks de status:

    * `MESSAGE_SENT` — mensagem aceita pelo WhatsApp
    * `MESSAGE_DELIVERED` — entregue no dispositivo
    * `MESSAGE_READ` — lida pelo destinatário
  </Step>
</Steps>

## Recebendo Mensagens

Para testar rapidamente o recebimento de webhooks, use o [webhook.site](https://webhook.site) —
ele gera uma URL temporária que exibe todas as requisições recebidas em tempo real.

<Steps>
  <Step title="Acesse webhook.site">
    Abra [webhook.site](https://webhook.site). Uma URL única será gerada automaticamente
    (ex: `https://webhook.site/abc123-def456-...`).
  </Step>

  <Step title="Configure no canal de Webhook">
    Use essa URL como `parameters.url` ao criar (ou atualizar) o seu canal `http-sender`, e aponte
    o `feedbackChannelId` do canal `whatsapp-web` para ele.
  </Step>

  <Step title="Visualize os eventos">
    Envie uma mensagem ou conecte uma sessão — os webhooks aparecerão na página do webhook.site
    com o payload JSON completo.
  </Step>
</Steps>

<Tip>
  Para ambientes de produção, implemente seu próprio endpoint seguindo o guia
  [Recebendo Eventos](/recebendo-eventos), que detalha o envelope do webhook e todos os eventos.
</Tip>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Tipos de Mensagem" icon="message" href="/mensagens/visao-geral">
    Envie imagens, documentos, áudio, vídeo e mais.
  </Card>

  <Card title="Comandos" icon="terminal" href="/comandos/visao-geral">
    Consulte status, contatos, grupos e gerencie sessões.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/recebendo-eventos">
    Entenda todos os eventos que você pode receber.
  </Card>

  <Card title="Referência API" icon="code" href="/api-reference/visao-geral">
    Documentação técnica completa de todos os endpoints.
  </Card>
</CardGroup>