Skip to main content

White-Labeled Audio Recorder — Integration Guide

This guide explains how to launch Upheal’s white-labeled Audio Recorder from your EHR and how to handle follow-ups after upload. It’s intentionally concise; deep feature descriptions live in our developer and support docs linked below.

Overview​

With the Audio Recorder, providers start an in-person/virtual in-room recording directly from your EHR via a secure, single-use token (OTP). Recordings are stored locally in the browser until the provider uploads them. After upload, standard Upheal processing and webhooks apply.

Available routes in the white-labeled app:

  • Recorder: /recorder
  • Un-uploaded sessions: /unuploaded-sessions

Your assigned white-label domain will look like:

https://<your-partner-domain>/

If you prefer a custom domain (CNAME), contact your Upheal representative for setup.

Prerequisites​

  1. Integration API access & credentials (Authorization key).
  2. Configured white-label deployment (domain + branding).
  3. Webhook endpoint(s) set on your side for post-processing notifications.

Step 1 — Authenticate via Integration API (OTP)​

Obtain a one-time token that authenticates the provider in the white-labeled app.

Request (example):

curl -X POST "https://api.upheal.io/authentication/initiate-auth" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "<PROVIDER_ID>"
  }'

Response (example):

{
  "otpToken": "<OTP_TOKEN>"
}

Use the token promptly and do not log it in plain text.

Step 2 — Launch the Recorder​

Open a new browser tab/window to your Audio Recorder domain with the URL below. Build this URL server-side after you obtain the otpToken.

URL format:

https://<your-partner-domain>/recorder
  ?variant=<VARIANT>
  &contractId=<CLIENT_ID>
  &sessionToken=<OTP_TOKEN>
  &redirectUrl=<REDIRECT_URL>  (optional)

Query parameters

NameRequiredDescription
variantYesin-person for the in-room Audio Recorder flow or virtual for capturing external online session.
contractIdYesThe client's (patient's) Upheal User ID.
sessionTokenYesThe OTP token returned by initiate-auth.
redirectUrlNoA fully formed URL. If present, a redirect button will be available after successful upload.

Notes

  • The Recorder runs fully in the provider’s browser and keeps recorded data locally until upload.
  • If the browser/tab closes before upload completes, the session will appear in Un-uploaded sessions for recovery.

For more about capturing in-person sessions, see our support article.

Variant: virtual​

Use this when the provider is holding a virtual session in another calling tool (e.g., EHR video module, Zoom, Google Meet, Teams) and wants Upheal notes without switching platforms.

URL format (virtual capture):

https://<your-partner-domain>/recorder
  ?variant=virtual
  &contractId=<USER_ID>
  &sessionToken=<OTP_TOKEN>

Behavior & requirements (summary):

  • Two capture modes are available in the app: Headphones / Shared audio (recommended) and No headphones (Simple); the app guides the provider based on their setup.
  • Headphones / Shared audio requires a Chromium-based browser (e.g., Chrome, Edge; browsers like Firefox and Safari are not supported).
  • Capturing audio from desktop apps (e.g., Zoom, Teams outside the browser) is available on Windows; macOS restricts system-audio capture at the OS level.
  • Only audio is captured; no video is accessed or stored.

For end-user guidance and troubleshooting of virtual capture, see our support article.

Step 3 — Recover / Complete Uploads (Un-uploaded Sessions)​

If a recording or upload was interrupted, direct the provider to:

https://<your-partner-domain>/unuploaded-sessions?sessionToken=<OTP_TOKEN>

Behavior

  • Lists only sessions recorded on the same device & browser by the authenticated provider.
  • Allows resuming an interrupted recording flow or finishing the upload.

Processing & Webhooks​

After a session is successfully uploaded:

  • Upheal begins processing.
  • Standard webhooks notify you when processing starts and finishes. See: Using webhooks (headers, retries, signature verification, and SLAs).

For details on processing and webhooks, see your Upheal Webhook docs page.

Error Handling & Troubleshooting​

  • Invalid/expired token → Re-run initiate-auth to obtain a fresh otpToken.
  • Missing/invalid URL parameters → The app will not start; ensure you provide variant, contractId, and sessionToken.
  • Nothing listed in Un-uploaded sessions → Confirm the same browser and device are used, and the provider is authenticated with a valid token.
  • Upload stalls → Instruct provider to keep the tab active, ensure stable network, and avoid closing the browser until the “Uploaded” confirmation appears.

Security Considerations​

  • Always launch the Audio Recorder with a server-generated OTP obtained via your backend (never expose API keys in the browser).
  • Use HTTPS and do not log tokens or PHI in plain text.
  • Scope provider access appropriately in your EHR before calling initiate-auth.
  • Initiate Auth (OTP): API
  • Users API (get user by id): API
  • Capturing in-person sessions (support): Article
  • Capturing virtual sessions (support): Article
  • Webhooks overview: Documentation

Contact​

For domain setup, branding, or technical issues, reach out to your Upheal integration representative or support channel.