Chat

List your chat threads

  • Sandbox: available
  • On your own host? Choose https://{host} in the playground.
GET
/v1/chat/threads

Lists the chat threads you take part in, latest activity first, each with your unread count and its newest message.

Scope: the caller's own threads in the caller's project; chat must be on (CHAT_ENABLED).

Behaviour

  • patient keeps the threads about one patient; updatedSince keeps threads changed after an instant, for a catch-up after reconnecting.
  • limit is 1–100 (default 30). Pass nextCursor as cursor for the next page; nextCursor is null on the last.

Example

curl 'https://api.sandbox.ovok.com/v1/chat/threads?limit=20' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk'

Authorization

bearer
headerAuthorizationBearer <JWT>

Query Parameters

patient?string

Only threads about this patient.

Match^Patient\/[A-Za-z0-9\-.]{1,64}$
updatedSince?string

Only threads changed after this instant.

Formatdate-time
cursor?string

nextCursor from the previous page.

Length1 <= length <= 200
limit?integer
Range1 <= value <= 100
Default30

Response Body

Your threads, latest activity first, with your unread count in each.

application/json
  1. response
items*array<>
nextCursor*string
Example Request
curl -X GET 'https://api.sandbox.ovok.com/v1/chat/threads'
Example Response
{  "items": [    {      "id": "string",      "patient": {        "reference": "string",        "display": "string"      },      "participants": [        {          "reference": "string",          "display": "string"        }      ],      "title": "string",      "status": "open",      "lastMessage": {        "id": "string",        "threadId": "string",        "sender": {          "reference": "string",          "display": "string"        },        "text": "string",        "attachments": [          {            "id": "string",            "title": "string",            "contentType": "string"          }        ],        "sentAt": "string",        "replyTo": "string",        "clientId": "string"      },      "lastMessageAt": "string",      "unreadCount": 0,      "reads": [        {          "participant": "string",          "readAt": "string"        }      ],      "createdAt": "string"    }  ],  "nextCursor": "string"}

Execute a bot POST

Runs a Medplum Bot of your project, found by its identifier, and returns its output. Use it to call custom server-side logic without knowing the Bot's id. **Auth:** bearer token. The Bot is searched and run with your token, so you need read access to the Bot and permission to execute it. ## Behaviour - `identifier` uses FHIR token search syntax: `system|value`, `system|`, or just `value`. Exactly one Bot must match. - The JSON request body is passed to the Bot as its input, unchanged. The body is optional. - The response is whatever the Bot returns. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/bots?identifier=https://example.com|get-users' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "parameter1": "value1" }' ```

Open a chat thread POST

Opens a chat thread about one patient between you and the people you name, or answers the one they already have. A thread is a FHIR `Communication` in the patient's compartment, so whoever may see the patient may see the thread. **Scope:** the caller's project (from the token). A Patient, Practitioner or RelatedPerson session, in a project with `CHAT_ENABLED` on. ## Behaviour - `patient` is `Patient/<id>`; you must be able to read it, else **404** `CHAT_PATIENT_NOT_FOUND`. - `participants` are `Patient/<id>`, `Practitioner/<id>` or `RelatedPerson/<id>`; you are added yourself. Each one's own access policy must let them read the patient, else **403** `CHAT_PARTICIPANT_NOT_ALLOWED` naming them. - Your own access policy must let you create a `Communication` about the patient, else **403** `CHAT_WRITE_NOT_ALLOWED`. - A patient may open a thread about another patient who shares readings with them, between the two of them only (anyone else is **403** `CHAT_PARTICIPANT_NOT_ALLOWED`); the share lets them read that chat, and ovok writes it. - A new thread answers **201** with `Location: /v1/chat/threads/<id>`, and everyone in it hears `chat.thread` on the `chat` socket topic. - The same patient and people again answer **200** with the thread they have, in any order of `participants`. ## Example ```bash curl -X POST 'https://api.sandbox.ovok.com/v1/chat/threads' \ -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3NjcyNjg4MDAsImV4cCI6MTc2NzI3MjQwMH0.Ql3B_ztDvctlyZ2z0vp4sl3ExXRQGkzmxdmTAqxNzZk' \ -H 'Content-Type: application/json' \ -d '{ "patient": "Patient/123", "participants": ["Practitioner/456"], "title": null }' ```