NODAPI

Instancia

Conectar instância ao WhatsApp

POST/instance/connect
  • Informe phone para receber um código de pareamento; sem ele, a resposta traz o QR code.

Autenticação: envie a chave da conexão no header token ou em Authorization: Bearer.

Inicia o processo de conexão de uma instância ao WhatsApp. Este endpoint:

  1. Requer o token de autenticação da instância
  2. Recebe o número de telefone associado à conta WhatsApp
  3. Gera um QR code caso não passe o campo phone
  4. Ou Gera código de pareamento se passar o o campo phone
  5. Atualiza o status da instância para "connecting"

O processo de conexão permanece pendente até que:

  • O QR code seja escaneado no WhatsApp do celular, ou
  • O código de pareamento seja usado no WhatsApp
  • Timeout de 2 minutos para QRCode seja atingido ou 5 minutos para o código de pareamento

Use o endpoint /instance/status para monitorar o progresso da conexão.

Estados possíveis da instância:

  • disconnected: Desconectado do WhatsApp
  • connecting: Em processo de conexão
  • connected: Conectado e autenticado
  • hibernated: Sessão pausada, com credenciais preservadas para reconexão

Sincronização e armazenamento de mensagens:

  • Todas as mensagens recebidas da Meta durante a sincronização da conexão (leitura do QR code) são enviadas no evento history do webhook.
  • As mensagens dos últimos 7 dias são armazenadas no banco de dados e ficam acessíveis pelos endpoints: POST /message/find e POST /chat/find.
  • Depois que a instância conecta, todas as mensagens enviadas ou recebidas são armazenadas no banco de dados.
  • Mensagens mais antigas do que 7 dias são excluídas durante a madrugada.

Proxy regional:

  • No momento, o proxy regional público está disponível para Brasil (br).
  • O backend valida a combinação de país, estado e cidade antes de salvar.

Corpo da requisição (JSON)

CampoTipoDescrição
phonestring

Número de telefone no formato internacional (ex: 5511999999999). Se informado, gera código de pareamento. Se omitido, gera QR code.

Exemplo: 5511999999999

browserstring

Browser usado no ciclo de autenticação/conexão. auto preserva um perfil válido já salvo ou escolhe Safari, Firefox ou Edge para novas conexões.

Exemplo: auto

systemNamestring

Sistema/nome exibido no celular em aparelhos conectados. Ajuda a identificar a instância no WhatsApp; para maior estabilidade, recomendamos deixar em branco e usar o valor padrão do navegador escolhido.

Exemplo: Minha Empresa

* obrigatório

Exemplos de corpo

QR code com proxy regional em Campinas/SP

{
  "browser": "auto",
  "systemName": "Minha Empresa"
}

Respostas

  • 200Sucesso
  • 401Token inválido/expirado
  • 404Instância não encontrada
  • 429Limite de conexões simultâneas atingido
  • 500Erro interno
  • 503Capacidade de conexão temporariamente indisponível

Experimente

Atenção: a chamada é real. Ela roda na sua conexão e pode enviar mensagem de verdade. A chave fica só nesta tela e some ao sair dela; nunca é guardada.

Cole a chave gerada no painel.