Conectar el número a WhatsApp con código de emparejamiento

Objetivo

Al final, el número del celular estará conectado a su instancia, sin necesidad de escanear un código QR. Es útil cuando no puede apuntar la cámara a la pantalla, por ejemplo al configurar todo desde el propio celular.

Requisitos previos

• Una instancia creada en el panel, con el ID y el token (Primeros pasos).
• El celular con WhatsApp instalado y el número que se va a conectar.
• curl en la terminal.

En los ejemplos, reemplace INSTANCIA_ID por el ID de la instancia y TOKEN por el token de ella.

1. Inicie la conexión

El código de emparejamiento solo existe después de que la conexión comienza:

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

La respuesta es 202 con el connectionStatus. Solo confirma que la conexión comenzó. Si la instancia está suspendida o con un pago pendiente, la respuesta es 402 con instance_suspended.

2. Pida el código

Envíe el teléfono del número que se va a conectar, con código de país y de área:

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

El código será otro, con 8 caracteres. Si la API tarda unos segundos, es normal: espera a que la conexión esté lista antes de generar el código.

3. Ingrese el código en el celular

En el celular:

1. Abra WhatsApp.
2. Vaya a Dispositivos vinculados.
3. Toque Vincular con el número de teléfono.
4. Ingrese el código del paso anterior.

Si WhatsApp rechaza el código, repita el paso 2 para pedir otro.

4. Confirme la conexión

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

Resultado esperado, con el connectionStatus en connected y el número en phone:

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

La respuesta real trae otros campos de la instancia. Mientras el estado no sea connected, consulte de nuevo en unos segundos. Para recibir un aviso sin consultar, configure el webhook instance.connected.

Si algo sale mal

Status	Código	Qué hacer
400	invalid_phone	El teléfono debe tener 12 o 13 dígitos, o 10 a 11 sin el 55
409	instance_not_connected	No hay una conexión en curso: repita el paso 1 y pida el código enseguida
401	invalid_token	Revise el token y el ID de la instancia

Próximos pasos

• Conexión: código QR, estados de la instancia, desconectar y reiniciar.
• Enviar un mensaje con Node.js: envíe el primer mensaje desde el número conectado.
• Recibir mensajes por webhook: reciba las respuestas en su sistema.