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 onlyfactory,projectandteamchannels. - 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, ornull),text(ornull),tool,agentName(ornull), andauthoredByCaller(truewhen your key or External App wrote it). A session that touched restricted knowledge returns agent-authored text redacted.
Row visibility
Every chat operation is decided at the channel’s home org unit. A channel is usable only when it is afactory, 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 — list the factory, project and team channels you may readGET /api/v3/chat-sessions/{sessionId}— getChatSession — fetch a session by IDGET /api/v3/chat-sessions/{sessionId}/messages— listChatMessages — list messages in a session
POST /api/v3/chat-channels/{channelId}/sessions— createChatSession — open a new session in a channelPOST /api/v3/chat-sessions/{sessionId}/messages— sendChatMessage — record a message in a session (starts no agent turn)
Common workflows
Open a session and post the first message: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:
Related
- Chat overview — conceptual background on Hybrid Workforce Chat
- Channels and sessions — the chat data model
- Native HTTP quickstart — call these endpoints with
fetchand a bearer token

