Build a clinical conversation

Connect an authenticated user to a streamed conversation, typed events, and consultation documents.

A clinical conversation connects four API resources: a user, a chat, a stream of typed events, and the artifacts produced when the consultation completes.

User
  -> Chat
      -> Streamed turns
          -> Safety and workflow events
          -> Consultation artifacts

The /users/ resource is the Doctronic record associated with the patient identity in your system. The Bearer token scopes that record to your organization.

Build the server-side flow

Create the user with POST /users/ and save data.id in your identity mapping.
Send that ID as X-Doctronic-User-ID on every user-scoped request.
Create a chat with POST /chats/ and save the returned data.id.
Send each patient turn to POST /chats/{chatId}/stream/.
Parse the response as Server-Sent Events until the HTTP stream closes.
Act on explicit safety, workflow, and completion events.

Both credentials belong in your backend. Do not put the organization Bearer token in browser code, mobile binaries, client-visible configuration, logs, or analytics events.

Add integration context

When creating a chat, conversationPromptContext can provide context that applies to the full conversation. For a single turn, use messagePromptContext inside userEvent.

Create-chat context

{
  "timezone": "America/New_York",
  "conversationPromptContext": "The user entered from the primary-care intake flow."
}

Per-message context

{
  "userEvent": {
    "type": "user_message",
    "userInput": "I have had a sore throat and fever since yesterday.",
    "messagePromptContext": "This turn follows the integration's symptom intake form."
  },
  "timezone": "America/New_York"
}

Both context fields accept at most 50,000 characters. Treat them as clinical input, not as a place for credentials, routing instructions, or unbounded application state. Invalid timezones return 400; the default timezone is UTC.

Drive the interface from events

The stream separates assistant text from control signals.

Event	Integration behavior
`message.start`	Start a local assistant message using `messageId`.
`message.content`	Append the `content` chunk to that message.
`message.stop`	Mark the message complete.
`guardian`	If emitted, enter the integration's approved safety path.
`skill_code.cta`	Present the next-step action described by the event.
`conversation.end`	Record the explicit end state and its supplied `reason`.
`ai_consultation.complete`	Store the artifact IDs and begin retrieval.
`error`	Handle the stream error and respect `retryAfterSeconds` when present.

Artifact IDs in ai_consultation.complete are stable, but an artifact can still return 202 while generation is in progress.

Do not infer workflow state from the wording of message.content. The HTTP connection closing ends the transport for one turn, but it does not by itself mean the consultation is complete.

Keep event handling forward compatible

Ignore event names you do not recognize. Do not fail the stream when Doctronic adds a new event type.

Restore an existing conversation

Use GET /chats/ to list the user's chats and GET /chats/{chatId}/messages/ to rebuild the visible transcript. The message list contains user and assistant messages. Consultation artifacts use their own retrieval endpoint.

Build a clinical conversation

Build the server-side flow

Add integration context

Drive the interface from events

Restore an existing conversation

Next steps

On this page