Resumen

RyzeAPI se integra con Typebot. 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.

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.

Cómo funciona

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.
Con cada mensaje recibido en WhatsApp, RyzeAPI elige el bot por su trigger y envía el texto al flujo de Typebot.
Las respuestas del flujo vuelven a RyzeAPI y se entregan en WhatsApp.
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).

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.

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]

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.

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.

Endpoints de gestión

Crear bot

POST /api/typebot/set/:instance, crea un bot nuevo (solo creación).

Editar bot

PATCH /api/typebot/update/:instance, edición parcial de un bot existente (botId).

Listar bots

GET /api/typebot/list/:instance (o ?botId= para uno solo) + estado de la integración.

Eliminar bot

DELETE /api/typebot/delete/:instance (?botId= uno; sin botId = todos).

Iniciar flujo

POST /api/typebot/start/:instance, dispara un flujo manualmente para un número.

Sesiones en vivo

GET/POST /api/typebot/sessions/:instance, lista y controla las conversaciones en curso.

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:

{
  "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 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

Registrar un bot

Configura el primer bot con POST /api/typebot/set/:instance.

Errores de Typebot

Tabla de mapeo de los códigos de estado HTTP y mensajes de la integración.

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Cómo funciona

Botones y Pix con marcado en el texto

Endpoints de gestión

Crear bot

Editar bot

Listar bots

Eliminar bot

Iniciar flujo

Sesiones en vivo

Referencia de endpoints

Enrutamiento por trigger

Activación inline al crear la instancia

Modelo de datos

Próximos pasos

Registrar un bot

Errores de Typebot

​Cómo funciona

​Botones y Pix con marcado en el texto

​Endpoints de gestión

Crear bot

Editar bot

Listar bots

Eliminar bot

Iniciar flujo

Sesiones en vivo

​Referencia de endpoints

​Enrutamiento por trigger

​Activación inline al crear la instancia

​Modelo de datos

​Próximos pasos

Registrar un bot

Errores de Typebot

Cómo funciona

Botones y Pix con marcado en el texto

Endpoints de gestión

Referencia de endpoints

Enrutamiento por trigger

Activación inline al crear la instancia

Modelo de datos

Próximos pasos