Video-call 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

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.

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.

curl --request POST \
  --url 'https://api.sandbox.ovok.com/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

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

curl --request POST \
  --url 'https://api.sandbox.ovok.com/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

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

curl --request POST \
  --url 'https://api.sandbox.ovok.com/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

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.

curl --request POST \
  --url 'https://api.sandbox.ovok.com/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

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

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 and email setup guide. 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.