# Chat / History

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

```http
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`

```json
{
  "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                       |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.welkinhealth.com/developer-and-integration-guide/api-reference/chat-history.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.