Conexión

Para enviar y recibir mensajes, la instancia debe estar conectada a un número de WhatsApp. Se conecta de dos maneras: escaneando un código QR o ingresando un código de emparejamiento en el celular.

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

Estados de la instancia

El campo connectionStatus, en GET /v1/instances/{instanceId}, indica en qué punto está la conexión:

Estado	Significado
disconnected	Sin sesión. Llame a POST /connect para comenzar
connecting	La conexión se está estableciendo
qr	Esperando que se escanee el código QR
connected	Conectada. El número aparece en phone

Conectar con código QR

Primero inicie la conexión:

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

La respuesta es 202 con { "connectionStatus": "..." }. Solo confirma que la conexión comenzó. Si la instancia está suspendida o con pago pendiente, la API responde 402 con instance_suspended.

Luego obtenga el código QR:

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

La respuesta trae:

Campo	Descripción
qr	El texto del código QR, o null si todavía no hay uno disponible
image	El código QR como imagen PNG en una URL data:, lista para un <img>, o null

El código QR cambia cada pocos segundos. Consulte de nuevo mientras el estado sea qr. En el celular, abra WhatsApp, vaya a Dispositivos vinculados y escanee el código.

Si la instancia ya está conectada, la API responde 409 con already_connected.

Conectar con código de emparejamiento

¿Prefiere no usar la cámara? Genere un código e ingréselo en el celular, en Dispositivos vinculados y luego Vincular con el número de teléfono. La conexión debe haberse iniciado antes, con 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" }'

Envíe el teléfono del número que se va a conectar, con código de país y de área. La respuesta es { "code": "..." }.

Estado	Código	Cuándo
400	invalid_phone	El teléfono no tiene entre 12 y 13 dígitos (o 10 a 11, sin el 55)
409	instance_not_connected	No hay sesión activa: llame a POST /connect antes

Saber cuándo se conectó

En lugar de consultar la API en un bucle, configure los webhooks instance.connected e instance.disconnected. El primero trae el phone del número. El segundo trae reason y loggedOut.

Desconectar y reiniciar

Operación	Ruta	Qué hace
Desconectar	POST /disconnect	Cierra la sesión y desvincula el dispositivo. Para volver, habrá que escanear un nuevo código QR. Responde { "ok": true }
Reiniciar	POST /restart	Reinicia la sesión sin desvincular el dispositivo. No pide un nuevo código QR si las credenciales siguen siendo válidas. Responde { "ok": true }