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.
updatedSincekeeps only threads changed since an ISO date-time. retrieve(threadId)reads one thread and throwsOvokNotFoundErrorwhen 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);listpages newest first; walking further pages goes back in time.sincekeeps only messages after an ISO date-time.sendgives each message aclientId. The server stores a repeatedclientIdonce, so the client retries a failed send safely, and you can match the reply to the bubble you showed while it was sending.replyTotakes the id of the message being answered.readmarks the thread read by the signed-in person, now or atreadAt.- Pass your own
clientIdto 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);uploadtakes a PDF, PNG, JPEG or WebP of up to 10 MB and keeps it private. It throwsOvokServiceErrorwhen 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.
attachmentLinkanswers 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) andthread(a thread that is new or changed). - Every
listenof a client shares one socket to the/eventsnamespace 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,
listenfails; 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.
listenthrowsOvokPermissionErrorwhen the server refuses the subscription, orOvokConnectionErrorwhen it cannot connect.
See also
- chat API reference: every method and type.
- ovok.push for the push a closed app gets for a new message.
- Errors and retries
Last updated on