Quick Start

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

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.

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:

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

Passo a Passo

Crie uma Account

A Account é o agrupamento onde vivem os seus canais. Ela é criada dentro da Organization (que já existe desde o seu cadastro).

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"
  }'

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.

Se você já tem uma Account e a respectiva chave acc_, pule para o passo 2.

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.

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.

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 ({}).

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.

Conecte o WhatsApp

Inicie uma sessão via QR Code:

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.

Além do QR Code, existem outros métodos de conexão — todos detalhados em Iniciar Sessão:

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) — 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.

Envie sua primeira mensagem

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:

{
  "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

Recebendo Mensagens

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

Acesse webhook.site

Abra webhook.site. Uma URL única será gerada automaticamente (ex: https://webhook.site/abc123-def456-...).

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.

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.

Para ambientes de produção, implemente seu próprio endpoint seguindo o guia Recebendo Eventos, que detalha o envelope do webhook e todos os eventos.

Próximos Passos

Tipos de Mensagem

Envie imagens, documentos, áudio, vídeo e mais.

Comandos

Consulte status, contatos, grupos e gerencie sessões.

Webhooks

Entenda todos os eventos que você pode receber.

Referência API

Documentação técnica completa de todos os endpoints.

Início

Contas

API Keys

Canais

WhatsApp Oficial

Tipos de Mensagem

Operações de Mensagem

Sessão e Conexão

Consultas

Interação

Quick Start

Quick Start

Como o fluxo funciona

Passo a Passo

Recebendo Mensagens

Próximos Passos

Tipos de Mensagem

Comandos

Webhooks

Referência API

​Quick Start

​Como o fluxo funciona

​Passo a Passo

​Recebendo Mensagens

​Próximos Passos

Tipos de Mensagem

Comandos

Webhooks

Referência API

Quick Start

Como o fluxo funciona

Passo a Passo

Recebendo Mensagens

Próximos Passos