Namespaces

ovok.chat

Chat between patients and their care team, with files and live updates over one socket.

  • Stable unknown
  • Release candidate not available
  • Development not available

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

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

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

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

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

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

Last updated on

On this page