> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API de Chat de Flow Conversacional

> Use os endpoints de chat da implantação para executar Flows conversacionais multi-turno no CrewAI AMP

## Visão Geral

Flows conversacionais implantados expõem uma API de sessão de chat na URL da automação. Em vez de uma única execução `/kickoff`, você cria uma sessão, envia mensagens do usuário como turnos, opcionalmente transmite tokens e eventos de runtime, e retoma pausas HITL quando um turno precisa de feedback humano.

<Note>
  O chat de Flow conversacional é **experimental**. Os endpoints só ficam disponíveis quando o Flow implantado reporta `conversational: true` e `handle_turn: true` em [`GET /inspect`](#descobrir-capacidade-de-chat).
</Note>

Para construir o Flow em si (`conversational = True`, `handle_turn`, routers, tracing), consulte o guia open-source [Conversational Flows](https://docs.crewai.com/en/guides/flows/conversational-flows).

## Pré-requisitos

1. Implante uma automação Flow que implemente turnos conversacionais (`handle_turn`).
2. Copie o bearer token da aba **Status** da automação (o mesmo token usado em `/kickoff`).
3. Confirme que o chat está habilitado via `/inspect` (abaixo).

Todas as requisições usam:

```bash theme={null}
Authorization: Bearer YOUR_FLOW_TOKEN
```

Os exemplos deste guia usam a base `https://your-flow-url.crewai.com`.

## Descobrir capacidade de chat

```bash theme={null}
curl -X GET \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  https://your-flow-url.crewai.com/inspect
```

Procure por `flow.chat`:

```json theme={null}
{
  "flow": {
    "chat": {
      "conversational": true,
      "handle_turn": true,
      "transports": ["webhook"],
      "experimental": true
    }
  }
}
```

Se qualquer flag for falsa, os endpoints de chat retornam `404` com `"Conversational flow chat is not available"`.

## Loop de chat ponta a ponta

<Steps>
  <Step title="Iniciar uma sessão">
    Crie uma sessão de chat. Opcionalmente registre um webhook de turno concluído e webhooks de eventos para a vida da sessão.

    ```bash theme={null}
    curl -X POST \
      -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "completedTurnWebhookUrl": "https://your-server.com/webhooks/completed-turn",
        "webhooks": {
          "url": "https://your-server.com/webhooks/events",
          "events": ["*"],
          "realtime": false,
          "authentication": {
            "strategy": "bearer",
            "token": "my-secret-token"
          }
        }
      }' \
      https://your-flow-url.crewai.com/chat/start
    ```

    Resposta:

    ```json theme={null}
    { "session_id": "11111111-2222-3333-4444-555555555555" }
    ```

    Um body vazio (`{}` ou sem body) é válido quando você não precisa de webhooks.
  </Step>

  <Step title="Enviar uma mensagem do usuário">
    Enfileire um turno para a sessão:

    ```bash theme={null}
    curl -X POST \
      -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "message": "Where is my order?",
        "stream": true
      }' \
      https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/message
    ```

    Resposta:

    ```json theme={null}
    {
      "session_id": "11111111-2222-3333-4444-555555555555",
      "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "status": "queued"
    }
    ```

    | Campo            | Descrição                                                                                                                                                                     |
    | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `message`        | Obrigatório. Mensagem atual do usuário neste turno.                                                                                                                           |
    | `stream`         | Padrão `true`. Quando `true`, frames de token/evento são publicados para clientes WebSocket/SSE.                                                                              |
    | `messageHistory` | Transcript de fallback opcional (`[{ "role", "content" }, ...]`). O histórico da sessão no servidor é autoritativo; isso só é usado quando o histórico armazenado está vazio. |

    Roles aceitos em `messageHistory`: `user`, `assistant`, `system`, `tool`.
  </Step>

  <Step title="Aguardar o fim do turno">
    Faça polling do turno com o `kickoff_id` retornado (mesma API de status de um kickoff normal de Flow):

    ```bash theme={null}
    curl -X GET \
      -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
      https://your-flow-url.crewai.com/status/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
    ```

    Apenas um turno pode ficar ativo por sessão. Um segundo `/message` enquanto `active_kickoff_id` estiver definido retorna `409`:

    ```json theme={null}
    {
      "detail": {
        "code": "session_busy",
        "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
      }
    }
    ```

    Aguarde até o histórico mostrar `active_kickoff_id: null` (ou o turno atingir status terminal / pausa) antes de enviar a próxima mensagem.
  </Step>

  <Step title="Ler o histórico da sessão">
    ```bash theme={null}
    curl -X GET \
      -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
      https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/history
    ```

    ```json theme={null}
    {
      "session_id": "11111111-2222-3333-4444-555555555555",
      "messages": [
        { "role": "user", "content": "Where is my order?" },
        { "role": "assistant", "content": "Your order is on the way." }
      ],
      "active_kickoff_id": null
    }
    ```
  </Step>
</Steps>

## Streaming de um turno

O streaming é opcional. Use quando a UI precisar de tokens ou eventos de runtime durante o turno. Os frames sempre incluem tipos de ciclo de vida (`turn_started`, `turn_completed`, `turn_failed`, `token`, `error`). Frames `event` adicionais podem ser filtrados com o query param `events` (`*` ou lista separada por vírgulas).

### Opção A: mensagem HTTP + anexar SSE

1. `POST /chat/{session_id}/message` com `"stream": true`.
2. Anexe-se ao turno ativo:

```bash theme={null}
curl -N \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  "https://your-flow-url.crewai.com/chat/11111111-2222-3333-4444-555555555555/stream/events?events=*&last_event_id=0-0"
```

SSE retorna frames JSON `text/event-stream` (`data: {...}`), mais comentários de keepalive. O stream termina em `turn_completed` ou `turn_failed`.

Se não houver turno ativo, este endpoint retorna `409` (`No active chat turn`).

### Opção B: WebSocket (anexar ou enviar)

```text theme={null}
wss://your-flow-url.crewai.com/chat/{session_id}/stream?token=YOUR_FLOW_TOKEN&events=*&last_event_id=0-0
```

Auth: passe o bearer token como query param `token`, ou como header `Authorization: Bearer ...` quando o cliente suportar headers em WebSocket.

Comportamento:

* **Turno ativo já em execução** — o socket anexa e emite primeiro `turn_started` com `data.status: "attached"`, depois transmite frames até um tipo terminal.
* **Sem turno ativo** — envie uma mensagem JSON para enfileirar um turno e então consuma o stream:

```json theme={null}
{
  "message": "Where is my order?",
  "messageHistory": [],
  "events": "*",
  "lastEventId": "0-0"
}
```

O servidor responde com `turn_started` (`status: "queued"`) e então frames do stream para aquele `kickoff_id`.

Use `last_event_id` / `lastEventId` para retomar após desconexões.

### Exemplos de frames do stream

```json theme={null}
{
  "type": "turn_started",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": { "status": "queued" }
}
```

```json theme={null}
{
  "type": "token",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": { "content": "Your order" }
}
```

```json theme={null}
{
  "type": "turn_completed",
  "kickoff_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "data": {}
}
```

## HITL dentro de uma sessão de chat

Se um turno pausar para feedback humano (`status` / estado `PAUSED`), retome com o mesmo endpoint de resume de Flow usado em execuções sem chat:

```bash theme={null}
curl -X POST \
  -H "Authorization: Bearer YOUR_FLOW_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "FLOW_OR_SESSION_ID",
    "feedback": "approved"
  }' \
  https://your-flow-url.crewai.com/resume_feedback
```

Em seguida, faça polling do `kickoff_id` de resume da resposta. Aguarde até `/history` mostrar `active_kickoff_id: null` antes de enviar a próxima mensagem de chat.

Veja [Workflows HITL](/platform/pt-BR/guides/human-in-the-loop) e [Gerenciamento HITL para Flows](/platform/pt-BR/features/flow-hitl-management) para a UX de revisão na plataforma.

## Referência da API

| Método | Path                               | Propósito                                          |
| ------ | ---------------------------------- | -------------------------------------------------- |
| `GET`  | `/inspect`                         | Descobrir se o chat conversacional está habilitado |
| `POST` | `/chat/start`                      | Criar uma sessão de chat                           |
| `POST` | `/chat/{session_id}/message`       | Enfileirar um turno do usuário                     |
| `GET`  | `/chat/{session_id}/history`       | Ler mensagens e id do turno ativo                  |
| `GET`  | `/chat/{session_id}/stream/events` | Stream SSE do turno ativo                          |
| `WS`   | `/chat/{session_id}/stream`        | Stream WebSocket (anexar ou enviar + stream)       |
| `GET`  | `/status/{kickoff_id}`             | Polling do status de execução do turno (ou resume) |
| `POST` | `/resume_feedback`                 | Retomar um turno HITL pausado                      |

### Erros comuns

| Status | Quando                                                                    |
| ------ | ------------------------------------------------------------------------- |
| `400`  | `message` vazio                                                           |
| `404`  | Chat não habilitado nesta implantação, ou `session_id` desconhecido       |
| `409`  | Sessão já tem turno ativo (`session_busy`), ou anexar SSE sem turno ativo |
| `422`  | `session_id` não é um UUID válido                                         |
| `503`  | Armazenamento de sessão ou stream de chat indisponível                    |

## Relacionados

<CardGroup cols={2}>
  <Card title="Conversational Flows" href="https://docs.crewai.com/en/guides/flows/conversational-flows" icon="comments">
    Construa Flows multi-turno com `handle_turn`, routers e tracing.
  </Card>

  <Card title="Kickoff Crew / Flow" href="/platform/pt-BR/guides/kickoff-crew" icon="flag-checkered">
    Kickoff de execução única e polling de status na URL da implantação.
  </Card>

  <Card title="Webhook Streaming" href="/platform/pt-BR/features/webhook-streaming" icon="webhook">
    Formato do payload de webhook de eventos e opções de autenticação.
  </Card>

  <Card title="Gerenciamento HITL para Flows" href="/platform/pt-BR/features/flow-hitl-management" icon="users-gear">
    Revisão humana com email-first para etapas pausadas de Flow.
  </Card>
</CardGroup>