Sessões ao vivo

GET

api

typebot

sessions

:instance

Sessões ao vivo

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

const options = {
  method: 'GET',
  headers: {token: '<token>', 'Content-Type': '<content-type>'},
  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": "<content-type>"
}

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

print(response.text)

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.

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.

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

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:

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

Sessões de um bot (?botId=):

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",
    params={"botId": "8f3a1c2e-...-b7d9"},
    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?botId=8f3a1c2e-...-b7d9", nil)
    req.Header.Set("token", os.Getenv("Token_Account"))
    http.DefaultClient.Do(req)
}

Resposta de sucesso

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

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.

Controlar uma sessão

POST /api/typebot/sessions/:instance Pausa, retoma ou encerra uma conversa. O jid é derivado do number informado.

Exemplo

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

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

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

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

Resposta de sucesso

200 OK

{
  "success": true,
  "message": "session paused"
}

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

Request body

string

obrigatório

Número do contato no formato E.164 sem o + (ex.: 5511999999999). O jid da sessão é derivado dele.

string

obrigatório

Ação a aplicar na conversa: pause (pausa o bot), resume (retoma) ou close (encerra a sessão). Valor fora dessa lista devolve 400.

string

UUID do bot da sessão. Opcional/informativo, ajuda a desambiguar quando o número tem sessões em mais de um bot.

Parâmetros de rota

string

obrigatório

Nome da instância (ex.: suporte).

Headers

string

obrigatório

TokenAccount ou TokenInstance.

string

obrigatório

application/json (obrigatório no POST).

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.

Listar bots

Cada bot já traz active_sessions e last_activity_at no GET /api/typebot/list/:instance.

Iniciar fluxo

Abra uma nova sessão manualmente com POST /api/typebot/start/:instance.

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Sessões ao vivo

Descrição

Campos da sessão

Listar sessões

Exemplo

Resposta de sucesso

Query params

Controlar uma sessão

Exemplo

Resposta de sucesso

Request body

Parâmetros de rota

Headers

Erros

Próximo

Listar bots

Iniciar fluxo

​Descrição

​Campos da sessão

​Listar sessões

​Exemplo

​Resposta de sucesso

​Query params

​Controlar uma sessão

​Exemplo

​Resposta de sucesso

​Request body

​Parâmetros de rota

​Headers

​Erros

​Próximo

Listar bots

Iniciar fluxo

Descrição

Campos da sessão

Listar sessões

Exemplo

Resposta de sucesso

Query params

Controlar uma sessão

Exemplo

Resposta de sucesso

Request body

Parâmetros de rota

Headers

Erros

Próximo