> ## 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.
# Listar bots
> Lista os bots do Typebot da instância (ou só um, com ?botId=) e o status da integração
**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=` 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:**
```bash cURL theme={null}
curl -X GET "https://ryzeapi.cloud/api/typebot/list/suporte" \
-H "token: $Token_Account"
```
```javascript JavaScript theme={null}
await fetch("https://ryzeapi.cloud/api/typebot/list/suporte", {
method: "GET",
headers: {
"token": process.env.Token_Account
}
});
```
```python Python theme={null}
import os, requests
requests.get(
"https://ryzeapi.cloud/api/typebot/list/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/list/suporte", nil)
req.Header.Set("token", os.Getenv("Token_Account"))
http.DefaultClient.Do(req)
}
```
**Um bot específico (`?botId=`):**
```bash cURL theme={null}
curl -X GET "https://ryzeapi.cloud/api/typebot/list/suporte?botId=8f3a1c2e-...-b7d9" \
-H "token: $Token_Account"
```
```javascript JavaScript theme={null}
await fetch("https://ryzeapi.cloud/api/typebot/list/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/list/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/list/suporte?botId=8f3a1c2e-...-b7d9", nil)
req.Header.Set("token", os.Getenv("Token_Account"))
http.DefaultClient.Do(req)
}
```
## Resposta de sucesso
```json 200 OK theme={null}
{
"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
Nome da instância (ex.: `suporte`).
## Query params
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
`TokenAccount` ou `TokenInstance`.
## Comportamento
Consulta a tabela `typebot_bots` da instância (ou a linha do `botId`, se filtrado). Esta etapa é rápida e sempre funciona.
Para cada bot, calcula `active_sessions` (opened + paused) e `last_activity_at` a partir das sessões correntes.
Busca a linha em `typebot_integrations` para obter `status` e `last_error` locais.
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) |
## Próximo
Ajuste os campos de um bot com `PATCH /api/typebot/update/:instance`.
Liste e controle as conversas em andamento com `GET/POST /api/typebot/sessions/:instance`.