Overview

RyzeAPI integrates with Typebot. 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.

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

How it works

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

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.

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]

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.

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.

Management endpoints

Create bot

POST /api/typebot/set/:instance, creates a new bot (create-only).

Edit bot

PATCH /api/typebot/update/:instance, partial update of an existing bot (by botId).

List bots

GET /api/typebot/list/:instance?botId=, the instance’s bots (or one) with live enrichment + integration status.

Remove bot(s)

DELETE /api/typebot/delete/:instance?botId=, removes one bot, or all when botId is omitted.

Start flow

POST /api/typebot/start/:instance, triggers a flow manually for a number.

Live sessions

GET/POST /api/typebot/sessions/:instance, list ongoing conversations or pause/resume/close one.

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

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:

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

Create a bot

Configure the first bot with POST /api/typebot/set/:instance.

Typebot errors

Mapping table of the integration’s HTTP status codes and messages.

Introduction

Instance

Events

Messages

Calls

Groups

Communities

Newsletter

Profile

Chat

Chatwoot

Typebot

Observability

How it works

Buttons and Pix via text markup

Management endpoints

Create bot

Edit bot

List bots

Remove bot(s)

Start flow

Live sessions

Routing by trigger

Inline activation when creating the instance

Data model

Next steps

Create a bot

Typebot errors

​How it works

​Buttons and Pix via text markup

​Management endpoints

Create bot

Edit bot

List bots

Remove bot(s)

Start flow

Live sessions

​Routing by trigger

​Inline activation when creating the instance

​Data model

​Next steps

Create a bot

Typebot errors

How it works

Buttons and Pix via text markup

Management endpoints

Routing by trigger

Inline activation when creating the instance

Data model

Next steps