Iframe Embedding Requirements

Overview

To embed HAMI within your application using an <iframe>, you must configure specific browser permissions and ensure proper network connectivity. Incorrect configuration will prevent core features like microphone access and real-time audio from functioning.

1. Iframe Configuration

Caution

The allow attribute is required. Without allow="microphone", the browser will block microphone access inside the iframe entirely, regardless of what the user allows at the OS or browser level.

The <iframe> tag must include the specified permissions. Replace {groupName} with your configured clinic or hospital’s name (e.g., baytown).

Note

The width, height, and style values shown below are for example purposes only. Adjust them to fit your website’s layout and design requirements.

<iframe
  src="https://careflow.bostonhealth.ai/g/{groupName}"
  title="{groupName}"
  width="390"
  height="630"
  style="border:0; border-radius:12px; max-width:calc(100vw - 2rem); max-height:calc(100vh - 2rem); display:block;"
  loading="lazy"
  referrerpolicy="strict-origin-when-cross-origin"
  allow="microphone; camera; autoplay; clipboard-write; geolocation"
  allowfullscreen
></iframe>

Permission	Required	Description
microphone	Yes	Required for real-time audio input during patient intake
autoplay	Yes	Required for AI avatar audio playback
camera	Recommended	Optional, recommended for future-proofing
clipboard-write	No	Enables copy-to-clipboard functionality
geolocation	Yes	Enables location-based features

2. Embedding a Patient-Specific Intake (embedUrl)

The example above embeds your group’s general HAMI page, where the patient identifies themselves. If your group has intake embedding enabled, each Universal Ingestion API call also returns an embedUrl. Loading it opens an intake that is already bound to the patient and appointment you just sent, with no sign-in step.

<iframe
  src="{embedUrl}"
  title="HAMI patient intake"
  width="390"
  height="630"
  style="border:0; border-radius:12px; display:block;"
  referrerpolicy="strict-origin-when-cross-origin"
  allow="microphone; camera; autoplay; clipboard-write; geolocation"
  allowfullscreen
></iframe>

The same allow permissions apply. In addition:

Requirement	Details
Register your origin	Give HAMI the exact origin(s) of the page that hosts the iframe (scheme + host + port, e.g. https://portal.yourclinic.com). Embed sessions requested from any other origin are rejected.
Use each link once	The embed_code in the URL is single-use and expires after 120 minutes. Set it as the iframe src once. Don’t prefetch it, open it in a second tab, or reuse it for another patient.
Session cookie	HAMI keeps the session in a partitioned (CHIPS) HttpOnly cookie scoped to your site, so a reload inside the iframe resumes the intake. If the browser blocks this cookie, the intake still works but can’t resume after a reload.
Load eagerly	Avoid loading="lazy" so the code is exchanged as soon as the page opens, while it is still valid.

Tip

Send the patient’s preferred language in Patient.communication in your FHIR bundle. The embedded intake then opens directly in that language instead of showing the language selector.

When the patient finishes, HAMI delivers the AI-generated summary to your Intake Summary Webhook.

3. Embedding HAMI Scribe

To embed HAMI Scribe for clinicians inside your EHR, use the scribeLaunchUrl returned by the ingestion API. The clinician flow, origin requirements and postMessage events are covered in Scribe Embedding.

4. Network Connectivity

The embedded application makes outbound connections from the patient’s browser to several services. Ensure none of these are blocked by your network or firewall configuration.

Service	Protocol	Notes
REST API	HTTPS	Must be reachable from the patient’s browser
WebSocket	WSS	Must not be blocked by corporate firewalls
Real-time audio server	UDP/TCP	Requires open ports for real-time communication
Country flag CDN (flagcdn.com)	HTTPS	Used for country flag images in the phone number input

Caution

If patients are behind a strict corporate firewall or proxy, real-time audio may fail silently. Test the integration from the patient’s network environment before going live.

Support

For additional support or questions about iframe embedding:

• Email: support@bostonhealth.ai
• Website: bostonhealth.ai