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

# Resumen

> Integración de RyzeAPI con Typebot: bots conversacionales en WhatsApp, enrutados por trigger

RyzeAPI se integra con [Typebot](https://typebot.io). Registras **bots conversacionales** que conducen la conversación en WhatsApp: el mensaje recibido se envía al flujo de Typebot (`startChat` / `continueChat`) y las respuestas vuelven a WhatsApp, incluyendo texto, media y botones/listas nativos.

<Note>
  **Formato de respuesta (v2)**, todas las respuestas exitosas siguen el envelope `{ "success": true, "message": "...", <contenido>, "meta": {...}? }` (ya no usan `data`). Los errores siguen `{ "success": false, "error": { "message": "...", "code": "..."? } }`. Además, `list` **enriquece** cada bot con `active_sessions` y `last_activity_at`.
</Note>

## Cómo funciona

1. Registras un bot con `POST /api/typebot/set/:instance` (solo creación; para editar, `PATCH /api/typebot/update/:instance`) o inline, al crear la instancia.
2. Con cada mensaje recibido en WhatsApp, RyzeAPI elige el bot por su **trigger** y envía el texto al flujo de Typebot.
3. Las respuestas del flujo vuelven a RyzeAPI y se entregan en WhatsApp.
4. La sesión se persiste en el servidor: reiniciar el servicio **no pierde** la conversación en curso.

También puedes evitar que el bot inicie solo cuando el operador empezó la conversación (`noStartFromMe`) y mantener la conversación abierta al terminar el flujo (`keepOpen`, estado `held`).

<Note>
  Una instancia puede tener **varios bots** al mismo tiempo, enrutados por trigger. Un bot `all` funciona como catch-all (cualquier mensaje lo inicia); los bots `keyword` solo se disparan cuando el mensaje coincide con el operador/valor configurado.
</Note>

## Botones y Pix con marcado en el texto

De forma nativa, Typebot solo ofrece el botón de respuesta (el nodo de opciones). Para enviar los demás botones de WhatsApp (enlace, llamada, copiar) y el mensaje de Pix, escribe un marcado dentro de un **globo de texto** normal de tu flujo. RyzeAPI reconoce el marcado, lo quita del texto y envía el mensaje interactivo correspondiente; el texto que queda en el globo se convierte en el cuerpo del mensaje.

| Marcado                            | Se convierte en                                                                                                             |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `[reply\|Texto]`                   | Botón de respuesta. Al tocarlo, el flujo recibe `Texto` como si la persona lo hubiera escrito, así puedes ramificar por él. |
| `[url:https://ejemplo.com\|Texto]` | Botón que abre un enlace.                                                                                                   |
| `[call:5511999999999\|Texto]`      | Botón que llama al número.                                                                                                  |
| `[copy:CODIGO\|Texto]`             | Botón que copia el código.                                                                                                  |
| `[pix:Nombre;Clave;Tipo\|Texto]`   | Mensaje de Pix. `Tipo` es uno de `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `RANDOM`.                                                 |

Botones de respuesta con un texto de apoyo:

```
Toca el botón de abajo para saber más:
[reply|Saber más]
[reply|Finalizar]
```

Varios botones de enlace:

```
Mira nuestros productos:
[url:https://ejemplo.com/1|Producto 1]
[url:https://ejemplo.com/2|Producto 2]
[url:https://ejemplo.com/3|Producto 3]
```

Un cobro por Pix:

```
Para finalizar, paga con Pix:
[pix:Mi Tienda;clave@ejemplo.com;EMAIL|Pagar]
```

<Note>
  WhatsApp acepta como máximo **3 botones** (respuesta/enlace/llamada/copiar) por mensaje. Si escribes más de 3, se envían en bloques de 3. El Pix es un tipo de mensaje aparte, así que siempre sale separado de los demás botones. La etiqueta después del `|` en `[pix:...]` no cambia el botón de pago (WhatsApp usa su etiqueta nativa); el texto que aparece encima del Pix es el resto del globo.
</Note>

<Warning>
  No uses los caracteres `|`, `]` ni `;` dentro del texto o de los parámetros, separan los campos del marcado. Un token mal formado (tipo desconocido, parámetro faltante) se ignora y el resto del texto del globo se envía normalmente.
</Warning>

## Endpoints de gestión

<CardGroup cols={2}>
  <Card title="Crear bot" icon="robot" href="/es/api/typebot/set">
    `POST /api/typebot/set/:instance`, crea un bot nuevo (solo creación).
  </Card>

  <Card title="Editar bot" icon="pen" href="/es/api/typebot/update">
    `PATCH /api/typebot/update/:instance`, edición parcial de un bot existente (`botId`).
  </Card>

  <Card title="Listar bots" icon="list" href="/es/api/typebot/list">
    `GET /api/typebot/list/:instance` (o `?botId=` para uno solo) + estado de la integración.
  </Card>

  <Card title="Eliminar bot" icon="trash" href="/es/api/typebot/delete">
    `DELETE /api/typebot/delete/:instance` (`?botId=` uno; sin `botId` = todos).
  </Card>

  <Card title="Iniciar flujo" icon="play" href="/es/api/typebot/start">
    `POST /api/typebot/start/:instance`, dispara un flujo manualmente para un número.
  </Card>

  <Card title="Sesiones en vivo" icon="comments" href="/es/api/typebot/sessions">
    `GET/POST /api/typebot/sessions/:instance`, lista y controla las conversaciones en curso.
  </Card>
</CardGroup>

## Referencia de endpoints

| Método   | Ruta                              | Descripción                                                                       |
| -------- | --------------------------------- | --------------------------------------------------------------------------------- |
| `POST`   | `/api/typebot/set/:instance`      | Crea un bot nuevo (solo creación).                                                |
| `PATCH`  | `/api/typebot/update/:instance`   | Edición parcial de un bot existente (`botId` obligatorio).                        |
| `GET`    | `/api/typebot/list/:instance`     | Lista los bots (`?botId=` filtra uno) con `active_sessions` + `last_activity_at`. |
| `DELETE` | `/api/typebot/delete/:instance`   | Elimina un bot (`?botId=`) o todos (sin `botId`).                                 |
| `POST`   | `/api/typebot/start/:instance`    | Inicia un flujo manualmente para un número.                                       |
| `GET`    | `/api/typebot/sessions/:instance` | Lista las conversaciones en vivo (`?botId=` filtra por bot).                      |
| `POST`   | `/api/typebot/sessions/:instance` | Controla una sesión: `pause` / `resume` / `close`.                                |

## Enrutamiento por trigger

Cada mensaje recibido se evalúa contra los bots habilitados, en el siguiente **orden de prioridad** (una palabra clave específica vence al catch-all):

```
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 `(operator, value)`.

## Activación inline al crear la instancia

Un bot puede configurarse **junto con la creación de la instancia**, sin necesidad de llamar a `set` por separado. Solo incluye el bloque `typebot*` en el cuerpo de [`POST /api/instance/new`](/es/api/instance/create):

```json theme={null}
{
  "name": "suporte",
  "typebotEnabled": true,
  "typebotUrl": "https://typebot.co/meu-bot-abc123",
  "typebotTriggerType": "all"
}
```

Si la activación falla (campos inválidos), la instancia **se crea de todos modos**, el objeto `typebot` regresa con `status: "error"` y `error: "<mensaje>"`. Luego puedes llamar a [`POST /api/typebot/set/:instance`](/es/api/typebot/set) para configurar el bot sin recrear la instancia.

## Modelo de datos

El servidor persiste los datos en dos tablas:

| Tabla                  | Descripción                                                                                                                                                                                                                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `typebot_integrations` | Vínculo 1:1 entre la instancia y la integración (`status`, `last_error`, `fallback_bot_id`).                                                                                                                                                                                                            |
| `typebot_bots`         | N bots por instancia. Cada fila guarda `typebot_url`, `trigger_type` / `trigger_operator` / `trigger_value` y los flags de comportamiento (`expire_minutes`, `keyword_finish`, `typing_delay_ms`, `stop_bot_from_me`, `debounce_seconds`, `ignore_groups`, `no_start_from_me`, `keep_open`, `enabled`). |

Siempre que un bot se crea, edita o elimina, RyzeAPI activa la integración de la instancia. Cuando se elimina el último bot, la integración se desactiva y el vínculo local se borra.

## Próximos pasos

<CardGroup cols={2}>
  <Card title="Registrar un bot" icon="robot" href="/es/api/typebot/set">
    Configura el primer bot con `POST /api/typebot/set/:instance`.
  </Card>

  <Card title="Errores de Typebot" icon="triangle-exclamation" href="/es/guide/errors">
    Tabla de mapeo de los códigos de estado HTTP y mensajes de la integración.
  </Card>
</CardGroup>