Chat / History

Send and retrieve in-app chat messages between patients and care teams.

The Chat API enables sending and retrieving in-app messages exchanged between patients and care team members through the Welkin patient portal.

Base path: /{tenantName}/{instanceName}/patients/{patientId}/chat

---

Endpoints

POST Send Message (Patient → Care Team)

POST /{tenantName}/{instanceName}/patients/{patientId}/chat/messages

Sends a chat message from the patient to the care team.

Request Body

Field	Type	Required	Description
body	string	Yes	Message text content
attachmentId	string	No	UUID of a pre-uploaded file attachment

Example Request

POST /acme-health/live/patients/a1b2c3d4/chat/messages
Authorization: Bearer <token>
Content-Type: application/json

{
  "body": "I have a question about my medication dosage."
}

Example Response 201 Created

{
  "id": "msg-uuid",
  "patientId": "a1b2c3d4",
  "sender": "PATIENT",
  "body": "I have a question about my medication dosage.",
  "sentAt": "2026-03-19T10:05:00Z",
  "readAt": null
}

---

GET Get Messages

GET /{tenantName}/{instanceName}/patients/{patientId}/chat/messages

Returns the full chat message history for a patient.

Query Parameters

Parameter	Type	Default	Description
page	integer	0	Page number
size	integer	50	Results per page
since	string	—	Return messages after this ISO 8601 timestamp

---

GET Get Messages by Token

GET /{tenantName}/{instanceName}/chat/messages?token={chatToken}

Returns chat messages using a secure patient chat token (used for portal integrations).

Query Parameters

Parameter	Type	Required	Description
token	string	Yes	Secure patient chat session token

---

GET Get File by File ID

GET /{tenantName}/{instanceName}/chat/files/{fileId}

Downloads a file attachment sent within a chat conversation.

---

Chat Search

POST /{tenantName}/{instanceName}/chat/search

Full-text search across chat message history.

Request Body

Field	Type	Description
query	string	Text to search for
patientId	string	Optionally scope to a specific patient
page	integer	Page number
size	integer	Results per page