> ## 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. # Iniciar Sessão > Inicia a conexão com o WhatsApp via QR Code, Pair Code ou Link de conexão # 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 ``` ```json theme={null} { "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`: ```json theme={null} { "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: ```html theme={null} 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 ``` ```json theme={null} { "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`: ```json theme={null} { "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 ``` ```json theme={null} { "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`: ```json theme={null} { "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 Envie o comando `SESSION_START_QR_CODE`, `SESSION_START_PAIR_CODE` ou `SESSION_START_LINK` para o endpoint. Receba o webhook com o QR Code (imagem Base64), o Pair Code (código alfanumérico) ou o link de conexão (URL). O usuário escaneia o QR Code, digita o Pair Code ou abre o link de conexão no WhatsApp do celular. 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: Erro ao iniciar a sessão. ```json theme={null} { "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 | Erro específico do processo de pareamento (Pair Code). ```json theme={null} { "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 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. 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`). 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. ```json theme={null} { "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. ```json theme={null} { "packageId": null, "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "content": { "type": "DISCONNECTED" } } ``` Uma desconexão pode ocorrer por diversos motivos: comando de [Desconectar](/comandos/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. ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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`. ```json theme={null} { "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). ```json theme={null} { "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. ```json theme={null} { "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. ```json theme={null} { "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](/comandos/importar-sessao): o `sessionData` pode ser reimportado para restaurar a conexão sem novo pareamento. ```json theme={null} { "packageId": null, "channelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "content": { "type": "DEVICE_SESSION_BACKUP", "sessionData": "" } } ``` | 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) ```bash cURL 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": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "content": { "type": "SESSION_START_QR_CODE", "commandType": "SESSION_START_QR_CODE", "enableHistoryOnConnect": true, "historyMessageLimit": 50 } }' ``` ```python Python theme={null} 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()) ``` ```javascript Node.js theme={null} 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](/comandos/status) periodicamente como health check complementar.