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.
- 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 leastREADER(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. - 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).
- A home in an App needs the agent installed in that App and licensed (
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:
processChatResponsereturns more fields than the spec documents —conversationHandoff,chatEnded,onTrack,offTrackReason,conversationCompleted,detourReturned,routingSkippedandrejectedNextStageare all current and not in the spec.data,next_stageandgoal_reachedare optional on the tool call. The spec impliesmessage,dataandnext_stageare all required, and has nogoal_reached.- Fallback rerouting on every turn. If the current
conversation is marked
isFallback: trueand a non-fallback conversation matches viagoalSignals(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 (
summarizationNeededis alwaysnull, #1115). - No
<metadata>JSON</metadata>fallback. The spec mentions it; the implementation only supports tool-call extraction.
Related¶
- Conversation routing — model behind
the per-turn fields (
onTrack,next_stage, edges, goals). - Building a chatbot agent — the agent setup this API assumes.
- Memory access — how
userId/appIdflow through the four-gate access chain. - Debug PERMISSION_DENIED errors —
decision tree for the
Forbiddenerror.