Help Center

Everything you need to set up, customize, and manage your AI patient assistant. Written for clinic administrators — no technical background required.

Accepting Your Invitation

When your clinic is set up on Healthcare Agent, you will receive an email invitation with a link to create your account. Here is what to do:

1. Open the invitation email and click the link.
2. Enter your name and choose a password (at least 8 characters).
3. Click Create Account to sign in for the first time.

The Setup Wizard

The first time you log in, a guided setup wizard walks you through the essential steps. You can always change these settings later from the dashboard.

The wizard has six steps:

Your Dashboard Overview

After setup, you land on the Dashboard. This is your home base. Here is what you will see:

• Launch Checklist — A progress tracker showing which setup steps are complete. It disappears once you go live.
• Key metrics — At a glance: total conversations, bookings, escalations, and more for your selected date range.
• Trend chart — Conversation volume over time.
• Funnel chart — How many conversations result in a booking, escalation, or drop-off.
• Outcome and heatmap charts — Patterns in when patients are chatting and what happens in each conversation.

Use the date pickers at the top right to change the reporting period, and click Refresh to update the data.

The left sidebar gives you quick access to all sections: active conversations, configuration pages, the test area, and more.

Connecting Your EHR

Healthcare Agent works with your electronic health records system to pull patient data, provider schedules, and insurance information. Currently supported EHR systems:

• Healthie
• athenahealth

To connect your EHR:

1. Go to Integrations in the sidebar.
2. Find the EHR System section.
3. Select your EHR type from the dropdown.
4. Paste your API key (you can get this from your EHR's settings or your EHR account representative).
5. Click Test Connection to verify it works.
6. Click Save.

Syncing Data from Your EHR

Once your EHR is connected, you can pull in data automatically:

1. Go to Clinic in the sidebar.
2. Click the Sync from EHR button at the top.
3. Confirm that you want to import. This will update your providers, insurance plans, and services with the latest data from your EHR.

Editing Clinic Details

Go to Clinic in the sidebar to update your basic information. You can edit:

• Clinic name — Displayed in the chat widget and used by the AI when talking to patients.
• Phone number — The number the AI gives patients if they need to call you.
• Website — Your clinic's website URL.
• Address — Street, suite, city, state, and ZIP code.
• Office hours — Set open and close times for each day of the week, or mark a day as closed.

Click Save at the bottom when you are done. Changes take effect immediately for new conversations.

Managing Providers

The Providers section (on the Clinic page) lists the healthcare providers at your practice. The AI uses this list to help patients find the right provider and book appointments.

For each provider, you can include:

• Name and credentials (e.g., Dr. Sarah Chen, MD)
• Specialty
• Whether they are accepting new patients
• Languages spoken

To add a provider, click Add provider and fill in the details. To remove one, click the delete button next to their name.

Insurance Plans

Tell the AI which insurance plans your clinic accepts. When patients ask "Do you take Blue Cross?", the AI will check this list to give an accurate answer.

You can manage:

• Accepted plans — Add each insurance payer (e.g., Aetna, UnitedHealthcare, Cigna) and optionally specify plan types (HMO, PPO, etc.).
• Self-pay options — Describe any cash-pay or out-of-pocket options.
• Sliding scale — Toggle on if your clinic offers income-based pricing.

Services

List the services your clinic offers (e.g., "Annual Physical", "Mental Health Counseling", "Lab Work"). For each service, you can note whether telehealth is available.

The AI uses this list to answer questions like "Do you offer telehealth visits?" or "What services do you provide?"

FAQs Your Patients Ask

Add frequently asked questions and answers that are specific to your practice. For example:

• "Where do I park?" — "Free parking is available in the garage behind our building."
• "Do I need a referral?" — "Referrals are required for specialist visits if your plan is an HMO."

The AI will use your FAQs to answer patient questions accurately, in your own words.

Clinic Policies

Set the policies that your AI assistant will communicate to patients. These include:

• Cancellation policy — e.g., "Please cancel at least 24 hours before your appointment to avoid a fee."
• New patient process — What new patients need to know before their first visit.
• Telehealth policy — Requirements for virtual visits.
• Payment policy — When payment is due, accepted payment methods, etc.
• No-show policy — What happens if a patient does not show up for an appointment.

You can also set up escalation settings to control what happens when the AI needs to hand off to a human:

• Transfer phone — The number to transfer calls to.
• Transfer hours — When phone transfers are available.
• After-hours instructions — What to tell patients outside business hours.
• Emergency message — Displayed when a patient describes a medical emergency.

Choosing a Personality

Your AI assistant's personality determines how it speaks to patients. Go to Persona in the sidebar to configure it.

Agent Name

Give your assistant a name (e.g., "Patient Assistant" or "Maple Health Bot"). This name appears in the chat widget header.

Tone of Voice

Pick the tone that matches your clinic's brand:

• Friendly — Warm, approachable, uses conversational language.
• Professional — Polished and clinical, good for specialist practices.
• Neutral — Balanced, neither overly casual nor formal.
• Matter-of-fact — Direct and efficient, gets straight to the point.
• Humorous — Light-hearted, uses gentle humor where appropriate.

Emojis

Toggle Allow emojis on or off. When enabled, the AI may use emojis in its responses to feel more approachable.

Setting Answer Length

Control how much detail the AI gives in each response:

• Concise — Short, to-the-point answers. Good if your patients prefer quick responses.
• Standard — A balanced amount of detail. The default setting.
• Thorough — Longer, more detailed explanations. Useful for practices where patients often have complex questions.

Custom Instructions

The Custom Instructions text box lets you give the AI additional personality notes or behavioral guidelines that do not fit into the other settings. For example:

• "Always greet the patient by name if you know it."
• "When discussing costs, remind patients that estimates may vary based on their plan."
• "Our clinic specializes in pediatrics, so assume questions are about children unless told otherwise."

Click Save changes when you are done. Changes apply to the next new conversation.

Guidance Rules

Guidance rules are instructions that shape how your AI handles specific situations. Think of them as notes you would give a new receptionist: "If someone mentions chest pain, tell them to call 911."

Each guidance rule has:

• Category — Communication, Content & Sources, Escalation, Policy, or Other.
• Severity — Low, Medium, High, or Critical. Higher-severity rules get more weight.
• Instruction — The actual rule text, written in plain English.

To add a guidance rule:

1. Go to Guidance in the sidebar.
2. Click Add rule.
3. Choose a category and severity.
4. Write your instruction in the text box.
5. Click Add.

You can pause a rule without deleting it (click the pause button next to the rule). Paused rules are ignored until you resume them.

Hard Rules

Hard rules are stricter than guidance rules. They automatically block certain actions if conditions are not met. The AI literally cannot perform a blocked action — it is stopped before it reaches your EHR.

Example: "Do not allow appointment cancellations if the appointment is less than 48 hours away."

Each hard rule includes:

• Name — A short description (e.g., "48-hour cancellation window").
• Category — Scheduling, PHI, Billing, or General.
• Tool — Which action the rule applies to (e.g., canceling or booking an appointment).
• Condition — The specific check that must pass (e.g., "hours until appointment is greater than 48").
• Severity — How important the rule is.
• Action — What happens when the rule triggers (block the action, warn the patient, etc.).
• Message — An optional message shown to the patient when the rule triggers.

Like guidance rules, hard rules can be paused and resumed at any time.

Workflows

Workflows let you require certain steps to happen in a specific order. For example, you might want the AI to always verify a patient's insurance before booking an appointment.

Each workflow has:

• Name — A descriptive name (e.g., "Insurance check before booking").
• Trigger — The action that activates this workflow (e.g., booking an appointment).
• Requires — Steps that must be completed first (e.g., insurance verification).
• Then — Optional follow-up steps after the trigger.
• On failure — What to do if a required step fails.
• Message — What the AI tells the patient if the workflow is not followed.

Workflows can be paused and resumed, just like other rules.

Adding Knowledge Articles

The Knowledge Base is where you store information that your AI can reference when answering patient questions. Go to Knowledge in the sidebar.

Click Add document to create a new article. Each article needs:

• Title — A clear name (e.g., "Preparing for Your Colonoscopy").
• Type — Categorize it: article, FAQ, policy, or guide.
• Content — The full text. Write in plain language, as if explaining to a patient.

You can add as many articles as you need. Good candidates include:

• Procedure preparation instructions
• Post-visit care guides
• Information about conditions you treat
• Directions to your office
• Details about specific programs or specialties

Adding Snippets

Snippets are shorter, reusable pieces of content. Think of them as quick-reference cards the AI can pull from.

To add a snippet, go to Snippets in the sidebar and click Add snippet. Each snippet has:

• Title — A name for easy identification.
• Content — The reference text.
• Folder — Optional. Group related snippets together (e.g., "Insurance", "Procedures").

Snippets are great for:

• Standard responses you want worded a certain way
• Phone numbers and addresses for referral partners
• Short descriptions of programs or services

How the AI Uses Your Knowledge Base

When a patient asks a question, the AI searches your knowledge articles and snippets for relevant information. It then uses that content to craft a natural response in the tone and style you have chosen.

The AI will not make up information. If the answer is in your knowledge base, it uses it. If not, it lets the patient know and may suggest they contact your office directly.

Getting Your Embed Code

The chat widget is the floating chat bubble that appears on your website. To install it:

1. Go to Domains in the sidebar and add your website's domain (e.g., yourclinic.com). Follow the verification steps to prove you own it.
2. Go to Widget in the sidebar and copy the embed code shown at the bottom of the page.
3. Paste the code into your website, just before the closing </body> tag.

The embed code looks like this:

Your clinic ID is pre-filled in the embed code on the Widget page — just copy and paste. No API key or password is needed. The widget handles authentication automatically.

If you use a website builder (Squarespace, WordPress, Wix, etc.), look for a "Custom Code" or "Embed HTML" option in your site settings or page editor.

Customizing Colors and Appearance

On the Widget page, you can customize how the chat looks to match your brand:

• Accent color — The primary color used for the header, buttons, and chat bubble. Use your brand color here.
• User bubble color — The color of the patient's message bubbles. Defaults to your accent color.
• Header title — The text shown at the top of the chat window (e.g., "Chat with us" or "Patient Assistant").
• Greeting message — The first message patients see when they open the chat.
• Input placeholder — The hint text in the message box (e.g., "Type a message...").
• Disclaimer — A short message at the bottom of the chat (e.g., "This is an AI assistant and does not provide medical advice."). You can toggle this on or off.
• Photo upload — Toggle whether patients can send photos through the chat.

A live preview on the right side of the page updates as you change settings, so you can see exactly how the widget will look.

Click Save changes to apply. Click Revert to undo unsaved changes.

Widget Position and Size

You can also control the layout of your chat widget:

• Position — Choose whether the chat bubble appears in the bottom-right or bottom-left corner of the page.
• Bubble size — The diameter of the floating chat button (default is 56 pixels).
• Panel width — How wide the chat window is when open (default is 380 pixels).
• Border radius — How rounded the corners of the chat window are. A higher number makes them rounder.

Schedule Picker Settings

When the AI helps a patient book an appointment, it shows a calendar-style schedule picker inside the chat. You can customize:

• Days visible — How many days of availability to show at once (default is 7).
• Time format — 12-hour (2:30 PM) or 24-hour (14:30).
• Selected slot color — The color of a time slot when the patient clicks on it.
• Confirmed slot color — The color after an appointment is confirmed.
• Confirm button label — The text on the confirmation button (e.g., "Confirm appointment").
• Empty state label — What to show when no time slots are available for a given day.

Payment Form Settings

If your clinic collects card information through the chat (for copays or deposits), you can customize the payment form:

• Button color — The color of the payment form buttons.
• Success color — The color shown after a successful card save.
• Save card button label — e.g., "Save card" or "Add payment method".
• Pay button label — e.g., "Pay now" or "Submit payment".
• Success message — What the patient sees after their card is saved (e.g., "Card saved successfully!").

Using Sandbox Mode

Sandbox mode lets you test your AI assistant using your EHR's sandbox/test environment — real API calls, real workflows, but no impact on production patient data. When sandbox mode is on:

• The AI connects to your EHR's sandbox environment using separate test credentials — real API calls with test data, not mock data.
• Stripe uses test mode keys — no real charges are processed.
• Patient verification (OTP) still uses the real auth flow — emails are sent, codes are verified.
• Analytics events fire to separate sandbox destinations so test data doesn't pollute your production analytics.
• Sandbox sessions are tagged and excluded from your production dashboard metrics.
• A yellow "SANDBOX MODE" banner appears at the top of the dashboard and a "SANDBOX" badge shows in the widget.

To toggle sandbox mode, click the Sandbox switch at the bottom of the sidebar.

The Test Chat Feature

Go to Test in the sidebar to open a live chat preview. This lets you have a conversation with your AI assistant exactly as a patient would, right inside the admin dashboard.

Use this to:

• See how your persona and tone settings feel in a real conversation.
• Test whether your knowledge base answers questions correctly.
• Verify that guidance rules and hard rules work as expected.
• Try the scheduling and payment flows.

Pre-Launch Checklist

Before going live, the dashboard shows a Launch Checklist on the main dashboard page. It tracks your progress across key setup items:

Checklist Item	What It Checks
EHR connected	You have connected and tested your EHR integration.
Clinic info configured	Your clinic name and basic details are filled in.
Providers added	At least one provider is listed.
Insurance plans configured	At least one insurance plan is added.
Agent persona set	You have chosen a tone and saved your persona settings.
Widget customized	You have reviewed and saved your widget settings.

Each item links to the relevant settings page so you can complete it quickly.

Going Live

Once all checklist items are complete, the Go Live button becomes active. Clicking it makes your AI assistant available to patients on your website.

1. Finish all items in the Launch Checklist.
2. Test the chat in sandbox mode to make sure everything works.
3. Click Go Live on the dashboard.
4. Confirm in the popup that you are ready.

Dashboard Metrics Explained

The dashboard shows key performance metrics for your AI assistant. Here is what each one means:

• Total conversations — The number of chat sessions in your selected date range.
• Active — Conversations currently in progress.
• Booked — Conversations that resulted in a successful appointment booking.
• Escalated — Conversations where the AI determined a human needed to step in.
• Resolved — Conversations that ended successfully without escalation.
• Dropped — Conversations where the patient left before reaching a resolution.

You can view any conversation by clicking on it in the conversation list. Each conversation shows the full transcript, notes, an audit log, and details of any actions the AI took.

Running Experiments (A/B Testing)

Experiments let you test different configurations side by side to find out what works best. For example, you might want to test whether a "Warm & Friendly" tone leads to more bookings than a "Professional" tone.

Go to Experiment in the sidebar to get started.

Creating Variants

1. Enter a name for your experiment (e.g., "Friendly vs Professional tone").
2. The first variant is your Control — it uses your current settings. Give it a name (e.g., "Current setup") and set its traffic percentage.
3. Click + Add variant to create additional variants. Each variant gets a name and a traffic percentage.
4. Make sure your traffic percentages add up to exactly 100% (required before you can start the experiment).
5. Click Create Experiment.

After creating the experiment, you will see the draft view. Click on each variant to edit its configuration — you can change the persona, guidance rules, hard rules, snippets, knowledge articles, and widget settings independently for each variant.

When your variants are configured, click Start Experiment. Visitors will be randomly assigned to a variant based on your traffic percentages.

Reading Results

While an experiment is running, the results update automatically on the Experiment page. You will see metrics for each variant including conversation count, booking rate, and escalation rate.

Let your experiment run long enough to get meaningful results. A few days of traffic is usually a minimum; a week or more is better.

The Differences section shows you exactly what is different between each variant's configuration, making it easy to see what you are testing.

Promoting a Winner

When you are ready to end the experiment:

1. Click End Experiment.
2. Review the final results to identify the winning variant.
3. If a non-control variant won, you can promote its configuration to become your new default settings.

After ending an experiment, you can start a new one at any time.

Connecting Google Tag Manager

You can send chat events to Google Tag Manager (GTM) so they appear alongside your other website analytics. Go to Analytics in the sidebar.

1. Toggle Analytics to On.
2. Toggle GTM dataLayer to On.
3. Click Save.

Once enabled, chat events will be pushed to the dataLayer on your website. You can then set up GTM triggers and tags to forward these events to Google Analytics, your ad platforms, or any other tool.

Webhook Destinations

You can also send events to a webhook URL. This is useful if you want to record events in a CRM, trigger automations, or store them in your own analytics system.

1. Toggle Webhook to On.
2. Enter your Webhook URL (the endpoint that will receive the events).
3. Optionally enter a Secret for HMAC signature verification.
4. Click Test Webhook to send a test event and verify it works.
5. Click Save.

Available Events

You can toggle individual events on or off, and for each event, choose which data fields to include. Here are the events organized by category:

Lifecycle Events

Event	When It Fires
chat_loaded	The chat widget loads on a page.
chat_opened	A visitor opens the chat window.
chat_closed	A visitor closes the chat window.
message_sent	A visitor sends a message.
message_received	The AI sends a response.

Scheduling Events

Event	When It Fires
slots_shown	Available appointment slots are displayed to the visitor.
slot_selected	The visitor clicks on a time slot.
slot_confirmed	The visitor confirms their appointment.
date_range_changed	The visitor navigates to a different date range in the scheduler.

Payment Events

Event	When It Fires
card_saved	A visitor successfully saves their payment card.

Outcome Events

Event	When It Fires
booking_confirmed	An appointment is fully booked (EHR confirmed).
escalated	The conversation is escalated to a human.
verification_completed	A patient successfully completes identity verification.

Inviting Staff

If you are the account owner, you can invite other staff members to access the admin dashboard. Go to Users in the sidebar.

1. Click Add user.
2. Enter the staff member's name and email.
3. Set a temporary password (they can change it later).
4. Choose a role (see below).
5. Click Add.

Share the email and temporary password with the new team member so they can log in.

Roles Explained

Role	What They Can Do
Viewer	View conversations, the dashboard, and settings. Cannot make any changes.
Editor	Everything a Viewer can do, plus edit persona, guidance rules, hard rules, workflows, knowledge base, snippets, widget settings, analytics, experiments, and clinic details.
Owner	Full access. Can do everything an Editor can do, plus manage team members (invite, remove, change roles), manage API keys and integration credentials, toggle sandbox and go-live, and handle data deletion requests.

Changing Passwords

Team members can change their own password by logging out and using the password reset flow, or by asking an Owner to reset it for them.

If you need to remove a team member's access, an Owner can delete their account from the Users page.

Widget Not Showing

If the chat widget is not appearing on your website, check these common causes:

The embed code is missing or in the wrong place

Make sure the embed code snippet is pasted into your website's HTML, ideally just before the closing </body> tag. If you use a website builder, check the "Custom Code" or "Footer Code" section in your site settings.

Your domain is not registered

The widget authenticates by requesting a signed token from your server, and the server only issues tokens to registered domains. Make sure your website's domain is registered in the admin dashboard under Settings → Allowed Domains. If the domain does not match, the token request will be rejected and the widget will not load.

Your site is using a content security policy (CSP) that blocks the widget

If your website has strict security headers, you may need to add your Healthcare Agent server URL to the allowed script sources. Ask your web developer to check the CSP settings.

The agent is not live yet

The widget only appears for patients after you click "Go Live" on the dashboard. Before that, only sandbox/test mode is available.

Agent Giving Wrong Answers

If the AI is saying something incorrect, here are ways to fix it:

The information is outdated or missing from your knowledge base

The AI can only answer based on the information you have given it. Go to Knowledge or Snippets and add or update the relevant content. The AI will use the new information in the next conversation.

Clinic details are incorrect

Check your Clinic settings. Make sure your hours, phone number, address, providers, insurance plans, and services are up to date.

The AI is not following a specific policy

Add a guidance rule with clear instructions about the policy. For critical policies, consider adding a hard rule that automatically enforces it.

The tone feels wrong

Go to Persona and adjust the tone of voice, answer length, or custom instructions. Test the changes using the Test chat before going live.

EHR Sync Issues

Sync fails with an error

Go to Integrations and test your EHR connection. If the test fails, your API key may have expired or been revoked. Contact your EHR provider to get a new key.

Synced data is missing or incomplete

Some EHR systems only share certain data through their API. If providers or insurance plans are missing after a sync, you can add them manually on the Clinic page.

Sync overwrote my manual edits

Syncing from EHR replaces the providers, insurance plans, and services sections with fresh data from your EHR. If you need to make manual edits, do so after syncing. Your clinic details, FAQs, and policies are never overwritten by a sync.

Common Questions

Can I use the AI without connecting an EHR?

Yes. During setup, choose "Demo / None" for the EHR. The AI can still answer questions, provide information from your knowledge base, and help with general inquiries. It just will not be able to look up patient records or book real appointments.

How quickly do changes take effect?

Most changes (persona, guidance rules, knowledge articles, widget settings) take effect for the next new conversation. Patients who are already chatting will not see changes mid-conversation.

Can I see what the AI said to patients?

Yes. Go to the conversation list (Active, All, Escalated, etc.) in the sidebar and click on any conversation. You will see the full transcript, an audit log of actions taken, and any notes.

Is patient data secure?

Healthcare Agent is designed with patient privacy in mind. Conversations are stored securely, and you control what data fields are shared through analytics events. Sensitive fields like patient IDs are flagged so you can choose whether to include them.

Can I temporarily disable the AI without removing the widget code?

Yes. You can toggle sandbox mode on, which prevents real patient interactions while keeping the widget code on your site. When you are ready to go live again, just toggle sandbox mode off.

How do I contact support?

If you need help with something not covered in this guide, reach out to your account contact or use the support channel provided during onboarding.