Como testar fluxos do Fluxo Controlado via API

Quando usar

• Você quer automatizar testes de Fluxos Controlados em CI/CD ou via Postman/Insomnia
• Você precisa validar interações programaticamente antes de publicar em produção
• Você está integrando o Fluxo Controlado com outro sistema que precisa enviar mensagens via HTTP

Pré-requisitos

• Workspace do Fluxo Controlado com pelo menos um fluxo criado
• API Token do Fluxo Controlado gerado (passo a passo abaixo)
• Cliente HTTP (Postman, Insomnia, curl etc.)

Sobre este artigo

A API do Fluxo Controlado permite iniciar e continuar conversas automaticamente com fluxos criados, via chamadas HTTP. Essa funcionalidade é ideal para testes automatizados e validação de fluxos antes de publicar.

Visão geral da integração

A comunicação com o Fluxo Controlado é feita em duas etapas:

1. Início da conversa — cria uma nova sessão de chat

2. Continuidade da conversa — envia mensagens dentro da sessão criada

As chamadas usam endpoints HTTP autenticados com token Bearer e o ID do fluxo criado no Fluxo Controlado.

Passo a passo

Etapa 1 — Obter o ID do fluxo

Cada fluxo criado no Fluxo Controlado possui um identificador único (ID), usado para iniciar a sessão via API. Esse ID pode ser copiado:

• Diretamente da URL de edição do fluxo

• Ou da tela de publicação

Etapa 2 — Iniciar uma nova sessão de conversa

Endpoint:

POST https://eddieeyes.us-east-1.prd.cloudhumans.io/api/v1/typebots/ID_DO_FLUXO/startChat

Headers obrigatórios:

• Content-Type: application/json

• Authorization: Bearer {{apiToken}}

Resposta esperada:

{ "sessionId": "abc123xyz" }

Etapa 3 — Enviar mensagens para continuar o chat

Endpoint:

POST https://eddieeyes.us-east-1.prd.cloudhumans.io/api/v1/sessions/{{sessionId}}/continueChat

Headers:

• Content-Type: application/json

• Authorization: Bearer {{apiToken}}

Body:

{ "message": "mensagem do usuário" }

Resposta: objeto JSON com a próxima interação gerada pelo Fluxo Controlado com base na lógica do fluxo.

Como gerar um API Token

Para autenticar as chamadas via API, você precisa de um API Token. Siga os passos abaixo:

1. Clique em Configurações e membros no canto superior direito da tela

2. No menu lateral, selecione Minha conta

3. Na seção API tokens, clique em Criar para gerar um novo token

Boas práticas para uso da API

Armazenamento e reuso do sessionId

Guarde o sessionId gerado para cada conversa. Ele é necessário para manter a continuidade da interação com o mesmo contexto.

Testes antes da integração final

Use Postman ou Insomnia para validar:

• Endpoints

• Headers

• Corpo (body) e respostas

Isso evita erros no ambiente de produção.

Monitoramento de erros

Falhas em chamadas (dados inválidos, endpoints incorretos, timeout) aparecem no Hub com sinalização de erro. Use essas informações para diagnóstico rápido.

Observações

• Para entender as chamadas de API que o Fluxo Controlado faz internamente: Como criar um fluxo no Fluxo Controlado com API externa

• Para reduzir falhas em chamadas: Como reduzir erros de chamada do Fluxo Controlado para aumentar a retenção

• Para entender requisitos de API que o Fluxo Controlado consome: Requisitos de API para utilização no Fluxo Controlado