Live sessions

GET

api

typebot

sessions

:instance

Live sessions

curl --request GET \
  --url https://api.example.com/api/typebot/sessions/:instance \
  --header 'Content-Type: application/json' \
  --header 'token: <token>' \
  --data '
{
  "number": "<string>",
  "status": "<string>",
  "botId": "<string>"
}
'

const options = {
  method: 'GET',
  headers: {token: '<token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({number: '<string>', status: '<string>', botId: '<string>'})
};

fetch('https://api.example.com/api/typebot/sessions/:instance', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/api/typebot/sessions/:instance"

payload = {
    "number": "<string>",
    "status": "<string>",
    "botId": "<string>"
}
headers = {
    "token": "<token>",
    "Content-Type": "application/json"
}

response = requests.get(url, json=payload, headers=headers)

print(response.text)

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.

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

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

curl -X GET "https://ryzeapi.cloud/api/typebot/sessions/suporte" \
  -H "token: $Token_Account"

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

import os, requests

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

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

Sessions of one bot

curl -X GET "https://ryzeapi.cloud/api/typebot/sessions/suporte?botId=8f3a1c2e-...-b7d9" \
  -H "token: $Token_Account"

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

import os, requests

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

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

Success response

200 OK

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

curl -X POST "https://ryzeapi.cloud/api/typebot/sessions/suporte" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "status": "pause"
  }'

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"
  })
});

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"
    }
)

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

Success response

200 OK

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

string

required

Contact number in E.164 format without the + (e.g., 5511999999999). The jid is derived from it.

string

required

Action to apply: pause, resume, or close.

string

UUID of the bot. Optional and informational, the conversation is located by number.

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

string

required

Instance name (e.g., suporte).

Query parameters

string

(GET only) UUID of a bot to restrict the listed sessions. Omitted, all the instance’s sessions are returned.

Headers

string

required

TokenAccount or TokenInstance.

string

application/json (required for POST).

List bots

See each bot’s active_sessions count with GET /api/typebot/list/:instance.

Start flow

Open a new conversation with POST /api/typebot/start/:instance.

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

Description

List live sessions

Example

Success response

Session fields

Errors

Control a session

Example

Success response

Request body

Errors

Path parameters

Query parameters

Headers

Next

List bots

Start flow

​Description

​List live sessions

​Example

​Success response

​Session fields

​Errors

​Control a session

​Example

​Success response

​Request body

​Errors

​Path parameters

​Query parameters

​Headers

​Next

List bots

Start flow

Description

List live sessions

Example

Success response

Session fields

Errors

Control a session

Example

Success response

Request body

Errors

Path parameters

Query parameters

Headers

Next