Visão Geral

A RyzeAPI integra com o Typebot. Você cadastra bots conversacionais que conduzem a conversa no WhatsApp: a mensagem recebida é enviada ao fluxo do Typebot (startChat / continueChat) e as respostas voltam para o WhatsApp, incluindo texto, mídia e botões/listas nativos.

Como funciona

Você cria um bot com POST /api/typebot/set/:instance (ou inline, na criação da instância).
A cada mensagem recebida no WhatsApp, a RyzeAPI escolhe o bot pelo trigger e envia o texto ao fluxo do Typebot.
As respostas do fluxo voltam para a RyzeAPI e são entregues no WhatsApp.
A sessão fica persistida no servidor: reiniciar o serviço não perde a conversa em andamento.

Uma instância pode ter vários bots ao mesmo tempo, roteados por trigger. Um bot all funciona como catch-all (qualquer mensagem inicia); bots keyword só disparam quando a mensagem casa com o operador/valor configurado.

Também é possível não iniciar o bot quando o operador começou a conversa (noStartFromMe) e manter a conversa aberta ao terminar o fluxo (keepOpen, status held).

Botões e Pix pela marcação no texto

Nativamente o Typebot oferece só o botão de resposta (o nó de opções). Para enviar os outros botões do WhatsApp (link, ligação, copiar) e a mensagem de Pix, escreva uma marcação dentro de um balão de texto comum do seu fluxo. A RyzeAPI reconhece a marcação, retira ela do texto e envia a mensagem interativa correspondente; o texto que sobra no balão vira o corpo da mensagem.

Marcação	Vira
`[reply\|Texto]`	Botão de resposta. Ao tocar, o fluxo recebe `Texto` como se a pessoa tivesse digitado, então dá para ramificar por ele.
`[url:https://exemplo.com\|Texto]`	Botão que abre um link.
`[call:5511999999999\|Texto]`	Botão que liga para o número.
`[copy:CODIGO\|Texto]`	Botão que copia o código.
`[pix:Nome;Chave;Tipo\|Texto]`	Mensagem de Pix. `Tipo` é um de `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `RANDOM`.

Botões de resposta com um texto de apoio:

Clique no botão abaixo para saber mais:
[reply|Saber mais]
[reply|Encerrar]

Vários botões de link:

Confira nossos produtos:
[url:https://exemplo.com/1|Produto 1]
[url:https://exemplo.com/2|Produto 2]
[url:https://exemplo.com/3|Produto 3]

Cobrança por Pix:

Para finalizar, pague pelo Pix:
[pix:Minha Loja;chave@exemplo.com;EMAIL|Pagar]

O WhatsApp aceita no máximo 3 botões de resposta/link/ligação/copiar por mensagem. Se você escrever mais de 3, eles são enviados em blocos de 3. O Pix é uma mensagem própria, então sai sempre separado dos outros botões. O rótulo depois do | no [pix:...] não altera o botão de pagamento (o WhatsApp usa o rótulo nativo); o texto exibido acima do Pix é o restante do balão.

Não use os caracteres |, ] ou ; dentro do texto ou dos parâmetros, eles separam os campos da marcação. Um token malformado (tipo desconhecido, parâmetro faltando) é ignorado e o restante do texto do balão é enviado normalmente.

Padrão de resposta

Todos os endpoints do Typebot seguem o envelope padrão da API v2:

{ "success": true, "message": "...", "<conteúdo>": ..., "meta": { } }

O campo <conteúdo> varia por endpoint (bot, bots, sessions); meta aparece quando há contadores (total, deleted). Em caso de erro, o formato é { "success": false, "error": { "message": "...", "code": "...?" } }.

Endpoints de gerenciamento

Endpoint	O que faz
`POST /api/typebot/set/:instance`	Cria um bot (create-only; enviar `botId` retorna `400`).
`PATCH /api/typebot/update/:instance`	Edita parcialmente um bot existente (só os campos enviados mudam).
`GET /api/typebot/list/:instance?botId=`	Lista os bots (ou só um, com `?botId=`) + status da integração.
`DELETE /api/typebot/delete/:instance?botId=`	Remove um bot; sem `botId`, remove todos e desconecta a integração.
`POST /api/typebot/start/:instance`	Dispara um fluxo manualmente para um número.
`GET /api/typebot/sessions/:instance?botId=`	Lista as conversas ao vivo (`opened`/`paused`/`held`).
`POST /api/typebot/sessions/:instance`	Pausa, retoma ou encerra uma conversa.

Cadastrar bot

POST /api/typebot/set/:instance, cria um bot novo (somente criação).

Editar bot

PATCH /api/typebot/update/:instance, edição parcial de um bot existente.

Listar bots

GET /api/typebot/list/:instance?botId=, todos os bots (ou um) + status da integração.

Remover bot

DELETE /api/typebot/delete/:instance?botId=, remove um bot ou todos.

Iniciar fluxo

POST /api/typebot/start/:instance, dispara um fluxo manualmente para um número.

Sessões ao vivo

GET/POST /api/typebot/sessions/:instance, lista e controla as conversas em andamento.

Enriquecimento e sessões

Cada bot retornado por GET /api/typebot/list/:instance vem enriquecido com active_sessions (nº de conversas abertas + pausadas) e last_activity_at (última atividade em RFC3339, ausente se nunca houve). Para inspecionar e controlar cada conversa individualmente, use /api/typebot/sessions/:instance.

Roteamento por trigger

Cada mensagem recebida é avaliada contra os bots habilitados, na seguinte ordem de prioridade (uma palavra-chave específica vence o catch-all):

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

Ativação inline na criação da instância

Um bot pode ser configurado junto com a criação da instância, sem precisar chamar set separadamente. Basta enviar o bloco typebot* no body de POST /api/instance/new:

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

Se a ativação falhar (campos inválidos), a instância continua sendo criada, o objeto typebot retorna com status: "error" e error: "<mensagem>". Você pode então chamar POST /api/typebot/set/:instance para configurar o bot sem recriar a instância.

Modelo de dados

O servidor persiste os dados em duas tabelas:

Tabela	Descrição
`typebot_integrations`	Vínculo 1:1 entre a instância e a integração (`status`, `last_error`, `fallback_bot_id`).
`typebot_bots`	N bots por instância. Cada linha guarda `typebot_url`, `trigger_type` / `trigger_operator` / `trigger_value` e os flags de comportamento (`expire_minutes`, `keyword_finish`, `typing_delay_ms`, `stop_bot_from_me`, `debounce_seconds`, `ignore_groups`, `no_start_from_me`, `keep_open`, `enabled`).

Sempre que um bot é criado, editado ou removido, a RyzeAPI (re)ativa a integração da instância. Quando o último bot é removido, a integração é desativada e o vínculo local é apagado. Os campos active_sessions e last_activity_at não são persistidos: são calculados a partir das sessões ao vivo no momento da leitura.

Próximos passos

Cadastrar um bot

Configure o primeiro bot com POST /api/typebot/set/:instance.

Erros do Typebot

Tabela de mapeamento dos status HTTP e mensagens da integração.

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Como funciona

Botões e Pix pela marcação no texto

Padrão de resposta

Endpoints de gerenciamento

Cadastrar bot

Editar bot

Listar bots

Remover bot

Iniciar fluxo

Sessões ao vivo

Enriquecimento e sessões

Roteamento por trigger

Ativação inline na criação da instância

Modelo de dados

Próximos passos

Cadastrar um bot

Erros do Typebot

​Como funciona

​Botões e Pix pela marcação no texto

​Padrão de resposta

​Endpoints de gerenciamento

Cadastrar bot

Editar bot

Listar bots

Remover bot

Iniciar fluxo

Sessões ao vivo

​Enriquecimento e sessões

​Roteamento por trigger

​Ativação inline na criação da instância

​Modelo de dados

​Próximos passos

Cadastrar um bot

Erros do Typebot

Como funciona

Botões e Pix pela marcação no texto

Padrão de resposta

Endpoints de gerenciamento

Enriquecimento e sessões

Roteamento por trigger

Ativação inline na criação da instância

Modelo de dados

Próximos passos