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

# Conceptos

> Glosario y modelo mental para trabajar con RyzeAPI

Comprender estos conceptos clave ahorra horas de depuración. Léelos antes de abrir cualquier módulo.

## Account

Tu **cuenta** en RyzeAPI es lo que agrupa todas tus instancias de WhatsApp. Tiene:

* Un **TokenAccount** único (tu credencial principal)
* Un **límite de instancias** que puedes crear
* Acceso a todas sus instancias

Piénsalo como tu "área de cliente": dentro de ella viven tus instancias, cada una representando un número de WhatsApp conectado.

## Instance

Una **instancia** es una conexión activa a un número de WhatsApp. Cada instancia tiene:

* **Un nombre único dentro de tu cuenta** (por ejemplo, `myInstance`, `support`, `service`)
* **Su propio token** (TokenInstance) generado automáticamente al crear la instancia
* **Sesión persistente**, después de conectarte a WhatsApp, permanece conectada incluso tras reiniciar
* **Configuración individual** (webhook, proxy, etc.)

<Info>
  El nombre de la instancia aparece en cada URL que tiene `:instance` en la ruta. Ejemplo: `POST /api/message/text/myInstance` opera sobre la instancia llamada `myInstance`.
</Info>

## Tokens: Account vs Instance

<CardGroup cols={2}>
  <Card title="TokenAccount" icon="users">
    Entregado al crearse tu cuenta. Se usa para **administrar** tu cuenta.
    **Casos de uso**: crear, listar o eliminar instancias.
  </Card>

  <Card title="TokenInstance" icon="key">
    Generado por la API al crear una instancia. Se usa para **operaciones del día a día**.
    **Casos de uso**: enviar un mensaje, crear un grupo, configurar un webhook, etc.
  </Card>
</CardGroup>

Consulta [Autenticación](/es/guide/authentication) para más detalles sobre cuándo usar cada uno.

## JID (Jabber ID)

Cada contacto, grupo o canal en WhatsApp tiene un **JID**, un identificador único en estilo de correo electrónico. La API acepta y devuelve JIDs en cada endpoint que referencia destinatarios.

| Tipo               | Formato                   | Ejemplo                        |
| ------------------ | ------------------------- | ------------------------------ |
| Usuario            | `<numero>@s.whatsapp.net` | `5511999999999@s.whatsapp.net` |
| Grupo              | `<id>@g.us`               | `120363024567890123@g.us`      |
| Newsletter (canal) | `<id>@newsletter`         | `123456789@newsletter`         |

<Tip>
  En los endpoints de envío para contactos, **puedes pasar solo el número** (por ejemplo, `5511999999999`) en el campo `number`, y la API construye el JID completo automáticamente. Para grupos, siempre pasa el JID completo (el que termina en `@g.us`).
</Tip>

## Webhook vs WebSocket

RyzeAPI ofrece **dos canales complementarios** para recibir eventos en tiempo real (nuevos mensajes, estado de entrega, cambios de grupo, etc.). Puedes usar ambos al mismo tiempo.

<AccordionGroup>
  <Accordion title="Webhook (HTTP push)" icon="webhook">
    Cuando ocurre un evento en tu instancia, RyzeAPI realiza una solicitud `POST` a la URL que configuraste.

    **Ideal para:** integraciones servidor a servidor, CRMs, automatizaciones, bots.

    **Características:**

    * RyzeAPI reintenta si tu endpoint está caído (retry con backoff)
    * Puedes configurar hasta 3 webhooks simultáneos por instancia (producción, staging, logs)
    * Puede incluir el archivo multimedia como base64 en el cuerpo del webhook, o solo la URL
  </Accordion>

  <Accordion title="WebSocket (conexión persistente)" icon="plug">
    Tu cliente mantiene una conexión abierta con RyzeAPI y recibe eventos en tiempo real por el mismo canal.

    **Ideal para:** dashboards en vivo, aplicaciones de navegador, cualquier interfaz donde quieras ver llegar los mensajes sin polling.

    **Características:**

    * Se recomienda reconexión automática del lado del cliente
    * Mismo formato de evento que el webhook
    * Autenticado vía query string (`?token=`) cuando se usa en navegador
  </Accordion>
</AccordionGroup>

### Los 6 tipos de evento

| Evento             | Cuándo ocurre                                  |
| ------------------ | ---------------------------------------------- |
| `message.exchange` | Mensaje enviado o recibido                     |
| `message.status`   | Cambio de estado (enviado → entregado → leído) |
| `group.flow`       | Creación, salida o cambio de grupo             |
| `instance.state`   | Conectado, desconectado, nuevo QR, logout      |
| `call.update`      | Llamada recibida, rechazada, aceptada          |
| `label.update`     | Etiqueta creada, renombrada, asignada          |

## Formato de respuesta

La API utiliza dos formatos de envoltorio, que pueden variar entre endpoints. Ambos comienzan con el campo `success` que indica si la operación fue exitosa.

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

    **Campos importantes:**

    * `success`: siempre presente
    * `message`: descripción legible del resultado
    * `status`: **código de negocio estable** (por ejemplo, `sent`, `connected`, `qr_ready`). Es el mejor campo para manejar respuestas de forma programática
    * `data`: payload útil (varía según el endpoint)
  </Tab>

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

    **Orden de prioridad para el manejo:**

    1. El código HTTP (401, 403, 429, etc.), fuente de verdad
    2. El texto en `error.message`, cuando necesitas diferenciar dos errores con el mismo código HTTP
  </Tab>
</Tabs>

Consulta [Tipos de error](/es/guide/errors) para el catálogo completo de mensajes literales.

## Glosario rápido

| Término           | Significado                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------- |
| **Account**       | Tu área principal en RyzeAPI. Agrupa todas tus instancias, con una cuota de cuántas puedes crear. |
| **Instance**      | Conexión activa a un número de WhatsApp, gestionada por la API.                                   |
| **TokenAccount**  | Tu token principal, usado para crear/listar/eliminar instancias.                                  |
| **TokenInstance** | Token de la instancia específica, usado para operaciones del día a día.                           |
| **JID**           | Identificador único en WhatsApp (contacto, grupo o canal) en formato de correo electrónico.       |
| **Webhook**       | Solicitud `POST` que RyzeAPI hace a tu URL cuando ocurre un evento.                               |
| **WebSocket**     | Conexión persistente que entrega eventos en tiempo real a un cliente.                             |
| **Pairing code**  | Código de 8 caracteres para conectar una instancia sin escanear un QR.                            |

## Variables usadas en los ejemplos

La Base URL es siempre `https://ryzeapi.cloud`. Los ejemplos usan estas variables:

| Variable          | Significado                                        |
| ----------------- | -------------------------------------------------- |
| `$Token_Account`  | Tu token de cuenta                                 |
| `$Token_Instance` | Token de una instancia específica                  |
| `$Instance_Name`  | Nombre de la instancia (por ejemplo, `myInstance`) |