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

# Quickstart

> Create an instance, connect your WhatsApp, and send your first message in less than 5 minutes

This guide covers the minimum path to get an instance connected and exchange your first message.

## Prerequisites

<Check>You already have your RyzeAPI **TokenAccount**.</Check>
<Check>A phone with **WhatsApp Business** (or regular WhatsApp) installed.</Check>

## 1. Set your token

```bash theme={null}
export Token_Account="your-account-token"
```

In all examples, the Base URL is always `https://ryzeapi.cloud`.

## 2. Create an instance

Use your TokenAccount to provision a new WhatsApp instance.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://ryzeapi.cloud/api/instance/new" \
    -H "token: $Token_Account" \
    -H "Content-Type: application/json" \
    -d '{"name": "$Instance_Name"}'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch(`https://ryzeapi.cloud/api/instance/new`, {
    method: "POST",
    headers: {
      "token": Token_Account,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ name: "$Instance_Name" }),
  });
  const { data } = await res.json();
  console.log(data.token); // this is the TokenInstance
  ```

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

  r = requests.post(
      "https://ryzeapi.cloud/api/instance/new",
      headers={"token": os.environ["Token_Account"]},
      json={"name": "myInstance"},
  )
  print(r.json()["data"]["token"])  # this is the TokenInstance
  ```
</CodeGroup>

Expected response:

```json theme={null}
{
  "success": true,
  "message": "Instance created successfully",
  "status": "created",
  "data": {
    "id": "01953abc-...",
    "name": "$Instance_Name",
    "token": "a1b2c3d4-...",
    "status": "disconnected",
    "createdAt": "2026-04-21T12:00:00Z"
  }
}
```

<Warning>
  **Save the `data.token`**, this is your **TokenInstance**. From now on, use it (not the TokenAccount) to operate this instance.
</Warning>

```bash theme={null}
export Token_Instance="a1b2c3d4-..."
```

## 3. Connect to WhatsApp

Use your **TokenInstance** from here on.

<Tabs>
  <Tab title="Via QR code">
    ```bash theme={null}
    curl -X GET "https://ryzeapi.cloud/api/instance/connect/$Instance_Name" \
      -H "token: $Token_Instance"
    ```

    The response includes:

    * `data.qrCodes`, strings that can be converted into a QR
    * `data.qrImages`, base64 PNGs ready to display as an image

    Scan it on your phone in **WhatsApp → Linked devices → Link a device**.
  </Tab>

  <Tab title="Via pairing code">
    Ideal for environments without a camera. Pass your number in the `number` parameter:

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

    The response includes an 8-character code to enter in **Linked devices → Link with code**.
  </Tab>
</Tabs>

## 4. Confirm that it is connected

```bash theme={null}
curl -X GET "https://ryzeapi.cloud/api/instance/list?instanceName=$Instance_Name" \
  -H "token: $Token_Instance"
```

Wait for the instance's `status` field to become `"connected"`.

## 5. Send your first message

```bash theme={null}
curl -X POST "https://ryzeapi.cloud/api/message/text/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "text": "Hello from RyzeAPI 👋"
  }'
```

## 6. Configure a webhook (optional)

To receive events in real time (incoming messages, delivery status, etc.):

```bash theme={null}
curl -X POST "https://ryzeapi.cloud/api/events/webhook/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "default",
    "enabled": true,
    "url": "https://your-server.com/webhook",
    "events": ["message.exchange", "group.flow", "instance.state"],
    "mediaBase64": false
  }'
```

<Tip>
  Each instance accepts up to **3 simultaneous webhooks** (for example: production, staging, and a logging one). See [Events](/en/api/events/overview) for the 6 available types.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Send media and advanced features" icon="image" href="/en/api/messages/overview">
    Images, videos, audio, documents, buttons, carousels, lists, and forms.
  </Card>

  <Card title="Manage contacts and labels" icon="address-book" href="/en/api/chat/overview">
    Organize conversations, create labels, archive, block, and pin chats.
  </Card>

  <Card title="Authentication" icon="key" href="/en/guide/authentication">
    Understand TokenAccount vs TokenInstance in detail.
  </Card>

  <Card title="Error types" icon="triangle-exclamation" href="/en/guide/errors">
    How to interpret and handle each HTTP code.
  </Card>
</CardGroup>