Listar bots

Auth: TokenAccount ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: sim

Descrição

Retorna os bots do Typebot cadastrados na instância, junto com o status e o last_error da integração. Passando ?botId=, retorna apenas aquele bot (a lista bots vem com um único item). O status local é complementado (best-effort) com o estado atual da integração, com timeout de 10s; se a consulta não responder, os valores locais são mantidos.

Este endpoint não retorna 503 quando a integração está indisponível: ele responde com os dados locais e, se houver, um last_error. O 503 integration gateway not configured só aparece em set, update e start.

Use GET /api/typebot/list/:instance?botId=<uuid> para inspecionar um único bot, substitui o antigo endpoint find.

Enriquecimento por bot

Cada bot da lista vem enriquecido com dois campos derivados das sessões ao vivo:

Campo	Descrição
`active_sessions`	Inteiro. Número de sessões abertas + pausadas (`opened` + `paused`) atribuídas ao bot no momento. `0` quando não há conversas em andamento.
`last_activity_at`	Data/hora (RFC3339) da última atividade em qualquer sessão do bot. Ausente quando o bot nunca teve atividade.

Exemplo

Todos os bots:

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

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

import os, requests

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

package main

import (
    "net/http"
    "os"
)

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

Um bot específico (?botId=):

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

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

import os, requests

requests.get(
    "https://ryzeapi.cloud/api/typebot/list/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/list/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": "1 bot(s) found",
  "status": "active",
  "last_error": "",
  "bots": [
    {
      "id": "8f3a1c2e-...-b7d9",
      "instance_id": "...",
      "enabled": true,
      "description": "Bot de orçamento",
      "typebot_url": "https://typebot.co/meu-bot-abc123",
      "trigger_type": "keyword",
      "trigger_operator": "contains",
      "trigger_value": "orçamento",
      "expire_minutes": 30,
      "expire_message": "Sessão encerrada por inatividade.",
      "keyword_finish": "sair",
      "finish_message": "Até logo! 👋",
      "typing_delay_ms": 1500,
      "stop_bot_from_me": true,
      "debounce_seconds": 6,
      "ignore_groups": true,
      "no_start_from_me": false,
      "keep_open": false,
      "active_sessions": 2,
      "last_activity_at": "2026-07-27T11:58:03Z",
      "created_at": "2026-07-20T09:00:00Z",
      "updated_at": "2026-07-27T12:00:00Z"
    }
  ],
  "meta": {
    "total": 1
  }
}

Campo	Descrição
`success`	`true` em caso de sucesso.
`message`	Resumo textual (ex.: `2 bot(s) found`).
`status`	Estado da integração: `active` / `paused` / `error`. Vazio quando não há integração ativa.
`last_error`	Última mensagem de erro da integração. Vazio quando saudável.
`bots`	Lista dos bots (ou o único filtrado por `?botId=`). Vazia quando não há bots.
`bots[].id`	UUID do bot.
`bots[].instance_id`	ID interno da instância dona do bot.
`bots[].enabled`	Se o bot está ativo no roteamento.
`bots[].description`	Rótulo do bot no painel.
`bots[].typebot_url`	URL do Typebot publicado (viewer).
`bots[].trigger_type`	`all` ou `keyword`.
`bots[].trigger_operator`	`contains` / `equals` / `startsWith` / `endsWith` / `regex` (presente quando `trigger_type` é `keyword`).
`bots[].trigger_value`	Palavra/expressão do gatilho (presente quando `trigger_type` é `keyword`).
`bots[].expire_minutes`	Minutos de inatividade até a sessão expirar (`0` = nunca).
`bots[].expire_message`	Mensagem enviada ao expirar a sessão.
`bots[].keyword_finish`	Palavra que finaliza o bot.
`bots[].finish_message`	Despedida enviada ao finalizar por palavra-chave.
`bots[].typing_delay_ms`	Delay do “digitando…” antes de cada resposta (ms).
`bots[].stop_bot_from_me`	Pausa o bot quando o operador responde na conversa.
`bots[].debounce_seconds`	Segundos de agrupamento de fragmentos antes de processar.
`bots[].ignore_groups`	Ignora mensagens de grupo.
`bots[].no_start_from_me`	Booleano. Não inicia o bot quando o operador começou a conversa.
`bots[].keep_open`	Booleano. Mantém a conversa aberta ao fim do fluxo, status `held`.
`bots[].active_sessions`	Enriquecimento, sessões abertas + pausadas do bot agora (`0` se nenhuma).
`bots[].last_activity_at`	Enriquecimento, última atividade (RFC3339); ausente se nunca houve.
`bots[].created_at`	Data/hora de criação do bot (RFC3339).
`bots[].updated_at`	Data/hora da última edição do bot (RFC3339).
`meta.total`	Total de bots retornados.

Parâmetros de rota

string

obrigatório

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

Query params

string

UUID de um bot específico. Quando informado, retorna apenas aquele bot (lista bots com um único item, meta.total: 1). Omitido, retorna todos os bots da instância. Se o botId não existir na instância, retorna 404.

Headers

string

obrigatório

TokenAccount ou TokenInstance.

Comportamento

Lê os bots locais

Consulta a tabela typebot_bots da instância (ou a linha do botId, se filtrado). Esta etapa é rápida e sempre funciona.

Enriquece com as sessões ao vivo

Para cada bot, calcula active_sessions (opened + paused) e last_activity_at a partir das sessões correntes.

Lê o vínculo da integração

Busca a linha em typebot_integrations para obter status e last_error locais.

Complementa com o estado da integração (best-effort)

Se houver integração, a RyzeAPI consulta o estado atual com timeout de 10s e sobrescreve status / last_error com os valores live. Em caso de falha de rede, mantém os locais.

Erros

HTTP	`error.message`
404	`instance not found`
404	`bot not found for this instance` (quando `?botId=` não existe)

Editar bot

Ajuste os campos de um bot com PATCH /api/typebot/update/:instance.

Sessões ao vivo

Liste e controle as conversas em andamento com GET/POST /api/typebot/sessions/:instance.

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Descrição

Enriquecimento por bot

Exemplo

Resposta de sucesso

Parâmetros de rota

Query params

Headers

Comportamento

Erros

Próximo

Editar bot

Sessões ao vivo

​Descrição

​Enriquecimento por bot

​Exemplo

​Resposta de sucesso

​Parâmetros de rota

​Query params

​Headers

​Comportamento

​Erros

​Próximo

Editar bot

Sessões ao vivo

Descrição

Enriquecimento por bot

Exemplo

Resposta de sucesso

Parâmetros de rota

Query params

Headers

Comportamento

Erros

Próximo