Cadastrar bot

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

Descrição

Cria um novo bot do Typebot para a instância. Este endpoint é somente criação (create-only): a cada bot criado a RyzeAPI ativa a integração da instância.

Para editar um bot existente use PATCH /api/typebot/update/:instance. Enviar botId no body deste endpoint retorna 400 botId is not allowed on create, use PATCH /api/typebot/update/:instance to edit.

Prioridade de trigger, quando várias regras podem casar com a mesma mensagem, a mais específica vence:

equals > startsWith / endsWith > contains > regex > all

Unicidade, cada instância pode ter apenas um bot all habilitado; bots keyword são únicos por combinação de (triggerOperator, triggerValue). Tentar criar um conflito devolve 400.

A typebotUrl deve apontar para um Typebot publicado (viewer). O / final é removido. Esta operação tem timeout interno de 60s.

Exemplo

curl -X POST "https://ryzeapi.cloud/api/typebot/set/suporte" \
  -H "token: $Token_Account" \
  -H "Content-Type: application/json" \
  -d '{
    "typebotUrl":      "https://typebot.co/meu-bot-abc123",
    "triggerType":     "keyword",
    "triggerOperator": "contains",
    "triggerValue":    "orçamento",
    "enabled":         true,
    "description":     "Bot de orçamento",
    "expireMinutes":   30,
    "expireMessage":   "Sessão encerrada por inatividade.",
    "keywordFinish":   "sair",
    "finishMessage":   "Até logo! 👋",
    "typingDelayMs":   1500,
    "stopBotFromMe":   true,
    "debounceSeconds": 6,
    "ignoreGroups":    true
  }'

await fetch("https://ryzeapi.cloud/api/typebot/set/suporte", {
  method: "POST",
  headers: {
    "token":        process.env.Token_Account,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    typebotUrl:      "https://typebot.co/meu-bot-abc123",
    triggerType:     "keyword",
    triggerOperator: "contains",
    triggerValue:    "orçamento",
    enabled:         true,
    description:     "Bot de orçamento",
    expireMinutes:   30,
    expireMessage:   "Sessão encerrada por inatividade.",
    keywordFinish:   "sair",
    finishMessage:   "Até logo! 👋",
    typingDelayMs:   1500,
    stopBotFromMe:   true,
    debounceSeconds: 6,
    ignoreGroups:    true
  })
});

import os, requests

requests.post(
    "https://ryzeapi.cloud/api/typebot/set/suporte",
    headers={
        "token":        os.environ["Token_Account"],
        "Content-Type": "application/json"
    },
    json={
        "typebotUrl":      "https://typebot.co/meu-bot-abc123",
        "triggerType":     "keyword",
        "triggerOperator": "contains",
        "triggerValue":    "orçamento",
        "enabled":         True,
        "description":     "Bot de orçamento",
        "expireMinutes":   30,
        "expireMessage":   "Sessão encerrada por inatividade.",
        "keywordFinish":   "sair",
        "finishMessage":   "Até logo! 👋",
        "typingDelayMs":   1500,
        "stopBotFromMe":   True,
        "debounceSeconds": 6,
        "ignoreGroups":    True
    }
)

package main

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

func main() {
    body := strings.NewReader(`{
        "typebotUrl":      "https://typebot.co/meu-bot-abc123",
        "triggerType":     "keyword",
        "triggerOperator": "contains",
        "triggerValue":    "orçamento",
        "enabled":         true,
        "description":     "Bot de orçamento",
        "expireMinutes":   30,
        "expireMessage":   "Sessão encerrada por inatividade.",
        "keywordFinish":   "sair",
        "finishMessage":   "Até logo! 👋",
        "typingDelayMs":   1500,
        "stopBotFromMe":   true,
        "debounceSeconds": 6,
        "ignoreGroups":    true
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/typebot/set/suporte", body)
    req.Header.Set("token", os.Getenv("Token_Account"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Para o bot mais simples, envie só typebotUrl + triggerType: "all": ele responde a qualquer mensagem. Para editar um bot já existente, use PATCH /api/typebot/update/:instance com o botId (retornado por GET /api/typebot/list/:instance).

Resposta de sucesso

201 Created

{
  "success": true,
  "message": "typebot bot created",
  "bot": {
    "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": 0,
    "created_at": "2026-07-27T12:00:00Z",
    "updated_at": "2026-07-27T12:00:00Z"
  }
}

Campo	Descrição
`success`	`true` em caso de sucesso.
`message`	Mensagem fixa de confirmação (`typebot bot created`).
`bot`	O bot recém-criado, já com o `id` gerado. Veja todos os campos em listar bots.
`bot.id`	UUID do bot, usado em `update`, `list?botId=`, `delete?botId=` e `start`.

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

Request body

string

obrigatório

URL do Typebot publicado (viewer). Precisa ser uma URL válida. O / final é removido. Ex.: https://typebot.co/meu-bot-abc123.

string

obrigatório

Como o bot é acionado: all (qualquer mensagem inicia o fluxo) ou keyword (só quando a mensagem casa com triggerOperator + triggerValue).

string

Operador do gatilho, obrigatório se triggerType é keyword. Um de: contains, equals, startsWith, endsWith, regex.

string

Palavra ou expressão do gatilho, obrigatória se triggerType é keyword.

boolean

padrão:"true"

Se o bot está ativo no roteamento. Ausente equivale a true.

string

Rótulo do bot no painel (ex.: "Bot de orçamento").

integer

padrão:"0"

Expira a sessão por inatividade após N minutos. 0 = nunca expira.

string

Mensagem enviada ao usuário quando a sessão expira (se definida).

string

Palavra que, enviada pelo usuário, finaliza o bot imediatamente (ex.: "sair").

string

Despedida enviada quando o bot é finalizado pela keywordFinish.

integer

padrão:"0"

Delay do indicador “digitando…” antes de cada resposta, em milissegundos (convertido para segundos no envio).

boolean

padrão:"false"

Se true, o bot é pausado naquela conversa quando você (o operador) responde manualmente.

integer

padrão:"0"

Junta fragmentos enviados pelo cliente por N segundos antes de processar (evita disparar o fluxo a cada linha).

boolean

padrão:"true"

Se true, mensagens de grupo não acionam o bot. Ausente equivale a true.

boolean

padrão:"false"

Se true, o bot não inicia sozinho quando você começou a conversa. Quando você envia a primeira mensagem e o contato responde, o bot não dispara. A janela de reativação reaproveita expireMinutes (contada a partir da sua primeira mensagem; 0 = permanente).

boolean

padrão:"false"

Se true, ao terminar o fluxo a conversa fica aberta em vez de encerrar. O bot fica em silêncio (não reinicia) e a sessão só encerra pela keywordFinish ou manualmente, aparecendo com status held.

Erros

HTTP	`error.message`	Causa
400	`invalid body: ...`	Body malformado, `typebotUrl` inválida ou `triggerType` fora de `all`/`keyword`.
400	`botId is not allowed on create, use PATCH /api/typebot/update/:instance to edit`	`botId` enviado no body. Este endpoint é somente criação; edite via `PATCH /update`.
400	`triggerOperator and triggerValue are required when triggerType is 'keyword'`	`triggerType: "keyword"` sem operador/valor.
400	`this instance already has an enabled 'all' trigger bot`	Já existe um bot `all` habilitado (unicidade).
400	`another enabled bot already uses this trigger operator+value`	Já existe um bot `keyword` habilitado com o mesmo `(operator, value)`.
404	`instance not found`	Instância não existe na RyzeAPI.
500	`create bot: ...`	Falha de persistência local ou na (re)ativação da integração.
503	`integration gateway not configured`	Serviço de integração indisponível no servidor.

Exemplo de payload de erro

Trigger keyword sem operador/valor:

{
  "success": false,
  "error": {
    "message": "triggerOperator and triggerValue are required when triggerType is 'keyword'"
  }
}

Editar bot

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

Listar bots

Confira todos os bots da instância e o status da integração.

Iniciar fluxo

Dispare o fluxo manualmente para um número com POST /api/typebot/start/:instance.

Sessões ao vivo

Liste e controle as conversas em andamento do bot.

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Descrição

Exemplo

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Erros

Exemplo de payload de erro

Próximo

Editar bot

Listar bots

Iniciar fluxo

Sessões ao vivo

​Descrição

​Exemplo

​Resposta de sucesso

​Parâmetros de rota

​Headers

​Request body

​Erros

​Exemplo de payload de erro

​Próximo

Editar bot

Listar bots

Iniciar fluxo

Sessões ao vivo

Descrição

Exemplo

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Erros

Exemplo de payload de erro

Próximo