> ## 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. # Visão Geral > Integração da RyzeAPI com o Typebot: bots conversacionais no WhatsApp, roteados por trigger A RyzeAPI integra com o [Typebot](https://typebot.io). 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 1. Você cria um bot com `POST /api/typebot/set/:instance` (ou inline, na criação da instância). 2. A cada mensagem recebida no WhatsApp, a RyzeAPI escolhe o bot pelo **trigger** e envia o texto ao fluxo do Typebot. 3. As respostas do fluxo voltam para a RyzeAPI e são entregues no WhatsApp. 4. 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: ```json theme={null} { "success": true, "message": "...", "": ..., "meta": { } } ``` O campo `` 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. | `POST /api/typebot/set/:instance`, cria um bot novo (somente criação). `PATCH /api/typebot/update/:instance`, edição parcial de um bot existente. `GET /api/typebot/list/:instance?botId=`, todos os bots (ou um) + status da integração. `DELETE /api/typebot/delete/:instance?botId=`, remove um bot ou todos. `POST /api/typebot/start/:instance`, dispara um fluxo manualmente para um número. `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`](/pt/api/typebot/list) 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`](/pt/api/typebot/sessions). ## 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`](/pt/api/instance/create): ```json theme={null} { "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: ""`. Você pode então chamar [`POST /api/typebot/set/:instance`](/pt/api/typebot/set) 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 Configure o primeiro bot com `POST /api/typebot/set/:instance`. Tabela de mapeamento dos status HTTP e mensagens da integração.