# Video calls

Canonical page: https://docs.ovok.com/video-calls

Ovok's video-call API connects an FHIR `Appointment` to a LiveKit room. Your application creates the appointment, tells participants when the call is ready, and requests a join token for each person who enters the room.

The API separates those steps. Creating an appointment does not send email or grant Patient access. Starting a call creates the access grant and queues a real-time notification. Join-access endpoints then issue the room URL and token.

```mermaid
flowchart LR
  app[Your application] -->|Create or update| appointment[FHIR Appointment]
  app -->|Start call| access[CommunicationRequest access grant]
  access --> event[Queued participant notification]
  app -->|Request join access| token[LiveKit URL and token]
  token --> room[LiveKit room]
  app -->|Invite or update email| email[Participant email]
```

## Typical workflow [#typical-workflow]

1. Create an appointment with at least one Practitioner participant. Ovok resolves each participant by email within the project; an address without a Practitioner account is looked up as a Patient and a Patient account is created when needed.
2. Send invitation emails with the mail API if your workflow uses email. The appointment endpoint does not send them automatically.
3. When the Practitioner starts the call, send the active-call notification. This creates or replaces the appointment's access `CommunicationRequest` and queues an event for participants who are not already in the room.
4. Request join access for each signed-in participant, or have a Practitioner request guest access for someone without an Ovok account.
5. If appointment details change, update the appointment and send an update email separately. The cancellation mail endpoint sends a cancellation message; it does not cancel the FHIR `Appointment`.

## Routes [#routes]

All routes require a bearer token. The caller's project comes from that token.

| Operation | Method | Path | Details |
| --- | --- | --- | --- |
| Create appointment | `POST` | `/v1/video-call/livekit/appointment` | [Appointments](/video-calls/appointments#create-an-appointment) |
| Update appointment | `PUT` | `/v1/video-call/livekit/appointment/:appointmentId` | [Appointments](/video-calls/appointments#update-an-appointment) |
| List my appointments | `GET` | `/v1/video-call/livekit/appointment` | [Appointments](/video-calls/appointments#list-my-appointments) |
| Create guest access | `POST` | `/v1/video-call/livekit/guest-access/:appointmentId` | [Join access](/video-calls/join-access#create-guest-access) |
| Create signed-in user access | `POST` | `/v1/video-call/livekit/user-access/:appointmentId` | [Join access](/video-calls/join-access#create-signed-in-user-access) |
| Read my access grant | `GET` | `/v1/video-call/livekit/access-permission/:appointmentId` | [Join access](/video-calls/join-access#read-the-access-grant) |
| Notify participants that the call is active | `POST` | `/v1/video-call/livekit/notification/active-call/:appointmentId` | [Notifications and email](/video-calls/notifications-and-email#start-the-call-and-notify-participants) |
| Send invitation email | `POST` | `/v1/video-call/livekit/mail/invite` | [Notifications and email](/video-calls/notifications-and-email#send-an-invitation) |
| Send appointment update email | `POST` | `/v1/video-call/livekit/mail/update` | [Notifications and email](/video-calls/notifications-and-email#send-an-update) |
| Send cancellation email | `POST` | `/v1/video-call/livekit/mail/cancel` | [Notifications and email](/video-calls/notifications-and-email#send-a-cancellation-email) |

**Path note:** these routes answer under `/v1`, the documented path. The bare `/video-call/livekit/...` paths keep working for existing clients.

## Authorization at a glance [#authorization-at-a-glance]

| Route group | Who can call it |
| --- | --- |
| Create, update, active-call notification, and mail | Practitioner, project admin, super admin, or a user with the **System Owner** access policy. |
| List appointments | Any signed-in user with a profile. Results are limited to appointments that include that user's profile. |
| Guest access | A signed-in Practitioner. This route checks the caller's profile type directly. |
| Signed-in user access | Practitioner or Patient. A Patient must have an access grant for the appointment. `RelatedPerson` is refused. |
| Read access grant | Signed-in user whose profile is one of the grant's recipients. |

## Before you integrate [#before-you-integrate]

- Your Ovok deployment must have its LiveKit service configured before it can issue join access.
- Email routes need the three video-call templates mapped and ready: [`VIDEO_CALL_APPOINTMENT_INVITE`](/email-templates/template-catalogue), [`VIDEO_CALL_APPOINTMENT_UPDATE`](/email-templates/template-catalogue), and [`VIDEO_CALL_APPOINTMENT_CANCEL`](/email-templates/template-catalogue). See [setting up email](/email-templates/set-up-email) and [mapping templates](/email-templates/map-templates).
- Appointment start and end values are UTC ISO date-times. The API rejects an end time that is not later than the start time.
- Treat `videoCallUrl`, `livekitJwt`, and the appointment passphrase as access credentials. Return them only to the intended participant.

## Pages in this section [#pages-in-this-section]

- [Appointments](/video-calls/appointments) — create, update, and list video-call appointments.
- [Join access](/video-calls/join-access) — issue room access for a guest or a signed-in Practitioner or Patient.
- [Notifications and email](/video-calls/notifications-and-email) — grant access when a call starts and message participants.
