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

# Cadastrar bot

> Cria um novo bot do Typebot na instância (somente criação)

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

<Warning>
  Para **editar** um bot existente use [`PATCH /api/typebot/update/:instance`](/pt/api/typebot/update). Enviar `botId` no body deste endpoint retorna **`400`** `botId is not allowed on create, use PATCH /api/typebot/update/:instance to edit`.
</Warning>

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

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

## Exemplo

<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 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`](/pt/api/typebot/update) com o `botId` (retornado por [`GET /api/typebot/list/:instance`](/pt/api/typebot/list)).
</Tip>

## Resposta de sucesso

```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-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](/pt/api/typebot/list). |
| `bot.id`  | UUID do bot, usado em `update`, `list?botId=`, `delete?botId=` e `start`.                              |

## Parâmetros de rota

<ParamField path="instance" type="string" required>
  Nome da instância (ex.: `suporte`).
</ParamField>

## Headers

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

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

## Request body

<ParamField body="typebotUrl" type="string" required>
  URL do Typebot **publicado** (viewer). Precisa ser uma URL válida. O `/` final é removido. Ex.: `https://typebot.co/meu-bot-abc123`.
</ParamField>

<ParamField body="triggerType" type="string" required>
  Como o bot é acionado: `all` (qualquer mensagem inicia o fluxo) ou `keyword` (só quando a mensagem casa com `triggerOperator` + `triggerValue`).
</ParamField>

<ParamField body="triggerOperator" type="string">
  Operador do gatilho, **obrigatório se** `triggerType` é `keyword`. Um de: `contains`, `equals`, `startsWith`, `endsWith`, `regex`.
</ParamField>

<ParamField body="triggerValue" type="string">
  Palavra ou expressão do gatilho, **obrigatória se** `triggerType` é `keyword`.
</ParamField>

<ParamField body="enabled" type="boolean" default="true">
  Se o bot está ativo no roteamento. Ausente equivale a `true`.
</ParamField>

<ParamField body="description" type="string">
  Rótulo do bot no painel (ex.: `"Bot de orçamento"`).
</ParamField>

<ParamField body="expireMinutes" type="integer" default="0">
  Expira a sessão por inatividade após N minutos. `0` = nunca expira.
</ParamField>

<ParamField body="expireMessage" type="string">
  Mensagem enviada ao usuário quando a sessão expira (se definida).
</ParamField>

<ParamField body="keywordFinish" type="string">
  Palavra que, enviada pelo usuário, finaliza o bot imediatamente (ex.: `"sair"`).
</ParamField>

<ParamField body="finishMessage" type="string">
  Despedida enviada quando o bot é finalizado pela `keywordFinish`.
</ParamField>

<ParamField body="typingDelayMs" type="integer" default="0">
  Delay do indicador "digitando..." antes de cada resposta, em milissegundos (convertido para segundos no envio).
</ParamField>

<ParamField body="stopBotFromMe" type="boolean" default="false">
  Se `true`, o bot é pausado naquela conversa quando você (o operador) responde manualmente.
</ParamField>

<ParamField body="debounceSeconds" type="integer" default="0">
  Junta fragmentos enviados pelo cliente por N segundos antes de processar (evita disparar o fluxo a cada linha).
</ParamField>

<ParamField body="ignoreGroups" type="boolean" default="true">
  Se `true`, mensagens de grupo não acionam o bot. Ausente equivale a `true`.
</ParamField>

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

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

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

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

## Próximo

<CardGroup cols={2}>
  <Card title="Editar bot" icon="pen-to-square" href="/pt/api/typebot/update">
    Ajuste campos de um bot existente com `PATCH /api/typebot/update/:instance`.
  </Card>

  <Card title="Listar bots" icon="list" href="/pt/api/typebot/list">
    Confira todos os bots da instância e o status da integração.
  </Card>

  <Card title="Iniciar fluxo" icon="play" href="/pt/api/typebot/start">
    Dispare o fluxo manualmente para um número com `POST /api/typebot/start/:instance`.
  </Card>

  <Card title="Sessões ao vivo" icon="comments" href="/pt/api/typebot/sessions">
    Liste e controle as conversas em andamento do bot.
  </Card>
</CardGroup>