> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Instance

> Initiates the WhatsApp connection and returns a QR code or pairing code

**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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/instance/connect/my-instance" \
    -H "token: $Token_Instance"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/connect/my-instance", {
    method: "GET",
    headers: {
      "token": process.env.Token_Instance
    }
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://ryzeapi.cloud/api/instance/connect/my-instance",
      headers={
          "token": os.environ["Token_Instance"]
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/instance/connect/my-instance", nil)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/instance/connect/my-instance?number=5511999999999" \
    -H "token: $Token_Instance"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/connect/my-instance?number=5511999999999", {
    method: "GET",
    headers: {
      "token": process.env.Token_Instance
    }
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://ryzeapi.cloud/api/instance/connect/my-instance?number=5511999999999",
      headers={
          "token": os.environ["Token_Instance"]
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/instance/connect/my-instance?number=5511999999999", nil)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/instance/connect/my-instance?history=7" \
    -H "token: $Token_Instance"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/instance/connect/my-instance?history=7", {
    method: "GET",
    headers: {
      "token": process.env.Token_Instance
    }
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://ryzeapi.cloud/api/instance/connect/my-instance?history=7",
      headers={
          "token": os.environ["Token_Instance"]
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/instance/connect/my-instance?history=7", nil)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

<Tip>
  **Pairing code**: no camera needed. The user types the 8 characters in WhatsApp under **Linked Devices > Link a Device > Link with phone number**.
</Tip>

## Success response

<Tabs>
  <Tab title="QR code generated">
    ```json 200 OK theme={null}
    {
      "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,...">`.
  </Tab>

  <Tab title="Pairing code generated">
    ```json 200 OK theme={null}
    {
      "success": true,
      "message": "Pairing code generated",
      "pairingCode": "ABCD-EFGH",
      "status": "qr"
    }
    ```

    `pairingCode` is what the user types on the phone.
  </Tab>
</Tabs>

## Path parameters

<ParamField path="instance" type="string" required>
  Name of the instance to connect.
</ParamField>

## Headers

<ParamField header="token" type="string" required>
  TokenAccount or TokenInstance of the instance in the path.
</ParamField>

## Query parameters

<ParamField query="number" type="string">
  Phone in international format (e.g., `5511999999999`). If filled, forces login via **pairing code** instead of QR.
</ParamField>

<ParamField query="history" type="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.
</ParamField>

## Notes

<Note>
  **The QR expires**, WhatsApp issues a new QR after \~20s. If the user takes too long and you need another attempt, redo the call.
</Note>

<Warning>
  **Pairing code** is not reusable. If the user gets it wrong, redo the request to generate a new one.
</Warning>

<Tip>
  After calling `connect`, poll [`GET /api/instance/list?instanceName=<name>`](/en/api/instance/list) to detect when the state becomes `connected`. Webhook/WebSocket notify in real time via the `instance.state` event.
</Tip>

## Errors

| HTTP | `error.message`                         | When                                                              |
| :--: | --------------------------------------- | ----------------------------------------------------------------- |
|  400 | `Instance name is required`             | Empty path.                                                       |
|  401 | `Invalid token`                         | Token missing or invalid.                                         |
|  404 | `Instance not found`                    | Name does not exist.                                              |
|  429 | `Rate limit exceeded. Try again later.` | More than 100 req/min.                                            |
|  500 | `Failed to generate QR code`            | Failure to generate QR/pairing (network, proxy, corrupted store). |

```json theme={null}
{
  "success": false,
  "error": {
    "message": "Instance not found"
  }
}
```

## Next

<CardGroup cols={2}>
  <Card title="Reconnect without QR" icon="rotate" href="/en/api/instance/reconnect">
    `POST /api/instance/reconnect/:instance`, reuses the saved session.
  </Card>

  <Card title="Check state" icon="list-check" href="/en/api/instance/list">
    `GET /api/instance/list?instanceName=<name>` shows the current state.
  </Card>
</CardGroup>