Connection

To send and receive messages, the instance must be connected to a WhatsApp number. You can connect in two ways: by scanning a QR code or by entering a pairing code on the phone.

In the examples, replace INSTANCIA_ID with the instance’s identifier and TOKEN with its token.

Instance states

The connectionStatus field, in GET /v1/instances/{instanceId}, shows where the connection stands:

State	Meaning
disconnected	No session. Call POST /connect to start
connecting	The connection is being established
qr	Waiting for the QR code to be scanned
connected	Connected. The number appears in phone

Connect with a QR code

First start the connection:

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

The response is 202 with { "connectionStatus": "..." }. It only confirms that the connection has started. If the instance is suspended or has a pending payment, the API responds 402 with instance_suspended.

Then fetch the QR code:

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

The response contains:

Field	Description
qr	The QR code’s text, or null if none is available yet
image	The QR code as a PNG image in a data: URL, ready for an <img>, or null

The QR code changes every few seconds. Check again while the state is qr. On your phone, open WhatsApp, go to Linked devices and scan the code.

If the instance is already connected, the API responds 409 with already_connected.

Connect with a pairing code

Prefer not to use the camera? Generate a code and enter it on the phone, under Linked devices and then Link with phone number. The connection must have been started first, with 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" }'

Send the phone number to be connected, with country code and area code. The response is { "code": "..." }.

Status	Code	When
400	invalid_phone	The phone does not have 12 to 13 digits (or 10 to 11, without the 55)
409	instance_not_connected	There is no active session: call POST /connect first

Knowing when it connected

Instead of polling the API in a loop, set up the instance.connected and instance.disconnected webhooks. The first carries the number’s phone. The second carries reason and loggedOut.

Disconnect and restart

Operation	Route	What it does
Disconnect	POST /disconnect	Ends the session and unlinks the device. To come back, you will need to scan a new QR code. Responds { "ok": true }
Restart	POST /restart	Restarts the session without unlinking the device. It does not ask for a new QR code if the credentials are still valid. Responds { "ok": true }