Live Chat via API

Live chats are interactions: conversations between your organization and a patient, held on a widget. The Live Chat API's documented surface today is read-only — retrieving chats, transcripts, files, and AI evaluations for reporting, archival, and analytics. Write operations (driving conversations programmatically) will be documented as they're opened up.

Base URL: https://medchatapp.com/livechatapi2.0 · Scope: read.my_orgs.chats

The chat object

GET /orgs/{orgId}/chats/{chatId} returns the chat: status (Active, Ended, Archived), widgetId, timestamps, chatEndReason, and expandable relations — memberships (each participant with a role of ExternalUser, AiAgent, or HumanAgent), attributes, forms, presentedFiles, plus AI evaluations (resolution, sentiment, analyzerOutputs).

Messages are polymorphic: each message's body is an array of typed blocks — TextMessageBlock, SystemMessageBlock, MultipleChoiceInputBlock, and ReferenceMessageBlock (which points at another object, e.g. a form, via referenceType + referenceId).

Read chats and transcripts

(Recipe: Retrieve Live Chat Transcripts.)

# Recently ended chats
curl "https://medchatapp.com/livechatapi2.0/orgs/$ORG_ID/chats?\$filter=status eq 'Ended'&\$orderby=createdDateTime desc&\$top=50" \
  -H "Authorization: Bearer $TOKEN"

# One chat with its participants and attributes
curl "https://medchatapp.com/livechatapi2.0/orgs/$ORG_ID/chats/$CHAT_ID?\$expand=Memberships,Attributes,Forms" \
  -H "Authorization: Bearer $TOKEN"

# The transcript
curl "https://medchatapp.com/livechatapi2.0/orgs/$ORG_ID/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $TOKEN"

When a transcript message carries a ReferenceMessageBlock with referenceType: "Form", resolve it against the chat's forms collection to see the form's elements and responses.

AI evaluations and analyzer outputs

Once the platform's evaluation pipeline has run, each chat exposes:

GET .../chats/{chatId}/resolution — did the conversation resolve the patient's intent
GET .../chats/{chatId}/sentiment — overall and final sentiment
GET .../chats/{chatId}/analyzerOutputs — chat-level analyzer results
Per message: .../messages/{messageId}/sentiment, .../messages/{messageId}/modelDecision, .../messages/{messageId}/analyzerOutputs

Note: $expand=AnalyzerOutputs on the chat endpoints intentionally returns chat-level outputs only — message-level outputs come from the per-message endpoints.

Files

Files exchanged during the chat are listed at GET .../chats/{chatId}/files, with metadata per file at .../files/{fileId} and content at .../files/{fileId}/download (thumbnails and PDF previews via .../thumbnail and .../preview). Files surfaced to the patient by an automation appear separately under GET .../chats/{chatId}/presentedFiles.

Context amendments

If a parent task injected context into the chat while it ran (see Voice via API for the same pattern on calls), the thread is readable at GET .../chats/{chatId}/contextAmendments — each amendment shows its originator (originatorInteractionType of Task means a task drove it) and any follow-on messages.

Where's the task?

The chat itself doesn't carry a task ID. Starting a chat on a widget configured for task creation spins up the parent task on the Automation API, which references the chat by interaction type and ID — see Tasks via API (InteractionLink).