Skip to main content
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.
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 — list the factory, project and team channels you may read
  • GET /api/v3/chat-sessions/{sessionId} — getChatSession — fetch a session by ID
  • GET /api/v3/chat-sessions/{sessionId}/messages — listChatMessages — list messages in a session
Writes:
  • POST /api/v3/chat-channels/{channelId}/sessions — createChatSession — open a new session in a channel
  • POST /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: