Video-call notifications and email

Grant participant access, queue active-call notifications, and send video-call emails.

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/v1/video-call/livekit/notification/active-call/2d5d6f7e-1184-4b4f-a4fc-12b50792ed0d' \
  --header "Authorization: Bearer ${PRACTITIONER_TOKEN}"
EventValue
Socket event name/video-call/livekit/notification/active-call
senderProfileNameDisplay name of the caller, when available.
appointmentIdFHIR Appointment id.
descriptionAppointment description, or an empty string.
start, endAppointment 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/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 fieldRequiredDescription
appointmentIdYesId of an existing video-call appointment.
emailRecipientsYesOne to 20 recipients. Duplicate email addresses are removed.
emailRecipients[].emailYesValid recipient email.
emailRecipients[].profileRefYesPractitioner/<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/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

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/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

Each mail route returns an appointmentId and an emailRecipientsResult array.

Response fieldMeaning
appointmentIdAppointment id supplied in the request.
emailRecipientsResult[]One result per distinct recipient, excluding the caller.
emailRecipientsResult[].emailAddress Ovok attempted to email.
emailRecipientsResult[].profileRefRecipient Patient or Practitioner reference.
emailRecipientsResult[].isEmailSentWhether 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:

MessageTemplate nameTAN included
InvitationVIDEO_CALL_APPOINTMENT_INVITEYes
UpdateVIDEO_CALL_APPOINTMENT_UPDATEYes
CancellationVIDEO_CALL_APPOINTMENT_CANCELNo

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.

Last updated on

On this page