Instancia
Conectar instância ao WhatsApp
/instance/connectInforme
phonepara 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:
- Requer o token de autenticação da instância
- Recebe o número de telefone associado à conta WhatsApp
- Gera um QR code caso não passe o campo
phone - Ou Gera código de pareamento se passar o o campo
phone - 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 WhatsAppconnecting: Em processo de conexãoconnected: Conectado e autenticadohibernated: 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
historydo webhook. - As mensagens dos últimos 7 dias são armazenadas no banco de dados e ficam acessíveis pelos endpoints:
POST /message/findePOST /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)
| Campo | Tipo | Descrição |
|---|---|---|
| phone | string | Número de telefone no formato internacional (ex: 5511999999999). Se informado, gera código de pareamento. Se omitido, gera QR code. Exemplo: 5511999999999 |
| browser | string | Browser usado no ciclo de autenticação/conexão. Exemplo: auto |
| systemName | string | 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.