# Video-call notifications and email

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

Appointments, access grants, socket notifications, and emails are separate operations. Call the operation that matches the event in your application; creating or updating an appointment does not trigger any of them automatically.

## Start the call and notify participants [#start-the-call-and-notify-participants]

When a Practitioner starts the call, call the active-call route. It upserts an active FHIR `CommunicationRequest` with the caller as sender and all appointment participants as recipients. Patients use this grant to request their [signed-in join access](/video-calls/join-access#create-signed-in-user-access).

The route also queues a real-time event for each participant who is not already in the LiveKit room. It returns after queuing the job, not after the event is delivered.

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/video-call/livekit/notification/active-call/2d5d6f7e-1184-4b4f-a4fc-12b50792ed0d' \
  --header "Authorization: Bearer ${PRACTITIONER_TOKEN}"
```

| Event | Value |
| --- | --- |
| Socket event name | `/video-call/livekit/notification/active-call` |
| `senderProfileName` | Display name of the caller, when available. |
| `appointmentId` | FHIR `Appointment` id. |
| `description` | Appointment description, or an empty string. |
| `start`, `end` | Appointment date-times. |

The response is an `OperationOutcome` with informational severity and diagnostics stating that participant notifications were sent. This indicates the work was queued; it does not confirm that every participant received the event.

The caller must be a Practitioner, project admin, super admin, or hold the **System Owner** access policy.

## Send an invitation [#send-an-invitation]

This sends invitation email for the appointment recipients you provide. It does not create or update the appointment.

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/video-call/livekit/mail/invite' \
  --header "Authorization: Bearer ${PRACTITIONER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "appointmentId": "2d5d6f7e-1184-4b4f-a4fc-12b50792ed0d",
    "emailRecipients": [
      {
        "email": "patient@example.org",
        "profileRef": "Patient/9e7c782a-f6d3-4faf-b3ac-480280efab77"
      }
    ]
  }'
```

| Body field | Required | Description |
| --- | --- | --- |
| `appointmentId` | Yes | Id of an existing video-call appointment. |
| `emailRecipients` | Yes | One to 20 recipients. Duplicate email addresses are removed. |
| `emailRecipients[].email` | Yes | Valid recipient email. |
| `emailRecipients[].profileRef` | Yes | `Practitioner/<id>` or `Patient/<id>`; used to look up the recipient's TAN. |

Invitation and update emails include a TAN and its expiry. A recipient without an active TAN is not emailed and has `isEmailSent: false`. Ovok never sends this email to the caller, even if the caller appears in the recipient list.

## Send an update [#send-an-update]

Call this after updating an appointment when participants should receive the revised details. The route only sends email; it does not change the appointment.

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/video-call/livekit/mail/update' \
  --header "Authorization: Bearer ${PRACTITIONER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "appointmentId": "2d5d6f7e-1184-4b4f-a4fc-12b50792ed0d",
    "emailRecipients": [
      {
        "email": "patient@example.org",
        "profileRef": "Patient/9e7c782a-f6d3-4faf-b3ac-480280efab77"
      }
    ]
  }'
```

The update message also needs a TAN for each recipient. Updating the appointment refreshes TAN records; send the update message separately.

## Send a cancellation email [#send-a-cancellation-email]

There is no cancellation operation in this controller. This route sends a cancellation message only; it does not change the FHIR `Appointment` status or revoke already-issued join tokens.

```bash
curl --request POST \
  --url 'https://api.sandbox.ovok.com/v1/video-call/livekit/mail/cancel' \
  --header "Authorization: Bearer ${PRACTITIONER_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "appointmentId": "2d5d6f7e-1184-4b4f-a4fc-12b50792ed0d",
    "emailRecipients": [
      {
        "email": "patient@example.org",
        "profileRef": "Patient/9e7c782a-f6d3-4faf-b3ac-480280efab77"
      }
    ]
  }'
```

Unlike invitation and update messages, cancellation email does not require a TAN.

## Email response [#email-response]

Each mail route returns an `appointmentId` and an `emailRecipientsResult` array.

| Response field | Meaning |
| --- | --- |
| `appointmentId` | Appointment id supplied in the request. |
| `emailRecipientsResult[]` | One result per distinct recipient, excluding the caller. |
| `emailRecipientsResult[].email` | Address Ovok attempted to email. |
| `emailRecipientsResult[].profileRef` | Recipient Patient or Practitioner reference. |
| `emailRecipientsResult[].isEmailSent` | Whether Ovok reports the email as sent. Check this for every recipient; a send failure does not fail the whole request. |

If the caller is the only distinct recipient, `emailRecipientsResult` is empty. The endpoint does not report each failure as an HTTP error; inspect `isEmailSent` in the response.

## Email setup and content [#email-setup-and-content]

Map these message names to ready email templates in the project:

| Message | Template name | TAN included |
| --- | --- | --- |
| Invitation | `VIDEO_CALL_APPOINTMENT_INVITE` | Yes |
| Update | `VIDEO_CALL_APPOINTMENT_UPDATE` | Yes |
| Cancellation | `VIDEO_CALL_APPOINTMENT_CANCEL` | No |

See the [video-call template parameters](/email-templates/template-catalogue) and [email setup guide](/email-templates/set-up-email). Video-call messages include the appointment title, Practitioner name when available, start/end, and dashboard link. The request's `Origin` and language context are used when constructing the message.

All three routes require a bearer token and the same Practitioner, project admin, super admin, or **System Owner** authorization as appointment creation. They return a per-recipient result; an email delivery failure can appear as `isEmailSent: false` while the request itself succeeds.
