Consultation lifecycle
Understand how users, chats, messages, events, and artifacts fit together.
A consultation begins with a user record and a chat. Each patient turn is sent to the chat's streaming endpoint. The stream carries assistant content, explicit control events, safety signals, calls to action, and consultation artifact IDs.
User record
└── Chat
├── User turn
├── Assistant message stream
├── Safety and control events
└── Consultation completion
└── Long summary, short summary, and SOAP noteResource ownership
Every chat belongs to both the authenticated organization and the selected Doctronic user.
List, retrieve, message, and stream operations enforce both parts of that scope. Send the
Bearer token and X-Doctronic-User-ID on every user-scoped request.
A typical turn
- POST the user's message to
/chats/{chatId}/stream/. - Open the
text/event-streamresponse. - Create an assistant message when
message.startarrives. - Append text from each
message.contentevent with the samemessageId. - Finalize that assistant message on
message.stop. - Handle safety and control events as independent events, even if they arrive between message events.
- Close local transport state when the HTTP response ends.
- Send the next user turn to the same endpoint until an explicit completion event arrives.
message.stop completes one assistant message. It does not complete the consultation. Likewise,
the HTTP connection ending only completes the current transport stream.
Safety and control events
Your event handler must not treat every frame as display text.
| Event | Integration behavior |
|---|---|
guardian | If emitted, enter the safety behavior approved for your integration, pause conflicting routine flows, and retain the stable guardianId in your logs. |
conversation.offtopic | Record the classification and continue consuming the stream. Do not treat it as consultation completion. |
conversation.end | Mark the conversation as ended using the supplied reason. Do not infer this state from message wording. |
skill_code.cta | Present the supplied widget action and optional text, associated with its skillCode. |
error | Handle the stream error separately from HTTP failures. Respect retryAfterSeconds when present. |
ai_consultation.complete | Persist the artifact IDs and begin artifact retrieval. |
Completion and artifacts
Only ai_consultation.complete identifies consultation completion. Its artifacts object
contains longSummary, shortSummary, and soapNote IDs. Retrieve each required artifact
with GET /artifacts/{artifactId}/ using the same user scope. The completion event provides
stable IDs, but it does not mean every artifact is ready.
A successful artifact response identifies the type in data.artifactType and places Markdown
content in data.content.body. A 202 response means generation is still in progress, so wait
before requesting that artifact again. A 500 response means generation failed permanently.