Iniciar Sessão

O comando Iniciar Sessão conecta o canal ao WhatsApp. Existem três métodos de autenticação: QR Code, Pair Code e Link de conexão. Em todos os casos, o usuário precisa confirmar a conexão no celular.

Método 1: QR Code

Gera um QR Code que deve ser escaneado pelo WhatsApp no celular do usuário.

Requisição

POST /api/v1/message/SendCommand

{
  "channelId": "uuid-do-canal",
  "content": {
    "type": "SESSION_START_QR_CODE",
    "commandType": "SESSION_START_QR_CODE",
    "enableHistoryOnConnect": false,
    "historyMessageLimit": 100,
    "historyDateLimit": "2026-03-25"
  }
}

Campos

Campo	Tipo	Obrigatório	Descrição
`enableHistoryOnConnect`	`boolean`	Não	Se `true`, sincroniza o histórico de mensagens ao conectar. Padrão: `false`
`historyMessageLimit`	`integer`	Não	Limite máximo de mensagens a sincronizar por conversa
`historyDateLimit`	`string` (data `AAAA-MM-DD`)	Não	Data limite para sincronizar mensagens (nao sincroniza anteriores a está data). Ex.: `2026-03-25`

Webhook de resposta

O QR Code é entregue via webhook GENERATE_QR_CODE_RESPONSE:

{
  "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "channelId": "uuid-do-canal",
  "content": {
    "type": "GENERATE_QR_CODE_RESPONSE",
    "success": true,
    "qrCode": "iVBORw0KGgoAAAANSUhEUgAA...",
    "automatic": false
  }
}

Campo	Tipo	Descrição
`success`	`boolean`	Se o QR Code foi gerado com sucesso
`qrCode`	`string`	Imagem do QR Code codificada em Base64 (formato PNG)
`automatic`	`boolean`	Se `true`, o QR Code foi gerado automaticamente pelo sistema (renovacao)

Como exibir o QR Code

O campo qrCode contém a imagem PNG codificada em Base64. Para exibir em uma página web:

<img src="data:image/png;base64,{qrCode}" alt="QR Code WhatsApp" />

O QR Code expira em aproximadamente 60 segundos. Se não for escaneado a tempo, um novo QR Code será gerado automaticamente é enviado via webhook (com automatic: true). Atualize a imagem exibida sempre que receber um novo webhook. Após varias tentativas sem sucesso, um webhook SESSION_START_ERROR será enviado.

Método 2: Pair Code

Gera um código numérico de 8 dígitos que o usuário digita manualmente no WhatsApp.

Requisição

POST /api/v1/message/SendCommand

{
  "channelId": "uuid-do-canal",
  "content": {
    "type": "SESSION_START_PAIR_CODE",
    "commandType": "SESSION_START_PAIR_CODE",
    "mobileNumber": "5511999887766",
    "enableHistoryOnConnect": false,
    "historyMessageLimit": 100,
    "historyDateLimit": "2026-03-25"
  }
}

Campos

Campo	Tipo	Obrigatório	Descrição
`mobileNumber`	`string`	Sim	Número do celular com código do país (sem `+`, sem espacos)
`enableHistoryOnConnect`	`boolean`	Sim	Se `true`, sincroniza o histórico de mensagens ao conectar
`historyMessageLimit`	`integer`	Não	Limite máximo de mensagens a sincronizar por conversa
`historyDateLimit`	`string` (data `AAAA-MM-DD`)	Não	Data limite para sincronizar mensagens. Ex.: `2026-03-25`

Webhook de resposta

O Pair Code é entregue via webhook PAIR_CODE_GENERATED_RESPONSE:

{
  "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "channelId": "uuid-do-canal",
  "content": {
    "type": "PAIR_CODE_GENERATED_RESPONSE",
    "success": true,
    "pairCode": "A1B2-C3D4"
  }
}

Campo	Tipo	Descrição
`success`	`boolean`	Se o Pair Code foi gerado com sucesso
`pairCode`	`string`	Código de 8 caracteres (formato `XXXX-XXXX`) para digitar no WhatsApp

O usuário deve abrir o WhatsApp no celular, ir em Dispositivos conectados > Conectar dispositivo > Vincular por número de telefone e digitar o código.

Método 3: Link de conexão

Gera um link de conexão que pode ser aberto pelo próprio usuário para autorizar o dispositivo, sem que você precise renderizar um QR Code ou exibir um código na sua interface.

Requisição

POST /api/v1/message/SendCommand

{
  "channelId": "uuid-do-canal",
  "content": {
    "type": "SESSION_START_LINK",
    "commandType": "SESSION_START_LINK",
    "financialManagerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Campos

Campo	Tipo	Obrigatório	Descrição
`financialManagerId`	`string` (UUID)	Não	Identificador do gestor financeiro associado à conexão

Webhook de resposta

O link é entregue via webhook SESSION_START_LINK_GENERATED_RESPONSE:

{
  "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "channelId": "uuid-do-canal",
  "content": {
    "type": "SESSION_START_LINK_GENERATED_RESPONSE",
    "success": true,
    "connectionLink": "https://api-dev.messagefy.io/connect/3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Campo	Tipo	Descrição
`success`	`boolean`	Se o link foi gerado com sucesso
`connectionLink`	`string`	URL de conexão a ser aberta pelo usuário para autorizar o dispositivo

Fluxo de autenticação

Enviar comando

Envie o comando SESSION_START_QR_CODE, SESSION_START_PAIR_CODE ou SESSION_START_LINK para o endpoint.

Receber resposta

Receba o webhook com o QR Code (imagem Base64), o Pair Code (código alfanumérico) ou o link de conexão (URL).

Autenticar no celular

O usuário escaneia o QR Code, digita o Pair Code ou abre o link de conexão no WhatsApp do celular.

Conexão confirmada

Após a autenticação, você receberá um webhook CONNECTED confirmando a conexão.

Webhooks de erro

Em caso de falha na autenticação, você receberá um dos seguintes webhooks:

SESSION_START_ERROR

Erro ao iniciar a sessão.

{
  "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "channelId": "uuid-do-canal",
  "content": {
    "type": "SESSION_START_ERROR",
    "error": true,
    "mode": "QR_CODE",
    "message": "Timeout ao aguardar escaneamento do QR Code"
  }
}

Campo	Tipo	Descrição
`error`	`boolean`	Sempre `true`
`mode`	`string`	Método de autenticação que falhou: `QR_CODE` ou `PAIR_CODE`
`message`	`string`	Descrição do erro

PAIRING_ERROR

Erro específico do processo de pareamento (Pair Code).

{
  "packageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "channelId": "uuid-do-canal",
  "content": {
    "type": "PAIRING_ERROR",
    "error": true,
    "message": "Numero de telefone invalido ou nao registrado no WhatsApp"
  }
}

Campo	Tipo	Descrição
`error`	`boolean`	Sempre `true`
`message`	`string`	Descrição do erro de pareamento

Erros comuns

QR Code expirou varias vezes

O usuário não escaneou o QR Code dentro do tempo limite. Após varias tentativas, um SESSION_START_ERROR será enviado. Envie o comando novamente para reiniciar o processo.

Número inválido no Pair Code

O número informado no comando SESSION_START_PAIR_CODE não está registrado no WhatsApp ou está em formato incorreto. Verifique se o número inclui o código do país (ex: 5511999887766).

Dispositivo já conectado

Se o WhatsApp já está conectado a outro dispositivo com o mesmo número, a sessão anterior será encerrada automaticamente.

Eventos do ciclo de vida da conexão

Após iniciar a sessão, você receberá webhooks sobre o estado da conexão. Esses eventos sao essenciais para monitorar a saúde da sessão e reagir a desconexoes.

CONNECTED

Enviado quando o canal se conecta ao WhatsApp com sucesso.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "CONNECTED",
    "jid": "5511999887766@s.whatsapp.net",
    "lid": "12345678901234:56@lid",
    "phoneNumber": "5511999887766"
  }
}

Campo	Tipo	Descrição
`jid`	`string`	JID do dispositivo conectado
`lid`	`string`	LID do dispositivo conectado
`phoneNumber`	`string`	Número de telefone do dispositivo

DISCONNECTED

Enviado quando o canal se desconecta do WhatsApp.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "DISCONNECTED"
  }
}

Uma desconexão pode ocorrer por diversos motivos: comando de Desconectar, perda de conexão com a internet, ou o usuário desvinculou o dispositivo pelo WhatsApp.

SESSION_EXPIRED

Enviado quando a sessão do WhatsApp expira e não pode ser reconectada automaticamente. Uma nova autenticação (QR Code ou Pair Code) será necessária.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "SESSION_EXPIRED",
    "reason": "Sessao revogada pelo usuario no WhatsApp"
  }
}

Campo	Tipo	Descrição
`reason`	`string`	Motivo da expiracao da sessão

Após receber SESSION_EXPIRED, o canal não pode mais enviar ou receber mensagens. Você deve iniciar uma nova sessão enviando o comando SESSION_START_QR_CODE, SESSION_START_PAIR_CODE ou SESSION_START_LINK novamente.

INSTANCE_START

Enviado quando a instância do canal e iniciada no servidor.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "INSTANCE_START"
  }
}

INSTANCE_STOP

Enviado quando a instância do canal e parada no servidor.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "INSTANCE_STOP"
  }
}

INSTANCE_USER_CONNECT_TIMEOUT

Enviado quando a instância aguardou o usuário conectar (via QR Code ou Pair Code) mas o tempo limite foi atingido sem autenticação.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "INSTANCE_USER_CONNECT_TIMEOUT"
  }
}

Após este evento, você pode enviar novamente o comando SESSION_START_QR_CODE, SESSION_START_PAIR_CODE ou SESSION_START_LINK para gerar uma nova autenticação.

HISTORY_SYNC_PROGRESS

Enviado periodicamente durante a sincronização do histórico de mensagens, indicando o progresso da operação. Só é emitido quando o SESSION_START_* foi enviado com enableHistoryOnConnect: true.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "HISTORY_SYNC_PROGRESS",
    "syncType": "MESSAGES",
    "progress": 42,
    "chunkOrder": 3,
    "totalConversations": 120,
    "totalMessages": 5000,
    "totalProcessed": 2100,
    "totalErrors": 0,
    "durationMs": 12450
  }
}

Campo	Tipo	Descrição
`syncType`	`string`	Tipo de sincronização em andamento (ex: `MESSAGES`)
`progress`	`integer`	Percentual aproximado (0–100) processado até agora
`chunkOrder`	`integer`	Ordem do lote atual sendo processado
`totalConversations`	`integer`	Total de conversas a sincronizar
`totalMessages`	`integer`	Total de mensagens a sincronizar
`totalProcessed`	`integer`	Total de mensagens já processadas
`totalErrors`	`integer`	Erros encontrados durante o processamento
`durationMs`	`number`	Duração acumulada da sincronização, em milissegundos

Para históricos grandes, este evento pode chegar dezenas de vezes. Use-o para atualizar uma barra de progresso na sua aplicação se quiser feedback visual.

HISTORY_SYNC_COMPLETED

Enviado quando a sincronização do histórico de mensagens termina (com sucesso ou não).

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "HISTORY_SYNC_COMPLETED",
    "syncType": "MESSAGES",
    "totalConversations": 120,
    "totalMessages": 5000,
    "totalProcessed": 4998,
    "totalErrors": 2,
    "durationMs": 45230
  }
}

Campo	Tipo	Descrição
`syncType`	`string`	Tipo de sincronização concluída
`totalConversations`	`integer`	Total de conversas sincronizadas
`totalMessages`	`integer`	Total de mensagens sincronizadas
`totalProcessed`	`integer`	Total efetivamente processado
`totalErrors`	`integer`	Erros encontrados
`durationMs`	`number`	Duração total, em milissegundos

Compare totalProcessed com totalMessages para detectar sincronizações parciais. totalErrors > 0 indica que algumas mensagens não foram importadas.

OFFLINE_SYNC_COMPLETED

Enviado quando a sincronização de mensagens recebidas enquanto o dispositivo estava offline termina. Acontece logo após o CONNECTED, antes que novas mensagens em tempo real comecem a fluir.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "OFFLINE_SYNC_COMPLETED",
    "count": 27
  }
}

Campo	Tipo	Descrição
`count`	`integer`	Quantidade de mensagens offline sincronizadas

APP_STATE_SYNC_COMPLETED

Enviado quando uma das coleções de estado do app (lista de conversas, contatos, configurações, etc.) termina de sincronizar. Pode ocorrer múltiplas vezes — uma por coleção.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "APP_STATE_SYNC_COMPLETED",
    "name": "regular"
  }
}

Campo	Tipo	Descrição
`name`	`string`	Nome da coleção sincronizada (ex: `regular`, `critical_block`, `critical_unblock_low`)

DEVICE_SESSION_BACKUP

Enviado quando o MessageFy exporta um snapshot completo da sessão do dispositivo. É o par de backup da Importação de Sessão: o sessionData pode ser reimportado para restaurar a conexão sem novo pareamento.

{
  "packageId": null,
  "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "content": {
    "type": "DEVICE_SESSION_BACKUP",
    "sessionData": "<blob completo da sessao>"
  }
}

Campo	Tipo	Descrição
`sessionData`	`string`	Blob completo da sessão autenticada. Trate como conteúdo opaco — não tente parsear.

O sessionData contém as credenciais brutas da sessão do WhatsApp, com acesso total à conta. Trate-o como segredo: trafegue somente sobre TLS, nunca registre em logs e evite persistir no cliente sem criptografia. Vazar esse blob equivale a entregar o acesso completo do dispositivo.

Diagrama do fluxo de conexão

O diagrama abaixo mostra o ciclo de vida completo de uma conexão, desde a autenticação ate possiveis desconexoes e reconexoes:

Comando SESSION_START_QR_CODE / SESSION_START_PAIR_CODE / SESSION_START_LINK
    |
    v
GENERATE_QR_CODE_RESPONSE / PAIR_CODE_GENERATED_RESPONSE / SESSION_START_LINK_GENERATED_RESPONSE
    |
    +--> [Usuario escaneia QR / digita codigo / abre link]
    |       |
    |       +--> CONNECTED (sucesso!)
    |               |
    |               +--> DISCONNECTED (desconexao temporaria)
    |               |       |
    |               |       +--> CONNECTED (reconexao automatica)
    |               |
    |               +--> SESSION_EXPIRED (sessao expirada)
    |                       |
    |                       +--> [Requer novo SESSION_START_*]
    |
    +--> [QR Code expira]
    |       |
    |       +--> GENERATE_QR_CODE_RESPONSE (automatic: true)
    |               |
    |               +--> [Repete ate timeout]
    |                       |
    |                       +--> SESSION_START_ERROR
    |
    +--> [Erro no pareamento]
    |       |
    |       +--> PAIRING_ERROR
    |
    +--> INSTANCE_USER_CONNECT_TIMEOUT (timeout sem autenticacao)
    |
    v
INSTANCE_STOP

Exemplo completo (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": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "content": {
      "type": "SESSION_START_QR_CODE",
      "commandType": "SESSION_START_QR_CODE",
      "enableHistoryOnConnect": true,
      "historyMessageLimit": 50
    }
  }'

import requests

response = requests.post(
    "https://api-dev.messagefy.io/api/v1/message/SendCommand",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "sua-api-key"
    },
    json={
        "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "content": {
            "type": "SESSION_START_QR_CODE",
            "commandType": "SESSION_START_QR_CODE",
            "enableHistoryOnConnect": True,
            "historyMessageLimit": 50
        }
    }
)

print(response.json())

const response = await fetch(
  "https://api-dev.messagefy.io/api/v1/message/SendCommand",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "sua-api-key",
    },
    body: JSON.stringify({
      channelId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      content: {
        type: "SESSION_START_QR_CODE",
        commandType: "SESSION_START_QR_CODE",
        enableHistoryOnConnect: true,
        historyMessageLimit: 50,
      },
    }),
  }
);

const data = await response.json();
console.log(data);

Para a maioria dos casos de uso com integração automatizada, o método Pair Code é mais prático, pois não exige renderizar uma imagem QR Code na sua interface. Basta exibir o código alfanumérico.

Implemente um mecanismo de monitoramento que reage ao SESSION_EXPIRED para notificar o operador que uma nova autenticação e necessária. Use o comando Status periodicamente como health check complementar.

​Iniciar Sessão

​Método 1: QR Code

​Requisição

​Campos

​Webhook de resposta

​Como exibir o QR Code

​Método 2: Pair Code

​Requisição

​Campos

​Webhook de resposta

​Método 3: Link de conexão

​Requisição

​Campos

​Webhook de resposta

​Fluxo de autenticação

​Webhooks de erro

​Erros comuns

​Eventos do ciclo de vida da conexão

​CONNECTED

​DISCONNECTED

​SESSION_EXPIRED

​INSTANCE_START

​INSTANCE_STOP

​INSTANCE_USER_CONNECT_TIMEOUT

​HISTORY_SYNC_PROGRESS

​HISTORY_SYNC_COMPLETED

​OFFLINE_SYNC_COMPLETED

​APP_STATE_SYNC_COMPLETED

​DEVICE_SESSION_BACKUP

​Diagrama do fluxo de conexão

​Exemplo completo (QR Code)

Iniciar Sessão

Método 1: QR Code

Requisição

Campos

Webhook de resposta

Como exibir o QR Code

Método 2: Pair Code

Requisição

Campos

Webhook de resposta

Método 3: Link de conexão

Requisição

Campos

Webhook de resposta

Fluxo de autenticação

Webhooks de erro

Erros comuns

Eventos do ciclo de vida da conexão

CONNECTED

DISCONNECTED

SESSION_EXPIRED

INSTANCE_START

INSTANCE_STOP

INSTANCE_USER_CONNECT_TIMEOUT

HISTORY_SYNC_PROGRESS

HISTORY_SYNC_COMPLETED

OFFLINE_SYNC_COMPLETED

APP_STATE_SYNC_COMPLETED

DEVICE_SESSION_BACKUP

Diagrama do fluxo de conexão

Exemplo completo (QR Code)