Crear bot

Auth: TokenAccount o TokenInstance • Rate limit: Global (100/min) • Idempotente: no

Descripción

Crea un bot de Typebot para la instancia. Este endpoint es solo de creación (create-only): siempre registra un bot nuevo. RyzeAPI activa la integración de la instancia.

Para editar un bot existente usa PATCH /api/typebot/update/:instance. Enviar botId en el body de este endpoint retorna 400 botId is not allowed on create, use PATCH /api/typebot/update/:instance to edit.

Prioridad de trigger, cuando varias reglas pueden coincidir con el mismo mensaje, gana la más específica:

equals > startsWith / endsWith > contains > regex > all

Unicidad, cada instancia puede tener solo un bot all habilitado; los bots keyword son únicos por combinación de (triggerOperator, triggerValue). Intentar crear un conflicto devuelve 400.

La typebotUrl debe apuntar a un Typebot publicado (viewer). La / final se elimina. Esta operación tiene un timeout interno de 60 s.

Ejemplo

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 el bot más simple, envía solo typebotUrl + triggerType: "all": responde a cualquier mensaje. Para editar un bot ya existente, no uses este endpoint: usa PATCH /api/typebot/update/:instance con el botId (devuelto por GET /api/typebot/list/:instance).

Respuesta exitosa

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-27T14:03:11Z",
    "updated_at": "2026-07-27T14:03:11Z"
  }
}

Campo	Descripción
`success`	`true` cuando la operación tuvo éxito.
`message`	Mensaje fijo de confirmación: `typebot bot created`.
`bot`	El bot creado, ya con el `id` generado. Consulta todos los campos en listar bots.
`bot.id`	UUID del bot, usado en `update`, `start` y `delete`.

Parámetros de ruta

string

requerido

Nombre de la instancia (p. ej., suporte).

Cabeceras

string

requerido

TokenAccount o TokenInstance.

string

requerido

application/json

Cuerpo de la solicitud

string

requerido

URL del Typebot publicado (viewer). Debe ser una URL válida. La / final se elimina. Ej.: https://typebot.co/meu-bot-abc123.

string

requerido

Cómo se acciona el bot: all (cualquier mensaje inicia el flujo) o keyword (solo cuando el mensaje coincide con triggerOperator + triggerValue).

string

Operador del trigger, requerido si triggerType es keyword. Uno de: contains, equals, startsWith, endsWith, regex.

string

Palabra o expresión del trigger, requerida si triggerType es keyword.

boolean

predeterminado:"true"

Si el bot está activo en el enrutamiento. Ausente equivale a true.

string

Etiqueta del bot en el panel (p. ej., "Bot de orçamento").

integer

predeterminado:"0"

Expira la sesión por inactividad tras N minutos. 0 = nunca expira.

string

Mensaje enviado al usuario cuando la sesión expira (si está definido).

string

Palabra que, enviada por el usuario, finaliza el bot de inmediato (p. ej., "sair").

string

Despedida enviada cuando el bot se finaliza por la keywordFinish.

integer

predeterminado:"0"

Delay del indicador “escribiendo…” antes de cada respuesta, en milisegundos (convertido a segundos en el envío).

boolean

predeterminado:"false"

Si es true, el bot se pausa en esa conversación cuando tú (el operador) respondes manualmente.

integer

predeterminado:"0"

Agrupa los fragmentos enviados por el cliente durante N segundos antes de procesar (evita disparar el flujo con cada línea).

boolean

predeterminado:"true"

Si es true, los mensajes de grupo no accionan el bot. Ausente equivale a true.

boolean

predeterminado:"false"

Si es true, el bot no inicia solo cuando tú empezaste la conversación. Cuando envías el primer mensaje y el contacto responde, el bot no se dispara. La ventana de reactivación reutiliza expireMinutes (contada desde tu primer mensaje; 0 = permanente).

boolean

predeterminado:"false"

Si es true, al terminar el flujo la conversación permanece abierta en lugar de cerrarse. El bot permanece en silencio (no reinicia) y la sesión solo se cierra por keywordFinish o manualmente, apareciendo con estado held.

Errores

HTTP	`error.message`	Causa
400	`invalid body: ...`	Body malformado, `typebotUrl` inválida o `triggerType` fuera de `all`/`keyword`.
400	`botId is not allowed on create, use PATCH /api/typebot/update/:instance to edit`	Se envió `botId`: este endpoint es solo de creación. Para editar, usa `PATCH /update`.
400	`triggerOperator and triggerValue are required when triggerType is 'keyword'`	`triggerType: "keyword"` sin operador/valor.
400	`this instance already has an enabled 'all' trigger bot`	Ya existe un bot `all` habilitado (unicidad).
400	`another enabled bot already uses this trigger operator+value`	Ya existe un bot `keyword` habilitado con el mismo `(operator, value)`.
404	`instance not found`	La instancia no existe en RyzeAPI.
500	`create bot: ...` / `activate typebot integration: ...`	Fallo de persistencia local o en la (re)activación de la integración.
503	`integration gateway not configured`	Servicio de integración no disponible en el servidor.

Ejemplo de payload de error

Trigger keyword sin operador/valor:

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

Editar bot

Edita parcialmente un bot existente con PATCH /api/typebot/update/:instance.

Listar bots

Consulta todos los bots de la instancia y el estado de la integración.

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Descripción

Ejemplo

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Errores

Ejemplo de payload de error

Siguiente

Editar bot

Listar bots

​Descripción

​Ejemplo

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Errores

​Ejemplo de payload de error

​Siguiente

Editar bot

Listar bots

Descripción

Ejemplo

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Errores

Ejemplo de payload de error

Siguiente