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

# Live sessions

> Lists live Typebot conversations and pauses, resumes, or closes a single one

**Auth:** `TokenAccount` or `TokenInstance` • **Rate limit:** `Global` (100/min) • **Idempotent:** `GET` yes / `POST` no

## Description

Two operations on the same path:

* **`GET /api/typebot/sessions/:instance`**, lists the live conversations (status `opened`, `paused` or `held`), optionally filtered by `?botId=`.
* **`POST /api/typebot/sessions/:instance`**, controls a single conversation: `pause`, `resume`, or `close` it.

<Info>
  When the instance has no Typebot integration or the integration is unavailable, they return **`404`** / **`503`** (see the error tables below).
</Info>

## List live sessions

`GET /api/typebot/sessions/:instance?botId=`

Returns every ongoing conversation for the instance. Pass `?botId=` to restrict the result to one bot.

### Example

**All live sessions**

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

**Sessions of one bot**

<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",
      headers={
          "token": os.environ["Token_Account"]
      },
      params={ "botId": "8f3a1c2e-...-b7d9" }
  )
  ```

  ```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>

### Success response

```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:50:02Z"
    },
    {
      "jid": "5511888888888@s.whatsapp.net",
      "number": "5511888888888",
      "bot_id": "8f3a1c2e-...-b7d9",
      "status": "paused",
      "await_user": false,
      "last_activity_at": "2026-07-27T13:41:10Z",
      "expires_at": null,
      "started_at": "2026-07-27T13:30:55Z"
    }
  ],
  "meta": { "total": 2 }
}
```

| Field        | Description                                                                      |
| ------------ | -------------------------------------------------------------------------------- |
| `success`    | Always `true` on success.                                                        |
| `message`    | Human-readable count (`N session(s) found`).                                     |
| `sessions`   | List of live conversations (opened, paused and held). Empty when there are none. |
| `meta.total` | Number of sessions returned.                                                     |

#### Session fields

| Field              | Description                                                                                                                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jid`              | Full WhatsApp JID of the contact.                                                                                                                                                                  |
| `number`           | Contact number in E.164 without the `+`.                                                                                                                                                           |
| `bot_id`           | UUID of the bot handling the conversation.                                                                                                                                                         |
| `status`           | `opened` (active), `paused` (paused by the operator/rule), `held` (kept open after the flow ended by `keepOpen`, awaiting a human) or `closed` (ended). `GET` lists `opened`, `paused` and `held`. |
| `await_user`       | `true` when the flow is waiting for the user's next message.                                                                                                                                       |
| `last_activity_at` | Timestamp of the last activity (RFC3339).                                                                                                                                                          |
| `expires_at`       | When the session expires by inactivity (RFC3339), `null` when it never expires.                                                                                                                    |
| `started_at`       | When the session started (RFC3339).                                                                                                                                                                |

### Errors

| HTTP | `error.message`                                                | Cause                                          |
| :--: | -------------------------------------------------------------- | ---------------------------------------------- |
|  404 | `instance not found`                                           | Instance does not exist in RyzeAPI.            |
|  404 | `no typebot integration for this instance, create a bot first` | The instance has no bot/integration yet.       |
|  503 | `integration gateway not configured`                           | Integration service unavailable on the server. |

## Control a session

`POST /api/typebot/sessions/:instance`

Pauses, resumes, or closes a single conversation. The `jid` is derived from `number`.

### Example

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

### Success response

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

| Field     | Description                                                                     |
| --------- | ------------------------------------------------------------------------------- |
| `success` | Always `true` on success.                                                       |
| `message` | Result of the action: `session paused`, `session resumed`, or `session closed`. |

### Request body

<ParamField body="number" type="string" required>
  Contact number in E.164 format without the `+` (e.g., `5511999999999`). The `jid` is derived from it.
</ParamField>

<ParamField body="status" type="string" required>
  Action to apply: `pause`, `resume`, or `close`.
</ParamField>

<ParamField body="botId" type="string">
  UUID of the bot. Optional and informational, the conversation is located by `number`.
</ParamField>

### Errors

| HTTP | `error.message`                                                | Cause                                                |
| :--: | -------------------------------------------------------------- | ---------------------------------------------------- |
|  400 | `invalid body: ...`                                            | Malformed body or missing `number` / `status`.       |
|  400 | `invalid status: ...`                                          | `status` is not one of `pause` / `resume` / `close`. |
|  404 | `instance not found`                                           | Instance does not exist in RyzeAPI.                  |
|  404 | `no typebot integration for this instance, create a bot first` | The instance has no bot/integration yet.             |
|  503 | `integration gateway not configured`                           | Integration service unavailable on the server.       |

## Path parameters

<ParamField path="instance" type="string" required>
  Instance name (e.g., `suporte`).
</ParamField>

## Query parameters

<ParamField query="botId" type="string">
  (`GET` only) UUID of a bot to restrict the listed sessions. Omitted, all the instance's sessions are returned.
</ParamField>

## Headers

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

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

## Next

<CardGroup cols={2}>
  <Card title="List bots" icon="list" href="/en/api/typebot/list">
    See each bot's `active_sessions` count with `GET /api/typebot/list/:instance`.
  </Card>

  <Card title="Start flow" icon="play" href="/en/api/typebot/start">
    Open a new conversation with `POST /api/typebot/start/:instance`.
  </Card>
</CardGroup>