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

# Crear bot

> Crea un bot de Typebot para la instancia (solo creación)

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

<Warning>
  Para **editar** un bot existente usa [`PATCH /api/typebot/update/:instance`](/es/api/typebot/update). Enviar `botId` en el body de este endpoint retorna **`400`** `botId is not allowed on create, use PATCH /api/typebot/update/:instance to edit`.
</Warning>

<Note>
  **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`.
</Note>

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

## Ejemplo

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  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
    })
  });
  ```

  ```python Python theme={null}
  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
      }
  )
  ```

  ```go Go theme={null}
  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)
  }
  ```
</CodeGroup>

<Tip>
  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`](/es/api/typebot/update) con el `botId` (devuelto por [`GET /api/typebot/list/:instance`](/es/api/typebot/list)).
</Tip>

## Respuesta exitosa

```json 201 Created theme={null}
{
  "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](/es/api/typebot/list). |
| `bot.id`  | UUID del bot, usado en `update`, `start` y `delete`.                                                      |

## Parámetros de ruta

<ParamField path="instance" type="string" required>
  Nombre de la instancia (p. ej., `suporte`).
</ParamField>

## Cabeceras

<ParamField header="token" type="string" required>
  `TokenAccount` o `TokenInstance`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

## Cuerpo de la solicitud

<ParamField body="typebotUrl" type="string" required>
  URL del Typebot **publicado** (viewer). Debe ser una URL válida. La `/` final se elimina. Ej.: `https://typebot.co/meu-bot-abc123`.
</ParamField>

<ParamField body="triggerType" type="string" required>
  Cómo se acciona el bot: `all` (cualquier mensaje inicia el flujo) o `keyword` (solo cuando el mensaje coincide con `triggerOperator` + `triggerValue`).
</ParamField>

<ParamField body="triggerOperator" type="string">
  Operador del trigger, **requerido si** `triggerType` es `keyword`. Uno de: `contains`, `equals`, `startsWith`, `endsWith`, `regex`.
</ParamField>

<ParamField body="triggerValue" type="string">
  Palabra o expresión del trigger, **requerida si** `triggerType` es `keyword`.
</ParamField>

<ParamField body="enabled" type="boolean" default="true">
  Si el bot está activo en el enrutamiento. Ausente equivale a `true`.
</ParamField>

<ParamField body="description" type="string">
  Etiqueta del bot en el panel (p. ej., `"Bot de orçamento"`).
</ParamField>

<ParamField body="expireMinutes" type="integer" default="0">
  Expira la sesión por inactividad tras N minutos. `0` = nunca expira.
</ParamField>

<ParamField body="expireMessage" type="string">
  Mensaje enviado al usuario cuando la sesión expira (si está definido).
</ParamField>

<ParamField body="keywordFinish" type="string">
  Palabra que, enviada por el usuario, finaliza el bot de inmediato (p. ej., `"sair"`).
</ParamField>

<ParamField body="finishMessage" type="string">
  Despedida enviada cuando el bot se finaliza por la `keywordFinish`.
</ParamField>

<ParamField body="typingDelayMs" type="integer" default="0">
  Delay del indicador "escribiendo..." antes de cada respuesta, en milisegundos (convertido a segundos en el envío).
</ParamField>

<ParamField body="stopBotFromMe" type="boolean" default="false">
  Si es `true`, el bot se pausa en esa conversación cuando tú (el operador) respondes manualmente.
</ParamField>

<ParamField body="debounceSeconds" type="integer" default="0">
  Agrupa los fragmentos enviados por el cliente durante N segundos antes de procesar (evita disparar el flujo con cada línea).
</ParamField>

<ParamField body="ignoreGroups" type="boolean" default="true">
  Si es `true`, los mensajes de grupo no accionan el bot. Ausente equivale a `true`.
</ParamField>

<ParamField body="noStartFromMe" type="boolean" default="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).
</ParamField>

<ParamField body="keepOpen" type="boolean" default="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`.
</ParamField>

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

```json theme={null}
{
  "success": false,
  "error": {
    "message": "triggerOperator and triggerValue are required when triggerType is 'keyword'"
  }
}
```

## Siguiente

<CardGroup cols={2}>
  <Card title="Editar bot" icon="pen" href="/es/api/typebot/update">
    Edita parcialmente un bot existente con `PATCH /api/typebot/update/:instance`.
  </Card>

  <Card title="Listar bots" icon="list" href="/es/api/typebot/list">
    Consulta todos los bots de la instancia y el estado de la integración.
  </Card>
</CardGroup>