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

# Concepts

> Glossary and mental model for working with RyzeAPI

Understanding these core concepts saves hours of debugging. Read this before opening any module.

## Account

Your **account** on RyzeAPI is what groups all of your WhatsApp instances. It has:

* A unique **TokenAccount** (your main credential)
* An **instance limit** that you can create
* Access to all of its instances

Think of it as your "client area": inside it live your instances, each one representing a connected WhatsApp number.

## Instance

An **instance** is an active connection to a WhatsApp number. Each instance has:

* **A unique name within your account** (e.g., `myInstance`, `support`, `service`)
* **Its own token** (TokenInstance) generated automatically when you create the instance
* **Persistent session**, after connecting to WhatsApp, it stays connected even after restarting
* **Individual settings** (webhook, proxy, etc.)

<Info>
  The instance name appears in every URL that has `:instance` in the path. Example: `POST /api/message/text/myInstance` operates on the instance named `myInstance`.
</Info>

## Tokens: Account vs Instance

<CardGroup cols={2}>
  <Card title="TokenAccount" icon="users">
    Delivered when your account is created. Used to **administer** your account.
    **Use cases**: create, list, or delete instances.
  </Card>

  <Card title="TokenInstance" icon="key">
    Generated by the API when you create an instance. Used for **day-to-day operations**.
    **Use cases**: send a message, create a group, configure a webhook, etc.
  </Card>
</CardGroup>

See [Authentication](/en/guide/authentication) for details on when to use each.

## JID (Jabber ID)

Every contact, group, or channel on WhatsApp has a **JID**, a unique identifier in email style. The API accepts and returns JIDs in every endpoint that references recipients.

| Type                 | Format                    | Example                        |
| -------------------- | ------------------------- | ------------------------------ |
| User                 | `<number>@s.whatsapp.net` | `5511999999999@s.whatsapp.net` |
| Group                | `<id>@g.us`               | `120363024567890123@g.us`      |
| Newsletter (channel) | `<id>@newsletter`         | `123456789@newsletter`         |

<Tip>
  In send endpoints for contacts, **you can pass just the number** (e.g., `5511999999999`) in the `number` field, and the API builds the full JID automatically. For groups, always pass the full JID (the one ending in `@g.us`).
</Tip>

## Webhook vs WebSocket

RyzeAPI offers **two complementary channels** to receive events in real time (new messages, delivery status, group changes, etc.). You can use both at the same time.

<AccordionGroup>
  <Accordion title="Webhook (HTTP push)" icon="webhook">
    When an event happens on your instance, RyzeAPI makes a `POST` request to the URL you configured.

    **Ideal for:** server-to-server integrations, CRMs, automations, bots.

    **Characteristics:**

    * RyzeAPI retries if your endpoint is down (retry with backoff)
    * You can configure up to 3 simultaneous webhooks per instance (production, staging, logging)
    * Can include the media as base64 in the webhook body, or just the URL
  </Accordion>

  <Accordion title="WebSocket (persistent connection)" icon="plug">
    Your client keeps an open connection with RyzeAPI and receives events in real time over the same channel.

    **Ideal for:** live dashboards, browser applications, any interface where you want to see messages arrive without polling.

    **Characteristics:**

    * Automatic reconnection recommended on the client side
    * Same event shape as the webhook
    * Authenticated via query string (`?token=`) when in browser
  </Accordion>
</AccordionGroup>

### The 6 event types

| Event              | When it happens                         |
| ------------------ | --------------------------------------- |
| `message.exchange` | Message sent or received                |
| `message.status`   | Status change (sent → delivered → read) |
| `group.flow`       | Group creation, exit, or change         |
| `instance.state`   | Connected, disconnected, new QR, logout |
| `call.update`      | Call received, rejected, accepted       |
| `label.update`     | Label created, renamed, assigned        |

## Response format

The API uses two envelope formats, which can vary across endpoints. Both start with the `success` field that indicates whether the operation succeeded.

<Tabs>
  <Tab title="Success">
    ```json theme={null}
    {
      "success": true,
      "message": "Text message sent successfully",
      "status": "sent",
      "data": { "...": "..." }
    }
    ```

    **Important fields:**

    * `success`: always present
    * `message`: human-readable description of the result
    * `status`: **stable business code** (e.g., `sent`, `connected`, `qr_ready`). It is the best field for handling responses programmatically
    * `data`: useful payload (varies by endpoint)
  </Tab>

  <Tab title="Error">
    ```json theme={null}
    {
      "success": false,
      "error": {
        "message": "Instance is not connected to WhatsApp"
      }
    }
    ```

    **Priority order for handling:**

    1. The HTTP code (401, 403, 429, etc.), source of truth
    2. The text in `error.message`, when you need to differentiate two errors with the same HTTP code
  </Tab>
</Tabs>

See [Error types](/en/guide/errors) for the full catalog of literal messages.

## Quick glossary

| Term              | Meaning                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------- |
| **Account**       | Your main area on RyzeAPI. Groups all of your instances, with a quota of how many you can create. |
| **Instance**      | Active connection to a WhatsApp number, managed by the API.                                       |
| **TokenAccount**  | Your main token, used to create/list/delete instances.                                            |
| **TokenInstance** | Token for the specific instance, used for day-to-day operations.                                  |
| **JID**           | Unique identifier on WhatsApp (contact, group, or channel) in email format.                       |
| **Webhook**       | `POST` request that RyzeAPI makes to your URL when an event happens.                              |
| **WebSocket**     | Persistent connection that delivers events in real time to a client.                              |
| **Pairing code**  | 8-character code to connect an instance without scanning a QR.                                    |

## Variables used in examples

The Base URL is always `https://ryzeapi.cloud`. The examples use these variables:

| Variable          | Meaning                            |
| ----------------- | ---------------------------------- |
| `$Token_Account`  | Your account token                 |
| `$Token_Instance` | Token of a specific instance       |
| `$Instance_Name`  | Instance name (e.g., `myInstance`) |