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

# Sesiones en vivo

> Lista las conversaciones de Typebot en curso y controla una sesión (pausar, reanudar, cerrar)

**Auth:** `TokenAccount` o `TokenInstance` • **Rate limit:** `Global` (100/min) • **Idempotente:** `GET` sí · `POST` no

## Descripción

Este recurso agrupa **dos operaciones** sobre las conversaciones (sesiones) que están corriendo para la instancia:

* **`GET /api/typebot/sessions/:instance`**, lista las sesiones en vivo (`opened` / `paused` / `held`), opcionalmente filtradas por bot con `?botId=`.
* **`POST /api/typebot/sessions/:instance`**, controla **una** sesión: la pausa, la reanuda o la cierra.

<Note>
  Si no hay integración de Typebot para la instancia, ambas operaciones devuelven **`404`** / **`503`**.
</Note>

<Note>
  El `jid` de la conversación se **deriva del `number`** en la operación `POST`; no necesitas conocerlo. En el `GET`, cada sesión trae su `jid` y su `number` ya resueltos.
</Note>

## Listar sesiones, `GET`

Devuelve las conversaciones en curso de la instancia. Con `?botId=`, restringe la lista a las sesiones de ese bot.

### Ejemplo

**Todas las sesiones en vivo**

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/typebot/sessions/suporte" \
    -H "token: $Token_Account"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/typebot/sessions/suporte", {
    method: "GET",
    headers: {
      "token": process.env.Token_Account
    }
  });
  ```

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

  requests.get(
      "https://ryzeapi.cloud/api/typebot/sessions/suporte",
      headers={
          "token": os.environ["Token_Account"]
      }
  )
  ```

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

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/typebot/sessions/suporte", nil)
      req.Header.Set("token", os.Getenv("Token_Account"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

**Sesiones de un bot (`?botId=`)**

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/typebot/sessions/suporte?botId=8f3a1c2e-...-b7d9" \
    -H "token: $Token_Account"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/typebot/sessions/suporte?botId=8f3a1c2e-...-b7d9", {
    method: "GET",
    headers: {
      "token": process.env.Token_Account
    }
  });
  ```

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

  requests.get(
      "https://ryzeapi.cloud/api/typebot/sessions/suporte",
      params={"botId": "8f3a1c2e-...-b7d9"},
      headers={
          "token": os.environ["Token_Account"]
      }
  )
  ```

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

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/typebot/sessions/suporte?botId=8f3a1c2e-...-b7d9", nil)
      req.Header.Set("token", os.Getenv("Token_Account"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### Respuesta exitosa

```json 200 OK theme={null}
{
  "success": true,
  "message": "2 session(s) found",
  "sessions": [
    {
      "jid": "5511999999999@s.whatsapp.net",
      "number": "5511999999999",
      "bot_id": "8f3a1c2e-...-b7d9",
      "status": "opened",
      "await_user": true,
      "last_activity_at": "2026-07-27T13:58:40Z",
      "expires_at": "2026-07-27T14:28:40Z",
      "started_at": "2026-07-27T13:40:02Z"
    },
    {
      "jid": "5511888888888@s.whatsapp.net",
      "number": "5511888888888",
      "bot_id": "8f3a1c2e-...-b7d9",
      "status": "paused",
      "await_user": false,
      "last_activity_at": "2026-07-27T13:20:11Z",
      "expires_at": null,
      "started_at": "2026-07-27T12:55:00Z"
    }
  ],
  "meta": {
    "total": 2
  }
}
```

| Campo                         | Descripción                                                                                                                                                                                                                         |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `success`                     | `true` cuando la operación tuvo éxito.                                                                                                                                                                                              |
| `message`                     | Resumen: `N session(s) found`.                                                                                                                                                                                                      |
| `sessions`                    | Lista de las conversaciones en vivo (`opened`, `paused` y `held`). Vacía cuando no hay sesiones.                                                                                                                                    |
| `sessions[].jid`              | JID de WhatsApp de la conversación (derivado del número).                                                                                                                                                                           |
| `sessions[].number`           | Número del contacto en formato E.164 sin `+`.                                                                                                                                                                                       |
| `sessions[].bot_id`           | UUID del bot que conduce la conversación.                                                                                                                                                                                           |
| `sessions[].status`           | Estado de la sesión: `opened` (activa), `paused` (pausada por el operador/regla), `held` (mantenida abierta al terminar el flujo por `keepOpen`, esperando atención) o `closed` (cerrada). `GET` lista `opened`, `paused` y `held`. |
| `sessions[].await_user`       | `true` cuando el flujo está esperando una respuesta del usuario.                                                                                                                                                                    |
| `sessions[].last_activity_at` | Marca de tiempo RFC3339 de la última actividad.                                                                                                                                                                                     |
| `sessions[].expires_at`       | Marca de tiempo RFC3339 de expiración por inactividad. `null` cuando la sesión no expira.                                                                                                                                           |
| `sessions[].started_at`       | Marca de tiempo RFC3339 de inicio de la sesión.                                                                                                                                                                                     |
| `meta.total`                  | Número de sesiones devueltas.                                                                                                                                                                                                       |

### Parámetros de consulta

<ParamField query="botId" type="string">
  UUID de un bot específico. Presente, la respuesta trae solo las sesiones de ese bot. Ausente, devuelve todas las sesiones de la instancia.
</ParamField>

## Controlar una sesión, `POST`

Pausa, reanuda o cierra **una** conversación, identificada por su `number`.

### Ejemplo

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://ryzeapi.cloud/api/typebot/sessions/suporte" \
    -H "token: $Token_Account" \
    -H "Content-Type: application/json" \
    -d '{
      "number": "5511999999999",
      "status": "pause"
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/typebot/sessions/suporte", {
    method: "POST",
    headers: {
      "token":        process.env.Token_Account,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      number: "5511999999999",
      status: "pause"
    })
  });
  ```

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

  requests.post(
      "https://ryzeapi.cloud/api/typebot/sessions/suporte",
      headers={
          "token":        os.environ["Token_Account"],
          "Content-Type": "application/json"
      },
      json={
          "number": "5511999999999",
          "status": "pause"
      }
  )
  ```

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

  import (
      "net/http"
      "os"
      "strings"
  )

  func main() {
      body := strings.NewReader(`{
          "number": "5511999999999",
          "status": "pause"
      }`)
      req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/typebot/sessions/suporte", body)
      req.Header.Set("token", os.Getenv("Token_Account"))
      req.Header.Set("Content-Type", "application/json")
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

<Tip>
  `pause` deja la conversación en manos del operador humano; `resume` devuelve el control al flujo; `close` termina la sesión por completo.
</Tip>

### Respuesta exitosa

```json 200 OK theme={null}
{
  "success": true,
  "message": "session paused"
}
```

| Campo     | Descripción                                                                                      |
| --------- | ------------------------------------------------------------------------------------------------ |
| `success` | `true` cuando la operación tuvo éxito.                                                           |
| `message` | Confirmación según el `status` enviado: `session paused` / `session resumed` / `session closed`. |

### Cuerpo de la solicitud

<ParamField body="number" type="string" required>
  Número del contacto en formato E.164 sin el `+` (p. ej., `5511999999999`). El `jid` de la conversación se deriva de él.
</ParamField>

<ParamField body="status" type="string" required>
  Acción a aplicar sobre la sesión: `pause` (pausar), `resume` (reanudar) o `close` (cerrar).
</ParamField>

<ParamField body="botId" type="string">
  UUID del bot, opcional e informativo. La sesión se localiza por el `number`.
</ParamField>

## Parámetros de ruta

<ParamField path="instance" type="string" required>
  Nombre de la instancia (p. ej., `suporte`).
</ParamField>

## Cabeceras

<ParamField header="token" type="string" required>
  `TokenAccount` o `TokenInstance`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json` (solo para el `POST`).
</ParamField>

## Errores

| HTTP | `error.message`                                                | Causa                                                                                    |
| :--: | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
|  400 | `invalid body: ...`                                            | Body malformado, `number` ausente o `status` fuera de `pause`/`resume`/`close` (`POST`). |
|  404 | `instance not found`                                           | La instancia no existe en RyzeAPI.                                                       |
|  404 | `no typebot integration for this instance, create a bot first` | La instancia todavía no tiene ningún bot/integración.                                    |
|  503 | `integration gateway not configured`                           | Servicio de integración no disponible en el servidor.                                    |

### Ejemplo de payload de error

`status` inválido en el `POST`:

```json theme={null}
{
  "success": false,
  "error": {
    "message": "invalid body: status must be one of pause, resume, close"
  }
}
```

## Siguiente

<CardGroup cols={2}>
  <Card title="Listar bots" icon="list" href="/es/api/typebot/list">
    Consulta los bots (con `active_sessions`) de la instancia.
  </Card>

  <Card title="Iniciar flujo" icon="play" href="/es/api/typebot/start">
    Dispara un flujo manualmente para un número con `POST /api/typebot/start/:instance`.
  </Card>
</CardGroup>