Skip to main content
GET
/
api
/
instance
/
connect
/
:instance
Connect Instance
curl --request GET \
  --url https://api.example.com/api/instance/connect/:instance \
  --header 'token: <token>'
Auth: TokenAccount or TokenInstance • Rate-limit: Global (100/min) • Idempotent: partial

​
Description

Starts the connection via whatsmeow. With no parameters, generates a QR code. With ?number=..., generates a pairing code (8 characters). Blocks until a code or error is received (internal timeout ~60s).

​
Examples

​
QR code (default usage)

With no query params, the server generates the QR code to scan on the phone. Returns the ASCII string and the PNG in base64 ready to render. 
curl -X GET "https://ryzeapi.cloud/api/instance/connect/my-instance" \
  -H "token: $Token_Instance"

​
Pairing code

Passing ?number=5511999999999, the server forces login via an 8-character pairing code instead of QR, useful when the user doesn’t have access to a camera to scan. 
curl -X GET "https://ryzeapi.cloud/api/instance/connect/my-instance?number=5511999999999" \
  -H "token: $Token_Instance"

​
With 7 days of history

Requests the last 7 days of messages on the first pairing via ?history=7. The presence of the parameter forces synchronization even if disableHistorySync=true is in the instance settings. 
curl -X GET "https://ryzeapi.cloud/api/instance/connect/my-instance?history=7" \
  -H "token: $Token_Instance"
Pairing code: no camera needed. The user types the 8 characters in WhatsApp under Linked Devices > Link a Device > Link with phone number.

​
Success response

200 OK
{
  "success": true,
  "message": "QR code generated",
  "qrCode": "1@abc...,xyz==,base64string",
  "qrCodeBase64": "data:image/png;base64,iVBORw0K...",
  "status": "qr"
}
  • qrCode, ASCII string of the QR (what WhatsApp expects). Can be rendered with any QR library.
  • qrCodeBase64, PNG rendered by the server (base64). Ready to use as <img src="data:image/png;base64,...">.

​
Path parameters

​
instance
string
required
Name of the instance to connect.

​
Headers

​
token
string
required
TokenAccount or TokenInstance of the instance in the path.

​
Query parameters

​
number
string
Phone in international format (e.g., 5511999999999). If filled, forces login via pairing code instead of QR.
​
history
integer
Requests the last N days of history on the first pairing (e.g., ?history=5). Requires WhatsApp server support, not guaranteed. The presence of the parameter forces synchronization even if disableHistorySync=true in the settings.

​
Notes

The QR expires, WhatsApp issues a new QR after ~20s. If the user takes too long and you need another attempt, redo the call.
Pairing code is not reusable. If the user gets it wrong, redo the request to generate a new one.
After calling connect, poll GET /api/instance/list?instanceName=<name> to detect when the state becomes connected. Webhook/WebSocket notify in real time via the instance.state event.

​
Errors

HTTPerror.messageWhen
400Instance name is requiredEmpty path.
401Invalid tokenToken missing or invalid.
404Instance not foundName does not exist.
429Rate limit exceeded. Try again later.More than 100 req/min.
500Failed to generate QR codeFailure to generate QR/pairing (network, proxy, corrupted store).
{
  "success": false,
  "error": {
    "message": "Instance not found"
  }
}

​
Next

Reconnect without QR

POST /api/instance/reconnect/:instance, reuses the saved session.

Check state

GET /api/instance/list?instanceName=<name> shows the current state.