# ovok.chat

Canonical page: https://docs.ovok.com/web-sdk/core/namespaces/chat

`ovok.chat` is person-to-person chat. A thread is about one patient and holds the patient and any of their care team. Messages are text, with files attached if you like. The server stores them as FHIR `Communication` resources, so whoever may read the patient may read the thread.

## Open a thread [#open-a-thread]

```ts
const thread = await ovok.chat.threads.open({
  patient: 'Patient/123',
  participants: ['Practitioner/456'],
  title: 'Blood pressure',
});
```

- The signed-in person is added to `participants`.
- Opening the same participants about the same patient again answers the existing thread.
- Every participant must be allowed to read the patient, or the call throws `OvokPermissionError`.
- When chat is turned off for the project, every call throws `OvokPermissionError`.

## List threads [#list-threads]

```ts
const page = await ovok.chat.threads.list({ patient: 'Patient/123' });

for await (const thread of ovok.chat.threads.list()) {
  showThread(thread.title, thread.unreadCount, thread.lastMessage?.text);
}
```

- Threads come newest message first. `updatedSince` keeps only threads changed since an ISO date-time.
- `retrieve(threadId)` reads one thread and throws `OvokNotFoundError` when there is none.

## Read and send messages [#read-and-send-messages]

```ts
const latest = await ovok.chat.messages.list(thread.id, { limit: 50 });

const sent = await ovok.chat.messages.send(thread.id, { text: 'See you on Monday.' });

await ovok.chat.read(thread.id);
```

- `list` pages newest first; walking further pages goes back in time. `since` keeps only messages after an ISO date-time.
- `send` gives each message a `clientId`. The server stores a repeated `clientId` once, so the client retries a failed send safely, and you can match the reply to the bubble you showed while it was sending.
- `replyTo` takes the id of the message being answered.
- `read` marks the thread read by the signed-in person, now or at `readAt`.
- Pass your own `clientId` to make a send repeatable across restarts, for example one id per post you send to many threads.

## Send files [#send-files]

```ts
const leaflet = await ovok.chat.attachments.upload({
  file: pdfBlob,
  fileName: 'Flu vaccination.pdf',
  contentType: 'application/pdf',
});

await ovok.chat.messages.send(thread.id, { text: 'Flu vaccination', attachments: [leaflet.id] });

const { url } = await ovok.chat.messages.attachmentLink(thread.id, message.id, message.attachments[0].id);
window.open(url);
```

- `upload` takes a PDF, PNG, JPEG or WebP of up to 10 MB and keeps it private. It throws `OvokServiceError` when the file store refuses the file.
- A message carries up to 5 attachments. You can send only your own uploads, but one upload can go into any number of your threads.
- Everyone who can read the message can download its files. `attachmentLink` answers a link that needs no bearer and works for an hour; ask again once it expires.
- `attachments.link(id)` answers the same kind of link for one of your own uploads.

## Listen for changes [#listen-for-changes]

```ts
import type { ChatEvent } from '@ovok/core';

const stop = await ovok.chat.listen((event: ChatEvent) => {
  if (event.type === 'message') {
    addMessage(event.message);
  }
});

await stop();
```

- Events are `message` (a new message, your own included), `read` (a read receipt) and `thread` (a thread that is new or changed).
- Every `listen` of a client shares one socket to the `/events` namespace on the API origin. It closes when the last listener stops.
- The socket uses WebSocket only, never HTTP long-polling, so the API needs no sticky sessions. Where a network blocks WebSockets, `listen` fails; read the threads over REST instead.
- Each connection spends a fresh single-use ticket from `v1/events/ticket`, so the access token never travels on the socket.
- A dropped connection reconnects with growing, jittered delays of up to 30 seconds.
- After each connect it lists the threads changed since the newest message or thread it has seen, and delivers the messages it missed, oldest first. Each message is delivered once, so a handler never polls.
- Listening ends when the user signs out.
- `listen` throws `OvokPermissionError` when the server refuses the subscription, or `OvokConnectionError` when it cannot connect.

## See also [#see-also]

- [chat API reference](../reference/core/chat.mdx): every method and type.
- [ovok.push](./push.mdx) for the push a closed app gets for a new message.
- [Errors and retries](../errors-and-retries.mdx)
