Technical Documentation

Integration guide for developers and technical administrators. Covers widget embedding, API reference, analytics, EHR integration, policy rules, experiments, and sandbox testing.

Widget Integration

Add the patient chat assistant to your website with a single script tag. The widget renders a floating chat bubble that opens an inline chat panel.

<script
  src="https://app.healthcareagent.com/widget.js"
  data-api-url="https://app.healthcareagent.com"
  data-clinic="your-clinic-id"
  data-accent="#0f766e"
  data-position="right"
  data-greeting="Hi! How can we help you today?">
</script>

Place the script tag before the closing </body> tag. The widget self-initializes and does not depend on any external frameworks. Your clinic ID and the exact embed code are available in the admin dashboard under Widget.

Data Attributes

Configure the widget via data-* attributes on the script tag. Appearance settings can also be configured in the admin dashboard, which overrides these defaults.

Server-Side Config

On load, the widget fetches GET /widget/config from your server. Server-side settings override the data-* attributes unless the attribute is explicitly set on the script tag. This lets you manage widget appearance from the admin dashboard without changing your website code.

The /widget/config endpoint also handles experiment variant assignment, returning the correct configuration for the visitor's assigned variant. It accepts an optional vid query parameter (visitor ID) for deterministic assignment.

Appearance Options

All appearance settings can be configured via the admin dashboard under Widget.

Schedule Picker Config

When the agent searches for appointment slots, the widget renders an inline schedule picker. These options control its appearance:

Card Capture Config

When the agent requests a payment card (via Stripe), the widget renders an inline card form. These options control its labels:

Responsive Behavior and Accessibility

• Mobile — On small screens, the chat panel expands to full-height with safe area support for notched devices.
• Image upload — Supports camera and file picker for JPEG/PNG images up to 4MB (used for insurance card photos).
• Markdown — Agent responses render bold, italic, lists, and tables.
• Keyboard navigation — Full focus management with visible focus rings (WCAG AA compliant).
• Session persistence — Session data is stored in the browser so conversations survive page navigation within the same tab. A persistent visitor ID is stored in the browser for experiment assignment.
• Typing indicator — Animated dots displayed while waiting for the agent response.

Chat API — Authentication

The Chat API supports two authentication methods:

1. Widget (automatic)

The embeddable widget authenticates automatically. No API key is needed in your embed code — just register your domains in the admin dashboard under Settings → Allowed Domains.

2. API key (server-to-server)

For direct API integrations from your backend, pass your API key via the X-API-Key header:

Your API key is available in the admin dashboard. Only use it in server-side code — never expose it in client-side JavaScript or HTML.

POST /v1/chat

Send a message to the agent and receive a response.

Request

curl -X POST https://agent.yourclinic.com/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "message": "Do you accept Blue Cross Blue Shield?",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Request body

Response — 200 OK

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "response": "Yes, we accept Blue Cross Blue Shield PPO and HMO plans...",

  // Present when the agent searched for appointment slots
  "slotPicker": {
    "slots": [
      { "id": "s_123", "providerId": "P1", "providerName": "Dr. Chen",
        "start": "2026-03-20T09:00:00", "duration": 30 }
    ],
    "queryContext": { ... }
  },

  // Present when the agent requested a payment card
  "cardCapture": {
    "type": "setup_intent",
    "clientSecret": "seti_...",
    "publishableKey": "pk_...",
    "reason": "self_pay_card_on_file"
  }
}

The slotPicker and cardCapture fields are only present when the agent performs the corresponding action during the conversation turn. The widget handles these automatically; if you are building a custom integration, you will need to render a slot picker or Stripe card form accordingly.

POST /v1/chat/stream

Streaming variant using Server-Sent Events (SSE). Same request body as POST /v1/chat.

curl -N -X POST https://agent.yourclinic.com/v1/chat/stream \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"message": "What are your hours?"}'

SSE events

GET /v1/chat/:sessionId

Returns the conversation transcript as an array of { role, content } objects. Image messages include hasImage: true.

curl https://agent.yourclinic.com/v1/chat/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: YOUR_API_KEY"

DELETE /v1/chat/:sessionId

Ends the conversation, persists the session for admin review, and clears any patient verification state.

curl -X DELETE https://agent.yourclinic.com/v1/chat/550e8400-... \
  -H "X-API-Key: YOUR_API_KEY"

POST /v1/chat/confirm-card

Called after a Stripe card form is completed to confirm the capture on the server side.

POST /v1/chat/fetch-slots

Used to load more appointment slots when the patient navigates to a different week in the schedule picker.

Session Management

Sessions expire after a period of inactivity. Each message or PHI access refreshes the timer. Key behaviors:

• Session IDs are auto-generated if not provided in the first POST /v1/chat call.
• Omit sessionId to start a new conversation; include it to continue an existing one.
• Expired sessions are persisted and available for review in the admin dashboard.
• Patient verification state is tied to the session and cleared when it ends.
• Sessions include security protections against hijacking and replay.

Forms API — POST /v1/forms/start

Start a conversational form session. The form engine drives the AI to collect data field-by-field in natural language, with branching logic, validation, and dynamic data sources.

curl -X POST https://agent.yourclinic.com/v1/forms/start \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"schemaId": "patient-intake"}'

You can either reference a pre-registered schema by schemaId, or provide an inline schema object. The response includes sessionId, formId, formName, and an initial greeting response.

POST /v1/forms/message

curl -X POST https://agent.yourclinic.com/v1/forms/message \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"sessionId": "abc-123...", "message": "John Smith"}'

Returns response (next question), completed flag, and result (action outcomes) when the form is done. Rate limited per session.

GET /v1/forms/:sessionId

Returns formId, completed, fieldsCollected (field IDs only, not values), and progress (filled/total/percent). Form values are never exposed via this endpoint to protect patient data.

GET /v1/forms/schemas

Returns an array of registered schemas with id, name, and description.

Form Schema Format

Forms use a declarative JSON schema with steps, fields, conditions, data sources, and submit actions.

{
  "id": "patient-intake",
  "name": "New Patient Intake",
  "steps": [
    {
      "id": "demographics",
      "title": "Personal Information",
      "fields": [
        { "id": "first_name", "type": "text", "label": "First name", "required": true },
        { "id": "email", "type": "email", "label": "Email", "required": true,
          "validations": [{ "rule": "email" }] }
      ]
    },
    {
      "id": "insurance",
      "title": "Insurance Details",
      "condition": { "field": "has_insurance", "equals": true },
      "fields": [ ... ]
    }
  ],
  "onSubmit": [
    { "type": "register_patient", "params": { "firstName": "{{ first_name }}" } }
  ]
}

Top-level fields

Step properties

Each step has: id, title, description, fields[], condition (skip step if not met), dataSources[] (fetch dynamic data at step entry), goto (static next step), branches[] (conditional next step).

Conditions

// Simple equality
{ "field": "has_insurance", "equals": true }

// Compound (AND)
{ "and": [
  { "field": "age", "gt": 18 },
  { "field": "reason", "equals": "physical" }
] }

// Set membership
{ "field": "insurance.payer", "in": ["BCBS", "Aetna"] }

Supported condition operators: equals, not_equals, in, not_in, exists, gt, lt, gte, lte, contains, and, or, not.

Data sources

Steps can declare dataSources that fetch dynamic data at step entry. Results populate field options or are available in templates.

Submit actions

Each action supports a condition (only run if met) and params with {{ template }} references to collected values.

Field Types

Validation Rules

Each validation can include a custom message string. If omitted, a sensible default is used (e.g., "Invalid email address").

Analytics Events

The agent emits 13 structured analytics events at key points in the conversation lifecycle. Events can be routed to multiple destinations. Configure analytics in the admin dashboard under Analytics.

Event Catalog

* Fields marked with * are disabled by default. See PHI Warnings below.

Setting Up GTM dataLayer

Enable the GTM destination in your analytics config. The widget pushes events to window.dataLayer automatically — no additional JavaScript required.

{
  "enabled": true,
  "destinations": {
    "gtmDataLayer": { "enabled": true }
  }
}

Events appear in GTM as custom events with the event name matching the names listed above (e.g., chat_opened, booking_confirmed). All payload fields are included as event parameters.

Setting Up postMessage

For iframe embeds or cross-origin setups, the widget can post events to the parent window via window.parent.postMessage().

{
  "destinations": {
    "postMessage": { "enabled": true, "targetOrigin": "https://www.yourclinic.com" }
  }
}

Listen for events in your parent page:

window.addEventListener('message', (event) => {
  if (event.data && event.data.type === 'hca_event') {
    console.log(event.data.event, event.data.payload);
  }
});

Set targetOrigin to your domain for security. Use "*" only during development.

Setting Up Webhooks

The server can POST analytics events to a webhook URL. Events are sent as JSON with an HMAC signature for verification.

{
  "destinations": {
    "webhook": {
      "enabled": true,
      "url": "https://hooks.yourclinic.com/analytics",
      "secret": "YOUR_WEBHOOK_SECRET"
    }
  }
}

See HMAC Verification for how to verify the signature.

Per-Event Field Toggles

Each event has individually toggleable fields. This lets you control exactly which data points are sent to each destination.

{
  "events": {
    "booking_confirmed": {
      "enabled": true,
      "fields": {
        "timestamp": true,
        "sessionId": true,
        "appointmentId": true,
        "patientId": false    // PHI — disabled by default
      }
    }
  }
}

Set an event's enabled to false to stop emitting it entirely. Set individual fields to false to exclude them from the payload.

PHI Field Warnings

Experiment Context in Events

When an experiment is running, all events for sessions in the experiment include two additional fields:

• experimentId — The experiment's unique identifier
• variantId — The variant assigned to this visitor

In sandbox mode, events also include sandbox: true. This enables per-variant analytics without post-hoc data joins.

EHR Integration — Supported Systems

Getting API Credentials

Healthie

1. Log in to your Healthie admin account.
2. Navigate to Settings → API Keys.
3. Generate a new API key. Copy the key value.
4. Note your practice ID (visible in the URL or settings).

athenahealth

1. Register at the athenahealth Developer Portal.
2. Create a new application to get a Client ID and Client Secret.
3. Note your Practice ID from your athenahealth account.
4. The token URL and base URL default to athenahealth's production endpoints unless overridden.

Connecting via the Dashboard

Go to Integrations in the admin dashboard, select your EHR system, and enter your credentials. Use the Test Connection button to verify before saving.

Credentials are stored encrypted at rest using AES-256-GCM. Separate credentials can be configured for production and sandbox environments.

What Data Syncs Automatically

After connecting your EHR, use the Sync from EHR button to pull:

• Providers — Name, credentials, specialty, languages, schedule, accepted insurance panels
• Appointment types — Name, duration, patient type (new/established), contact types, pricing
• Insurance — Accepted payers with plan types
• Services — Service catalog with telehealth availability
• Locations — Department/office names, addresses, phone numbers
• Policies — Cancellation window, booking horizon, same-day rules

Patient Verification (OTP)

All patient-specific data access requires two-step OTP verification. This is enforced at the server level — the AI cannot bypass it.

Flow

1. Patient provides full legal name and date of birth in conversation.
2. Agent initiates verification — the system sends a verification code to the email address on file in the EHR.
3. Patient provides the code in the chat.
4. Agent verifies the code — verification state is set on the session.

Available EHR Tools

These are the capabilities available to the AI agent when your EHR is connected. The tools are automatically enabled based on your EHR integration.

Policy Engine — Hard Rules

Hard rules are deterministic checks that execute before or after a tool call. They are pure functions: a field, an operator, and a value. They run with zero latency, zero cost, and 100% determinism — no AI is involved.

Create and manage rules in the admin dashboard under Policy → Hard Rules.

Rule structure

Pre-check rules run before the tool executes. If a pre-check rule triggers with action: "block", the tool call is prevented entirely. Post-check rules run after the tool returns and can inspect the result.

All 13 Operators

Actions: Block vs Warn

Workflows

Workflows enforce tool ordering without coding state machines. The engine tracks which tools have been called in each session and blocks actions whose prerequisites have not been met.

Workflow structure

Example Rules

48-hour cancellation window

{
  "name": "48-hour cancellation window",
  "tool": "Cancel Appointment",
  "category": "scheduling",
  "severity": "high",
  "check": {
    "phase": "pre",
    "field": "input.appointmentDate",
    "operator": "time_within_hours",
    "value": 48
  },
  "action": "block",
  "message": "Our policy requires 48 hours notice for cancellations."
}

90-day booking horizon

{
  "name": "90-day booking horizon",
  "tool": "Book Appointment",
  "category": "scheduling",
  "severity": "medium",
  "check": {
    "phase": "pre",
    "field": "input.appointmentDate",
    "operator": "time_beyond_days",
    "value": 90
  },
  "action": "block",
  "message": "Appointments can only be booked up to 90 days in advance."
}

Insurance check before booking (workflow)

{
  "name": "Insurance check before booking",
  "trigger": "Book Appointment",
  "requires": ["Check Eligibility"],
  "then": ["Request Card"],
  "onFailure": "escalate_to_staff",
  "message": "Insurance eligibility must be verified before booking."
}

Experiments

Experiments let you A/B test different agent configurations against live traffic and measure the impact on conversation outcomes like booking rate, escalation rate, and session duration.

Lifecycle

1. Draft — Configure variants and traffic split. No traffic is routed yet.
2. Running — Traffic is split between variants. Sessions are tagged with experiment context.
3. Ended — Traffic routing stops. Results are frozen for analysis.

Creating an experiment

Create via the admin dashboard under Experiments.

{
  "name": "Professional vs friendly tone",
  "variants": [
    {
      "name": "control",
      "trafficPercent": 50,
      "isControl": true,
      "config": {}
    },
    {
      "name": "friendly-tone",
      "trafficPercent": 50,
      "config": {
        "persona": { "tone": "friendly", "useEmojis": true }
      }
    }
  ]
}

Traffic Splitting

Traffic is split using a deterministic hash of the visitor ID, so the same visitor always sees the same variant. Each variant has a trafficPercent field. The percentages across all variants must total exactly 100% before the experiment can be started. You need at least 2 variants.

The visitor ID is stored in the browser and persists across sessions and page loads.

What Can Be Varied

Each variant's config object can override any combination of:

• Persona — tone, answer length, emoji usage, custom instructions
• Widget — accent color, greeting, layout, labels
• Guidance — additional or replacement guidance rules
• Hard rules — modified policy rules for the variant
• Workflows — different tool ordering requirements
• Snippets and knowledge docs — different reference material

The control variant should use "isControl": true and an empty config ({}) to capture your current production settings.

Reading Results

While running, each session is tagged with experimentId and variantId. These tags appear in:

• Analytics events (all destinations)
• Session metadata in the admin dashboard
• The admin analytics dashboard, which shows an experiment overlay comparing variants on:

• Booking rate and conversion funnel per variant
• Escalation rate and supervisor block rate
• Average conversation length and duration
• Outcome distribution (booked, resolved, escalated, dropped)

Promoting a Winner

After ending an experiment, promote the winning variant to apply its config to production. Use the Promote button in the admin dashboard.

Promoting applies the variant's persona, widget, guidance, snippets, knowledge docs, and (if present) policy rules and workflows to your main configuration. The experiment must be in ended status first.

Sandbox and Testing

Sandbox mode lets you test the full integration end-to-end using real EHR sandbox environments and Stripe test keys, without affecting production data or analytics.

Toggle sandbox on/off in the admin dashboard under Settings. The widget displays a "SANDBOX" badge in the header when active.

Sandbox EHR Credentials

Configure sandbox EHR keys separately from production in Integrations → Sandbox tab. In sandbox mode, the agent connects to your EHR's test/staging environment. If no sandbox EHR credentials are configured, it falls back to a mock adapter with realistic sample data.

Sandbox Stripe Keys

Set Stripe test keys (sk_test_* and pk_test_*) via Integrations → Sandbox. No real charges are processed. Use Stripe's test card numbers (e.g., 4242 4242 4242 4242) to test card capture flows.

Sandbox Analytics Destinations

Sandbox mode uses separate analytics destination config so test events do not pollute your production analytics. Configure sandbox-specific GTM, postMessage, and webhook destinations in the admin dashboard under Analytics → Sandbox.

Sandbox sessions are tagged with sandbox: true and excluded from production dashboard metrics.

Test Chat in the Dashboard

The admin dashboard includes a built-in test chat interface. Use it to test the agent's behavior with your current configuration without needing to embed the widget on a live page. Policy rules, workflows, guidance, and the supervisor all run normally in test chat.

Webhooks

Configure a webhook URL to receive analytics events as server-side HTTP POST requests. This is useful for feeding data into your own analytics pipeline, CRM, or data warehouse.

Set up via the admin dashboard under Analytics → Destinations → Webhook.

{
  "destinations": {
    "webhook": {
      "enabled": true,
      "url": "https://hooks.yourclinic.com/analytics",
      "secret": "YOUR_WEBHOOK_SECRET"
    }
  }
}

HMAC Signature Verification

Every webhook request includes an X-HCA-Signature header containing an HMAC-SHA256 hex digest of the request body, computed using your webhook secret. Always verify this signature to confirm the request came from Healthcare Agent.

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
const signature = req.headers['x-hca-signature'];
const rawBody = req.body; // raw string, not parsed JSON
if (!verifyWebhook(rawBody, signature, 'YOUR_WEBHOOK_SECRET')) {
  return res.status(401).send('Invalid signature');
}

Event Payload Format

Each webhook request sends a JSON body with this structure:

{
  "event": "booking_confirmed",
  "timestamp": "2026-03-14T09:41:52.771Z",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "appointmentId": "apt_12345",
  // ... additional fields per event type
  "experimentId": "exp_abc",    // present if experiment is running
  "variantId": "var_def"        // present if experiment is running
}

Retry Behavior

If your webhook endpoint returns a non-2xx status code or times out, the event is logged but not retried. Ensure your endpoint is highly available. All events are always recorded in the audit log regardless of webhook delivery status.

Error Reference

All error responses use a consistent JSON format with structured error codes. Match on the code field for programmatic error handling.

Error Response Format

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid request body",
  "details": [
    { "path": "message", "message": "String must contain at most 10000 character(s)" }
  ]
}

The details array is present only for VALIDATION_ERROR responses and contains one entry per invalid field, each with a path (dot-notation field name) and a human-readable message.

Every response includes an X-Request-ID header. Include this value in any support requests to help trace the issue.