Skip to content

Chat API

The Chat API is what a third-party chatbot integration calls to drive a conversation through a Hadron agent. Hadron compiles the system message and tool schema; the caller hosts the LLM, runs the turn, and reports the result back. Hadron handles routing, stage transitions, data extraction and history.

For the conceptual model behind the per-turn fields (topics, conversations, stages, edges, goals), see Conversation routing. This surface has no MCP equivalent — see MCP tools — Chat.

When to use this API vs. the portal

  • Use the portal for manual testing or when the agent is meant to be driven from inside the portal: an App's Chats tab → Agent chat runs a live chat, and the agent's Tester runs a scripted one. See Chatting with an agent and Test a chatbot with scripted personas.
  • Use this API when an external app (a website, a native client, an IVR) hosts the chat surface and the LLM call. The app passes user messages in and renders the assistant's replies; the routing logic stays in Hadron.

Surface

Four GraphQL mutations make up the Chat API:

Operation Purpose
startChat Open a chat. Returns the initial system message and tool schema.
sendChatMessage Save a user message and return a recompiled system message + history for the next LLM turn.
processChatResponse Save the LLM's structured response. Extracts data, evaluates routing edges, returns transitions.
saveChatSummary Persist a summary. Kept for compatibility; nothing requests summaries or uses them as summaries today (#1115).

There is no MCP equivalent. The hadron_chatbot_* MCP tools that mirrored these mutations were removed in hadron-server#1143; drive a chat through GraphQL or the portal.

Authentication

Every call carries an identity in ctx. The caller authenticates as one of:

Identity How What it binds
User (JWT) OAuth bearer token in the Authorization header. ctx.userId. Starting a chat takes two checks and is refused as AGENT_NOT_FOUND if either fails; org READER or a PUBLIC agent alone is not enough. See Who may start a chat. Other operations are scoped to the chat; see Errors.
App App key in the Authorization header (or your platform's app-key conventions). ctx.appId. Resolves to App.agentId. Personal-class memory is auto-keyed on (app_id, user_id).
Anonymous No identity. ctx.userId = "anonymous". No AgentSubscription is auto-provisioned; reads / writes that require one will fail.

App-keyed identity is the typical shape for third-party chatbot integrations — your service holds the App key, and you pass each end user's ID through to bind their personal memory. See Memory access for how user-vs-app identity flows through the four-gate access chain.

Per-turn loop

A typical session is one startChat plus N user turns. Each user turn is one sendChatMessage followed by one processChatResponse.

sequenceDiagram
    participant App as Caller
    participant Hadron
    participant LLM

    App->>Hadron: startChat(agentId, userId?, conversationName?)
    Hadron-->>App: {chatId, systemMessage, tools, conversationName, stageName}
    App->>LLM: systemMessage + tools (no user msg yet)
    LLM-->>App: respond({message, onTrack, data?, next_stage?})
    App->>Hadron: processChatResponse(chatId, {message, onTrack, data, next_stage})
    Hadron-->>App: {displayMessage, stageTransitioned, ...}
    Note over App: render welcome to user

    loop Per user turn
      App->>Hadron: sendChatMessage(chatId, userMessage)
      Hadron-->>App: {systemMessage, tools, messageHistory}
      App->>LLM: systemMessage + tools + messageHistory + userMessage
      LLM-->>App: respond({message, onTrack, data?, next_stage?})
      App->>Hadron: processChatResponse(chatId, {message, onTrack, data, next_stage})
      Hadron-->>App: {displayMessage, stageTransitioned, newStageName?, ...}
      Note over App: render displayMessage to user
    end

The LLM is always tool-calling the canonical respond tool — the schema for it is included in the tools field that startChat and sendChatMessage return. If your LLM returns plain text instead of a tool call, treat it as a bug in your provider adapter; the Hadron surface assumes structured responses.

Operations

startChat

Open a new chat with an agent. Hadron creates the chat node, provisions per-user memory if needed, and picks a starting conversation and stage: the one you name, or else the first ordinary conversation whose entry condition holds (how that order works). When none qualifies it tries the setup conversation, then the fallback, and otherwise refuses.

Inputs

Field Type Required Notes
agentId ID yes The agent to start the chat with.
userId ID no The end-user's ID. Defaults to ctx.userId for JWT identities. App-keyed callers should always pass this so personal memory is keyed correctly.
conversationName String no Open this conversation. A named start checks no entry condition. If omitted, the chat opens in the first ordinary conversation, in the author's order, whose entry condition holds for the person starting; see Starting a chat.

Returns

Field Type What it is
chatId ID Pass this to every subsequent call.
systemMessage String Compiled system prompt for the LLM — injected stages, agent persona, extraction spec, route history.
tools JSON The tool schema for the respond tool. Pass as-is to your LLM.
conversationName String The conversation the chat started in.
stageName String The starting stage.

Start refusals

Two refusals concern entry conditions. Both are GraphQL errors with a code and these extensions.

Code When Extensions
ENTRY_CONDITION_FAILED An unnamed start met an entry condition that could not be judged, and nothing was created. reason, messageId, detail.
INVALID_ENTRY_CONDITION A write tried to store a conversation entryCondition that is invalid or reads a scope other than memory.* and agent.*. This is a save error, not a start error. reason, detail. No messageId.

For ENTRY_CONDITION_FAILED, reason is one of MEMORY_ENCRYPTED_NO_KEY (the person's private memory is encrypted and the session has no key), MEMORY_UNREADABLE (the memory exists but this person may not read it), TYPE_MISMATCH (the condition compared values of incompatible types), or another condition-evaluation code when the stored condition is itself invalid. messageId is always a chat-start.error.* id: memory_encrypted_no_key, memory_unreadable, type_mismatch or invalid_condition. Show your own text for the id rather than relaying the server's. detail may carry conversation, field and operator, never a value, a memory URN or an edge id.

For INVALID_ENTRY_CONDITION, reason is one of the condition-validation codes, or SCOPE_NOT_AVAILABLE_AT_START for a chat.* or message.data.* variable, which has no value when a chat starts. detail may carry field and operator.

After startChat, run one LLM turn with no user message — the welcome turn — and feed the LLM's respond tool call into processChatResponse. The chat begins from the assistant's side.

sendChatMessage

Save the user's next message and return a refreshed compilation of the system message and history.

Inputs

Field Type Required
chatId ID yes
userMessage String yes

Returns

Field Type What it is
systemMessage String Recompiled — reflects the current stage and any goals on the stack.
tools JSON Same schema as startChat. Resend on every turn — agents can mutate.
messageHistory [Message!] Full chat so far in the order the LLM should see.
summarizationNeeded Object? Always null today: summarization is disarmed until the design in hadron-server#1115 lands. The field stays so existing callers don't break.

processChatResponse

Save the LLM's structured response, save any data fields to the memory the chat lives in (the user's for a private chat, the App's for a shared one), evaluate stage and conversation transitions, and return what the caller should render.

Inputs

Field Type Required Notes
chatId String yes
toolResponse JSON yes The model's respond tool call arguments, as one JSON object. Its fields are below.

Fields of toolResponse

Field Type Required Notes
message String yes The reply text the LLM produced.
data Object no Extracted facts. Each key is merged into the data node of the memory the chat lives in (auto-created if missing): the user's memory for a private chat, the App's memory for a shared one.
next_stage String no A bare stage name in the current conversation to move to. null stays on the current stage; it doesn't end the chat. A name that is not one of the conversation's stages moves nothing and comes back as rejectedNextStage. Ignored on a turn that sets goal_reached.
goal_reached Boolean no true completes the current conversation. Anything else, or absent, completes nothing. The field is in the respond tool schema that startChat and sendChatMessage return, so a caller forwards the model's whole tool call and does not add it. See Completing a conversation.
onTrack Boolean no Whether the current conversation still fits what the user is asking. The respond tool schema requires it of the model; processChatResponse treats a missing value as true.
offTrackReason String no The model's explanation when onTrack is false.

Returns

Field Type What it is
displayMessage String The text to render to the user. Usually equal to message; may be rewritten if a transition produced a hand-off.
stageTransitioned Boolean True if the next turn will start in a different stage than this turn ended in.
newStageName String? The new stage if stageTransitioned.
conversationHandoff String? The conversation the chat moved to when a rule targeting a conversation fired, or the fallback after a completion.
rejectedNextStage String? The stage name the turn asked for that is not one of the conversation's stages. The chat did not move and the turn is recorded. null when the name was accepted or none was given.
conversationCompleted String? The conversation this turn's goal_reached completed, or null.
detourReturned Boolean true when this turn returned the chat from a detour to the stage it left.
routingSkipped Boolean true when another turn moved the chat at the same moment, so this turn's routing changes were dropped. The reply is still saved; conversationCompleted, conversationHandoff and newStageName are null.
onTrack Boolean False when the LLM signalled onTrack: false in the tool call — the conversation has drifted. Today this is only recorded on the chat (with the reason); nothing re-routes on it.
offTrackReason String? The LLM's explanation when onTrack is false.
chatEnded Boolean Always false: a chat has no end. A completed conversation is reported as conversationCompleted.

A turn whose rule condition fails

If a rule condition fails while the turn is processed, the call errors with EDGE_CONDITION_FAILED and carries extensions.partialTurn:

{ "persisted": ["ASSISTANT_MESSAGE", "MESSAGE_COUNTER", "EXTRACTION"],
  "refused": [{ "component": "STAGE_PROGRESSION", "code": "EDGE_CONDITION_FAILED" }],
  "notRun": [] }

The assistant message and counter are saved; no routing change is applied. EXTRACTION is listed in persisted only when the extraction actually wrote data; extracting a value equal to the stored one writes nothing and is not listed. So do not repeat the call: the reply is already saved, and repeating it may append another. This report rests on a rule that is still Proposed (cor:cht:020:01), so treat it as how the server behaves today, not a guarantee.

Reading completed conversations

Chat.completedConversations is a list of the names of the conversations the chat has completed, in the order each was first completed. It is [] for a chat that has completed none, and for an encrypted chat. Read it with myChats or myChatsPage (the chat's host read gate applies). The route history and the goal stack are not readable through the API.

saveChatSummary

Summarization is disarmed

sendChatMessage no longer asks for summaries: summarizationNeeded is always null, and nothing uses a saved summary as a summary. The mutation still works so existing callers don't break, but the saved summary is replayed to the model as an ordinary turn alongside the messages it covers, so calling it makes the history longer, not shorter. Re-arming it needs the design in hadron-server#1115.

Stores a summary for a chat.

Inputs

Field Type Required
chatId ID yes
summary String yes

Returns true. There is no reason to call it today.

Who may start a chat

A start by a JWT caller must pass two checks, in order. A start that fails either one is refused as AGENT_NOT_FOUND before anything is written.

  1. The agent is reachable. This is necessary but not sufficient. It passes when the agent is PUBLIC, is the user's own, or is in an organization where the user holds at least READER (a platform admin also passes for an organization-owned agent), or when the user is a member of an App that has a licensed install of the agent.
  2. The chat's home admits the start. The home is the memory the chat will live in.
    • A home in an App needs the agent installed in that App and licensed (cor:acl:010:01).
    • A home with no App needs someone who manages the agent, acting as themselves and not impersonating: the organization's OWNERs and ADMINs, the owner of a user-owned agent, or a platform admin (cor:dmo:050:13).

Two refusals stay distinct from AGENT_NOT_FOUND: BOOT_PROMPT_INSTALL_LICENSE_INACTIVE and No target memory available for this chat. See Errors.

Errors

The Chat API throws plain Error instances with text messages, apart from the named refusals below (AGENT_NOT_FOUND, BOOT_PROMPT_INSTALL_LICENSE_INACTIVE). The most common shapes you'll see at the GraphQL boundary:

Message When
Forbidden The caller's role doesn't satisfy the agent's gate. A JWT start that fails the two agent and home checks is refused as AGENT_NOT_FOUND, not Forbidden. A start can still be Forbidden before those checks, for example when a user principal lacks the platform READER role or passes another user's userId without being an App key. App-keyed callers need an active AgentOrgGrant (cross-org) and active AgentSubscription for the user (personal-class). See Debug PERMISSION_DENIED errors.
AGENT_NOT_FOUND A JWT caller's start was not admitted: the agent is not visible to them, the home's App has no licensed install of it, or the home has no App and the caller does not manage the agent. Org READER or a PUBLIC agent alone is not enough to start. Nothing is written. See the User (JWT) row of the identity table.
BOOT_PROMPT_INSTALL_LICENSE_INACTIVE Raised at check 1, instead of AGENT_NOT_FOUND, only for a non-impersonating user who owns an App with no organization (a user-owned App) that still holds an install of the agent whose license has lapsed. Nothing is written. Any other caller whose start fails check 1 or check 2 gets AGENT_NOT_FOUND.
ENTRY_CONDITION_FAILED / INVALID_ENTRY_CONDITION A start could not judge a conversation's entry condition, or a save tried to store a bad one. See Start refusals.
EDGE_CONDITION_FAILED A rule condition failed during processChatResponse. The reply is saved and nothing was routed: see A turn whose rule condition fails.
Chat <chatId> not found The chat ID is invalid, soft-deleted, or scoped to a different user/app than the caller.
No system memory available The agent doesn't have a chatbot system memory attached. See Building a chatbot agent.
No target memory available for this chat The chat's personal-class memory could not be resolved or auto-provisioned. Usually a configuration issue with the App's Agent.memoryProvisioning.

If you need to disambiguate failure modes programmatically, match on the message prefix. A typed-error contract is on the roadmap but not in v1.

Spec drift

The canonical specification at hadron-concept/hadron-specs/Features/Chat-API.md is older than the implementation and is not authoritative. Treat the resolvers in hadron-server as the source of truth.

Concrete deltas you'll see if you compare:

  • processChatResponse returns more fields than the spec documents — conversationHandoff, chatEnded, onTrack, offTrackReason, conversationCompleted, detourReturned, routingSkipped and rejectedNextStage are all current and not in the spec.
  • data, next_stage and goal_reached are optional on the tool call. The spec implies message, data and next_stage are all required, and has no goal_reached.
  • Fallback rerouting on every turn. If the current conversation is marked isFallback: true and a non-fallback conversation matches via goalSignals (scanned in the author's start order), Hadron re-routes there on the next turn. The spec describes routing on session start only.
  • Summarization. The spec describes periodic summaries; the implementation has disarmed them (summarizationNeeded is always null, #1115).
  • No <metadata>JSON</metadata> fallback. The spec mentions it; the implementation only supports tool-call extraction.