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

# Chat

> Drive Hybrid Workforce Chat — channels, sessions, and messages — from external systems.

Hybrid Workforce Chat is the platform's conversation layer between humans and agents. Messages live inside Sessions, Sessions live inside Channels. The Chat domain lets external integrations list the channels they may use, open sessions, read transcripts, and record messages in a session.

> [!NOTE]
>
> A message sent through this API is recorded in the session; no agent turn is started, so no agent replies to it and no Trust Fabric hold follows from it. Agents reply to messages people send in the Forge Console.

## Resource shape

* **Channel** (`ChatChannel`) — scoping container. The API shows only `factory`, `project` and `team` channels.
* **Session** (`ChatSession`) — finite conversation inside a channel.
* **Message** (`ChatMessage`) — one turn in a session's transcript: `id`, `createdAt`, `order`, `stepOrder`, `status`, `role` (`user`, `assistant`, `tool`, `system`, or `null`), `text` (or `null`), `tool`, `agentName` (or `null`), and `authoredByCaller` (`true` when your key or External App wrote it). A session that touched restricted knowledge returns agent-authored text redacted.

Each schema is an explicit allowlist: routing settings, the home org unit, participants, the agent thread and model details are never returned.

## Row visibility

Every chat operation is decided at the channel's home org unit. A channel is usable only when it is a `factory`, `project` or `team` channel with a home org unit, and your key or External App holds the operation's permission there, or at an org unit above it: `chat:read` for the three reads, `chat:manage` to create a session, and `chat:use` to send a message. Direct messages, personal-assistant chats, group conversations and builder (`system`) channels are never visible to a key or External App, whatever it holds.

A session is reachable only through its channel. A session with restricted participants is visible only to the key or External App that started it. A missing, malformed or unusable channel or session answers `404 resource_missing`, exactly like one that does not exist.

## Paging

`listChannels` and `listMessages` page with a cursor. Pass `meta.nextCursor` back as `cursor` while `meta.hasMore` is `true`. A page can hold fewer rows than `limit`, or none, while `meta.hasMore` is still `true`: rows you may not read are left out and never counted. `listChannels` pages are at most 50 rows and `listMessages` pages at most 200; a larger `limit` is `400` `too_big`. A `limit` that is not a positive integer, an empty or repeated `cursor` or `limit`, or a cursor the server cannot read is `400 bad_request`. On `listChannels`, each `activeSessionCount` reads at most 201 sessions and a page counts at most 1,000 sessions in total; `meta.partial` is `true` when a count on the page stopped at either bound, and that count is then a lower bound.

## Operations

Reads:

* `GET /api/v3/chat-channels` — [listChatChannels](https://docs.gloo.com/forge/reference/http-api/chat) — list the factory, project and team channels you may read
* `GET /api/v3/chat-sessions/{sessionId}` — [getChatSession](https://docs.gloo.com/forge/reference/http-api/chat) — fetch a session by ID
* `GET /api/v3/chat-sessions/{sessionId}/messages` — [listChatMessages](https://docs.gloo.com/forge/reference/http-api/chat) — list messages in a session

Writes:

* `POST /api/v3/chat-channels/{channelId}/sessions` — [createChatSession](https://docs.gloo.com/forge/reference/http-api/chat) — open a new session in a channel
* `POST /api/v3/chat-sessions/{sessionId}/messages` — [sendChatMessage](https://docs.gloo.com/forge/reference/http-api/chat) — record a message in a session (starts no agent turn)

## Common workflows

Open a session and post the first message:

```bash theme={null}
curl -X POST "$FORGE_BASE/api/v3/chat-channels/ch_abc/sessions" \
  -H "Authorization: Bearer $FORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Triage GH-1234"}'

curl -X POST "$FORGE_BASE/api/v3/chat-sessions/sess_xyz/messages" \
  -H "Authorization: Bearer $FORGE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Triage this issue: ...", "contentType": "text"}'
```

`createSession` answers `201` with `{ "id": "<sessionId>" }`; `sendMessage` answers `201` with `{ "messageId": "...", "sessionId": "..." }`. `createSession` refuses `linkedEntityType` and `linkedEntityId` with `400 bad_request`, and a channel that is archived answers `409 invalid_state`.

Read back a transcript, following the cursor:

```bash theme={null}
curl "$FORGE_BASE/api/v3/chat-sessions/sess_xyz/messages?limit=50" \
  -H "Authorization: Bearer $FORGE_TOKEN"
# then, while meta.hasMore is true:
curl "$FORGE_BASE/api/v3/chat-sessions/sess_xyz/messages?limit=50&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $FORGE_TOKEN"
```

## Related

* [Chat overview](https://docs.gloo.com/forge/build/talk-to-agents.md) — conceptual background on Hybrid Workforce Chat
* [Channels and sessions](https://docs.gloo.com/forge/build/talk-to-agents.md) — the chat data model
* [Native HTTP quickstart](https://docs.gloo.com/forge/quickstart.md#raw-http) — call these endpoints with `fetch` and a bearer token


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.