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

# Sessões ao vivo

> Lista as conversas do Typebot em andamento (opened/paused/held) e permite pausar, retomar ou encerrar uma delas

**Auth:** `TokenAccount` ou `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotente:** `GET` sim, `POST` não

## Descrição

Gerencia as **conversas ao vivo** do Typebot de uma instância:

* **`GET /api/typebot/sessions/:instance`**, lista as sessões em andamento (`opened`, `paused` e `held`), opcionalmente filtradas por `?botId=`.
* **`POST /api/typebot/sessions/:instance`**, controla **uma** conversa: pausar, retomar ou encerrar.

<Info>
  Se a instância não tiver integração do Typebot, retorna `404`; se o serviço de integração estiver indisponível, retorna `503`.
</Info>

<Note>
  Uma sessão nasce quando um bot inicia a conversa (por trigger ou por [`POST /api/typebot/start/:instance`](/pt/api/typebot/start)) e fica persistida no servidor, reiniciar o serviço não perde a conversa.
</Note>

## Campos da sessão

| Campo              | Descrição                                                                                                                                                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `jid`              | JID do WhatsApp do contato (ex.: `5511999999999@s.whatsapp.net`).                                                                                                                                             |
| `number`           | Número do contato no formato E.164 sem o `+` (ex.: `5511999999999`).                                                                                                                                          |
| `bot_id`           | UUID do bot dono da sessão.                                                                                                                                                                                   |
| `status`           | `opened` (ativa), `paused` (pausada pelo operador/regra), `held` (mantida aberta ao fim do fluxo pelo `keepOpen`, aguardando atendimento) ou `closed` (encerrada). O `GET` lista `opened`, `paused` e `held`. |
| `await_user`       | `true` quando o fluxo está aguardando uma resposta do usuário.                                                                                                                                                |
| `last_activity_at` | Data/hora (RFC3339) da última atividade na sessão.                                                                                                                                                            |
| `expires_at`       | Data/hora (RFC3339) em que a sessão expira por inatividade. `null` quando o bot não expira (`expire_minutes: 0`).                                                                                             |
| `started_at`       | Data/hora (RFC3339) em que a sessão foi iniciada.                                                                                                                                                             |

***

## Listar sessões

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

### Exemplo

**Todas as sessões ao 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>

**Sessões de um 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>

### Resposta de sucesso

```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-27T11:58:03Z",
      "expires_at": "2026-07-27T12:28:03Z",
      "started_at": "2026-07-27T11:40:12Z"
    },
    {
      "jid": "5511888888888@s.whatsapp.net",
      "number": "5511888888888",
      "bot_id": "8f3a1c2e-...-b7d9",
      "status": "paused",
      "await_user": false,
      "last_activity_at": "2026-07-27T11:50:00Z",
      "expires_at": null,
      "started_at": "2026-07-27T11:30:00Z"
    }
  ],
  "meta": {
    "total": 2
  }
}
```

| Campo        | Descrição                                                                                  |
| ------------ | ------------------------------------------------------------------------------------------ |
| `success`    | `true` em caso de sucesso.                                                                 |
| `message`    | Resumo textual (ex.: `2 session(s) found`).                                                |
| `sessions`   | Lista das sessões `opened`, `paused` e `held`. Vazia quando não há conversas em andamento. |
| `meta.total` | Total de sessões retornadas.                                                               |

### Query params

<ParamField query="botId" type="string">
  UUID de um bot. Quando informado, retorna apenas as sessões daquele bot. Omitido, retorna as sessões de todos os bots da instância.
</ParamField>

***

## Controlar uma sessão

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

Pausa, retoma ou encerra **uma** conversa. O `jid` é derivado do `number` informado.

### Exemplo

<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 '{
      "botId":  "8f3a1c2e-...-b7d9",
      "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({
      botId:  "8f3a1c2e-...-b7d9",
      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={
          "botId":  "8f3a1c2e-...-b7d9",
          "number": "5511999999999",
          "status": "pause"
      }
  )
  ```

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

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

  func main() {
      body := strings.NewReader(`{
          "botId":  "8f3a1c2e-...-b7d9",
          "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>

### Resposta de sucesso

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

A `message` reflete a ação aplicada: `session paused`, `session resumed` ou `session closed`.

### Request body

<ParamField body="number" type="string" required>
  Número do contato no formato E.164 sem o `+` (ex.: `5511999999999`). O `jid` da sessão é derivado dele.
</ParamField>

<ParamField body="status" type="string" required>
  Ação a aplicar na conversa: `pause` (pausa o bot), `resume` (retoma) ou `close` (encerra a sessão). Valor fora dessa lista devolve `400`.
</ParamField>

<ParamField body="botId" type="string">
  UUID do bot da sessão. Opcional/informativo, ajuda a desambiguar quando o número tem sessões em mais de um bot.
</ParamField>

***

## Parâmetros de rota

<ParamField path="instance" type="string" required>
  Nome da instância (ex.: `suporte`).
</ParamField>

## Headers

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

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

## Erros

| HTTP | `error.message`                            | Causa                                                                                       |
| :--: | ------------------------------------------ | ------------------------------------------------------------------------------------------- |
|  400 | `invalid body: ...`                        | Body malformado, `number` ausente ou `status` fora de `pause`/`resume`/`close` (no `POST`). |
|  404 | `instance not found`                       | Instância não existe na RyzeAPI.                                                            |
|  404 | `no typebot integration for this instance` | A instância não tem integração/bot do Typebot.                                              |
|  503 | `integration gateway not configured`       | Serviço de integração indisponível no servidor.                                             |

## Próximo

<CardGroup cols={2}>
  <Card title="Listar bots" icon="list" href="/pt/api/typebot/list">
    Cada bot já traz `active_sessions` e `last_activity_at` no `GET /api/typebot/list/:instance`.
  </Card>

  <Card title="Iniciar fluxo" icon="play" href="/pt/api/typebot/start">
    Abra uma nova sessão manualmente com `POST /api/typebot/start/:instance`.
  </Card>
</CardGroup>