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

# Overview

> RyzeAPI's Typebot integration: conversational bots on WhatsApp, routed by trigger

RyzeAPI integrates with [Typebot](https://typebot.io). You register **conversational bots** that drive the conversation on WhatsApp: the incoming message is sent to the Typebot flow (`startChat` / `continueChat`) and the replies flow back to WhatsApp, including text, media, and native buttons/lists.

<Note>
  **Response shape**, every endpoint returns the envelope `{ "success": true, "message": "...", <content>, "meta": {...}? }` (there is no `data` wrapper). Errors return `{ "success": false, "error": { "message": "...", "code": "..."? } }`.
</Note>

## How it works

1. You register a bot with `POST /api/typebot/set/:instance` (or inline, when creating the instance).
2. On every message received on WhatsApp, RyzeAPI picks the bot by its **trigger** and sends the text to the Typebot flow.
3. The flow's replies flow back to RyzeAPI and are delivered on WhatsApp.
4. The session is persisted: restarting the service **does not lose** the ongoing conversation.

<Note>
  A single instance can have **several bots** at once, routed by trigger. An `all` bot works as a catch-all (any message starts it); `keyword` bots only fire when the message matches the configured operator/value.
</Note>

## Buttons and Pix via text markup

Natively, Typebot only offers the reply button (the choice node). To send the other WhatsApp buttons (link, call, copy) and a Pix message, write a small markup inside a regular **text bubble** in your flow. RyzeAPI recognizes the markup, strips it from the text, and sends the matching interactive message; whatever text remains in the bubble becomes the message body.

| Markup                             | Becomes                                                                                                 |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `[reply\|Label]`                   | Reply button. On tap, the flow receives `Label` as if the person had typed it, so you can branch on it. |
| `[url:https://example.com\|Label]` | Button that opens a link.                                                                               |
| `[call:5511999999999\|Label]`      | Button that calls the number.                                                                           |
| `[copy:CODE\|Label]`               | Button that copies the code.                                                                            |
| `[pix:Name;Key;Type\|Label]`       | Pix message. `Type` is one of `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `RANDOM`.                                |

Reply buttons with a supporting text:

```
Tap the button below to learn more:
[reply|Learn more]
[reply|End]
```

Several link buttons:

```
Check out our products:
[url:https://example.com/1|Product 1]
[url:https://example.com/2|Product 2]
[url:https://example.com/3|Product 3]
```

A Pix charge:

```
To finish, pay with Pix:
[pix:My Store;key@example.com;EMAIL|Pay]
```

<Note>
  WhatsApp allows at most **3 buttons** (reply/link/call/copy) per message. If you write more than 3, they are sent in groups of 3. Pix is its own message type, so it always goes out separately from the other buttons. The label after `|` in `[pix:...]` does not change the payment button (WhatsApp uses its native label); the text shown above the Pix button is the rest of the bubble.
</Note>

<Warning>
  Do not use the characters `|`, `]`, or `;` inside the text or the parameters, they separate the markup fields. A malformed token (unknown type, missing parameter) is ignored and the rest of the bubble text is sent normally.
</Warning>

## Management endpoints

<CardGroup cols={2}>
  <Card title="Create bot" icon="robot" href="/en/api/typebot/set">
    `POST /api/typebot/set/:instance`, creates a new bot (create-only).
  </Card>

  <Card title="Edit bot" icon="pen" href="/en/api/typebot/update">
    `PATCH /api/typebot/update/:instance`, partial update of an existing bot (by `botId`).
  </Card>

  <Card title="List bots" icon="list" href="/en/api/typebot/list">
    `GET /api/typebot/list/:instance?botId=`, the instance's bots (or one) with live enrichment + integration status.
  </Card>

  <Card title="Remove bot(s)" icon="trash" href="/en/api/typebot/delete">
    `DELETE /api/typebot/delete/:instance?botId=`, removes one bot, or all when `botId` is omitted.
  </Card>

  <Card title="Start flow" icon="play" href="/en/api/typebot/start">
    `POST /api/typebot/start/:instance`, triggers a flow manually for a number.
  </Card>

  <Card title="Live sessions" icon="comments" href="/en/api/typebot/sessions">
    `GET`/`POST /api/typebot/sessions/:instance`, list ongoing conversations or pause/resume/close one.
  </Card>
</CardGroup>

<Note>
  The list endpoint enriches each bot with `active_sessions` (count of opened + paused sessions) and `last_activity_at` (RFC3339, absent when the bot never ran).
</Note>

## Routing by trigger

Each incoming message is evaluated against the enabled bots, in the following **priority order** (a specific keyword beats the catch-all):

```
equals > startsWith / endsWith > contains > regex > all
```

**Uniqueness:** each instance can have only **one** enabled `all` bot; `keyword` bots are unique per combination of `(operator, value)`.

## Inline activation when creating the instance

A bot can be configured **together with instance creation**, without a separate `set` call. Just send the `typebot*` block in the body of [`POST /api/instance/new`](/en/api/instance/create):

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

If activation fails (invalid fields), the instance **is still created**, the `typebot` object comes back with `status: "error"` and `error: "<message>"`. You can then call [`POST /api/typebot/set/:instance`](/en/api/typebot/set) to configure the bot without recreating the instance.

## Data model

The server persists the data in two tables:

| Table                  | Description                                                                                                                                                                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `typebot_integrations` | 1:1 link between the instance and the integration (`status`, `last_error`, `fallback_bot_id`).                                                                                                                                                                |
| `typebot_bots`         | N bots per instance. Each row stores `typebot_url`, `trigger_type` / `trigger_operator` / `trigger_value` and the behavior flags (`expire_minutes`, `keyword_finish`, `typing_delay_ms`, `stop_bot_from_me`, `debounce_seconds`, `ignore_groups`, `enabled`). |

You can also keep the bot from auto-starting when the operator started the conversation (`noStartFromMe`), and keep the conversation open when the flow ends (`keepOpen`, status `held`).

Whenever a bot is created, edited, or removed, RyzeAPI recomputes the full list of the instance's bots and (re)activates the integration. When the last bot is removed, the integration is deactivated and the local link is deleted.

## Next steps

<CardGroup cols={2}>
  <Card title="Create a bot" icon="robot" href="/en/api/typebot/set">
    Configure the first bot with `POST /api/typebot/set/:instance`.
  </Card>

  <Card title="Typebot errors" icon="triangle-exclamation" href="/en/guide/errors">
    Mapping table of the integration's HTTP status codes and messages.
  </Card>
</CardGroup>