Conectar o número ao WhatsApp por código de pareamento

Objetivo

Ao final, o número do celular estará conectado à sua instância, sem precisar ler um QR code. Útil quando você não tem como apontar a câmera para a tela, por exemplo ao configurar tudo pelo próprio celular.

Pré-requisitos

• Uma instância criada no painel, com o ID e o token (Primeiros passos).
• O celular com o WhatsApp instalado e o número que será conectado.
• curl no terminal.

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

1. Inicie a conexão

O código de pareamento só existe depois que a conexão começa:

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

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

2. Peça o código

Envie o telefone do número que vai ser conectado, com DDI e DDD:

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" }'

Resultado esperado:

{ "code": "ABCD-1234" }

O código será outro, com 8 caracteres. Se a API demorar alguns segundos, é normal: ela espera a conexão ficar pronta antes de gerar o código.

3. Digite o código no celular

No celular:

1. Abra o WhatsApp.
2. Vá em Aparelhos conectados.
3. Toque em Conectar com número de telefone.
4. Digite o código do passo anterior.

Se o WhatsApp recusar o código, repita o passo 2 para pedir outro.

4. Confirme a conexão

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

Resultado esperado, com o connectionStatus em connected e o número em phone:

{ "connectionStatus": "connected", "phone": "5511999999999" }

A resposta real traz outros campos da instância. Enquanto o estado não for connected, consulte de novo em alguns segundos. Para ser avisado sem consultar, configure o webhook instance.connected.

Se algo der errado

Status	Código	O que fazer
400	invalid_phone	O telefone precisa ter 12 ou 13 dígitos, ou 10 a 11 sem o 55
409	instance_not_connected	Não há conexão em andamento: refaça o passo 1 e peça o código em seguida
401	invalid_token	Confira o token e o ID da instância

Próximos passos

• Conexão: QR code, estados da instância, desconectar e reiniciar.
• Enviar uma mensagem com Node.js: mande a primeira mensagem pelo número conectado.
• Receber mensagens por webhook: receba as respostas no seu sistema.