Conexão

Para enviar e receber mensagens, a instância precisa estar conectada a um número de WhatsApp. Você conecta de duas formas: lendo um QR code ou digitando um código de pareamento no celular.

Nos exemplos, troque INSTANCIA_ID pelo identificador da instância e TOKEN pelo token dela.

Estados da instância

O campo connectionStatus, em GET /v1/instances/{instanceId}, mostra em que ponto a conexão está:

Estado	Significado
disconnected	Sem sessão. Chame POST /connect para começar
connecting	A conexão está sendo estabelecida
qr	Aguardando a leitura do QR code
connected	Conectada. O número aparece em phone

Conectar com QR code

Primeiro inicie a conexão:

curl -X POST https://api.zap.nigora.com.br/v1/instances/INSTANCIA_ID/connect \
  -H "Authorization: Bearer TOKEN"

A resposta é 202 com { "connectionStatus": "..." }. Ela só confirma que a conexão começou. Se a instância estiver suspensa ou com pagamento pendente, a API responde 402 com instance_suspended.

Depois busque o QR code:

curl https://api.zap.nigora.com.br/v1/instances/INSTANCIA_ID/qr \
  -H "Authorization: Bearer TOKEN"

A resposta traz:

Campo	Descrição
qr	O texto do QR code, ou null se ainda não há um disponível
image	O QR code como imagem PNG em data: URL, pronta para um <img>, ou null

O QR code troca a cada poucos segundos. Consulte de novo enquanto o estado for qr. No celular, abra o WhatsApp, vá em Aparelhos conectados e leia o código.

Se a instância já estiver conectada, a API responde 409 com already_connected.

Conectar com código de pareamento

Prefere não usar a câmera? Gere um código e digite no celular, em Aparelhos conectados e depois Conectar com número de telefone. A conexão precisa ter sido iniciada antes, com POST /connect.

curl -X POST https://api.zap.nigora.com.br/v1/instances/INSTANCIA_ID/pairing-code \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "5511999999999" }'

Envie o telefone do número que vai ser conectado, com DDI e DDD. A resposta é { "code": "..." }.

Status	Código	Quando
400	invalid_phone	O telefone não tem entre 12 e 13 dígitos (ou 10 a 11, sem o 55)
409	instance_not_connected	Não há sessão ativa: chame POST /connect antes

Saber quando conectou

Em vez de consultar a API em laço, configure os webhooks instance.connected e instance.disconnected. O primeiro traz o phone do número. O segundo traz reason e loggedOut.

Desconectar e reiniciar

Operação	Rota	O que faz
Desconectar	POST /disconnect	Encerra a sessão e desvincula o aparelho. Para voltar, será preciso ler um novo QR code. Responde { "ok": true }
Reiniciar	POST /restart	Reinicia a sessão sem desvincular o aparelho. Não pede novo QR code se as credenciais continuam válidas. Responde { "ok": true }