Guides
Embed the patient widget
Patients use NezerCare only through a chat widget on your own website: answers about your clinic, their care, and a chat with your team. Signing them in is how they get into NezerCare.
Install the snippet
Copy the snippet from the dashboard under Integrations → Patient widget (step 2, Install the code) into the <head> of every page, above your analytics tags. The dashboard shows it once the widget is live on a verified website: until then the install step is locked. It looks like this:
<script
src="https://nezercare.com/widget.js"
async
data-organization="<organization ID>"
data-environment="<widget ID>"
></script>Anonymous visitors can ask questions as soon as it's installed on a website you have verified (below); nothing they type is stored. Signing in patients, email links and everything a signed-in patient does need your organization's signed BAA.
Building before the website is verified
The widget loads only on a website you have verified, and http://localhost is never one on NezerCare's hosted service: anyone can claim to be on localhost, so it proves nothing. You can list it under Edit websites, but there it neither shows the widget nor signs a patient in. The install code, with your organization ID and widget ID, appears in the staff app once one of your websites is verified and the widget is on it. To build, verify the domain first, then list a development or staging address on it (a subdomain of a verified domain counts) and use the same code there. Until then, try the widget in the Playground.
Websites and widget page
On the same dashboard page, set:
- Websites (step 1, Your website, then Edit websites): the exact origins that may show the widget, one per line, such as
https://clinic.example.com. Up to 10, HTTPS only (a bare origin: no path, no wildcard). Only a listed website whose domain you have verified shows the widget, and browsers refuse to show it anywhere else.http://localhostandhttp://127.0.0.1can be listed but don't count on the hosted service. - Widget page (step 3, Sign patients in, then Set page): the page where patients land from care-update emails. Until it's set, those emails still go out, without a link: they tell the patient your team will follow up directly.
Verify your website
The widget loads on a listed website only once you have verified its domain, so on an unverified site it simply doesn't appear (visitors see nothing, and nothing breaks). Your dashboard shows each website's state, one row per website, under Integrations → Patient widget → Your website. Choose Verify on a website that isn't verified yet and pick one way. Team email: a team member who signs in with an address at the domain verifies it by themselves. DNS record: add a TXT record to the domain, with the value nezercare-site-verification=<your token>. Home page tag: add this tag to the <head> of its home page and publish it:
<meta name="nezercare-site-verification" content="<your token>">For the DNS record and the tag, choose Check now in the panel once it's published. The token is yours alone and is shown in the Verify panel, with a Copy button. When a website is verified but the widget isn't on it yet, choose Turn on the widget to list it. One workspace holds a verified domain (www. and every subdomain included). Until it is verified, the widget works in the Playground. Websites on shared hosts such as wixsite.com or github.io, and on free mailbox domains, can't be verified: use a domain of your own.
Workspaces whose widget was already live when verification started were carried over as verified, so their snippet and sign-in keep working as before.
Sign patients in
When a patient is logged in on your site, your backend signs a short-lived JWT so the widget knows who they are without a second login. Create the signing secret under Integrations → Patient widget; it's shown once. Only HS256 is accepted.
This is how patients get into NezerCare on your website: there's no import for adding them in bulk. (If you have your own patient portal and use NezerCare through the API instead of the widget, your server identifies each patient with POST /v1/patients/identify and the same ID: see Patient messaging.) The first time a patient signs in, NezerCare adds them to your workspace with the name and email in the token. After that, each sign-in finds them by sub and updates their name, email and phone from the token. A claim you leave out is never cleared.
| Claim | Value |
|---|---|
sub | Required. The patient's permanent ID in your system (1–200 characters). Workflow calls send it to your systems as patient.externalId and patient searches match on it, so keep it the same every time. |
aud | Required. Your widget ID: the data-environment value in your snippet. |
iat | Required. Issued at, a whole number of seconds since the epoch, no more than a minute ahead of NezerCare's clock. |
exp | Required. Expiry, a whole number of seconds, in the future and at most 10 minutes after iat. |
jti | Required. A unique ID of up to 128 characters. Each token works once. |
given_name | The patient's first name (1–80 characters). Needed the first time a patient signs in. |
family_name | Optional. The patient's last name (1–80 characters). |
email | A valid email address (3–254 characters). Needed the first time a patient signs in. |
phone_number | Optional. The patient's phone number (7–30 characters). |
The profile claims use the OpenID Connect names, so a token from your identity provider's claims usually needs no mapping. A blank claim counts as left out, and so does one that's present but invalid, such as a phone number that's too short: it isn't stored, and the patient still signs in. The only exception is a first sign-in, which needs a valid given_name and email to add the patient. The signature, aud, exp and jti are always checked strictly.
Hand the token to the widget on the page:
window.NezerWidget.identify(identityToken);To call it before the script has loaded, queue it:
window.NezerWidget = window.NezerWidget || { q: [] };
window.NezerWidget.q.push(["identify", identityToken]);Patients sign in only from a verified website
The widget tells NezerCare which page the patient is on (the browser vouches for it, and the frame only listens to your allowed websites). A sign-in is accepted only from one of your live websites: an allowed website whose domain you have verified. A page on http://localhost never counts, because anyone can say they are on localhost. From any other page the request is refused with 403 and the code WEBSITE_NOT_VERIFIED, before the token is looked at: no patient is added, no session is made, and the token isn't used up, so the same token works once the website is verified. The patient sees “This site isn't set up for sign-in yet. Contact the clinic directly; if this is an emergency, call 911.” and the widget's 911 line stays. A workspace with no verified website can't sign anyone in. One-time links in care-update emails follow the same rule: they open only on your verified widget page, and a link opened anywhere else is left unused.
Sign a fresh token every time
Tokens last at most ten minutes and work once. Don't log them, send them to analytics or put them in URLs. Sign one only for a patient your site has signed in: anyone with your signing secret can add patients to your workspace, so keep it on your server and rotate it if it leaks. Sign-ins can add up to 500 new patients an hour per workspace; past that, a patient NezerCare doesn't know yet is refused until the hour has passed, while patients it knows still sign in.
Every refusal looks the same, so the endpoint can't reveal who is a patient. If sign-in fails, check the token is signed with the current secret, aud is your widget ID, it hasn't expired or been used, and a patient signing in for the first time has a valid given_name and email. The one refusal that doesn't look the same is WEBSITE_NOT_VERIFIED (above): it says nothing about patients, only that the page isn't one of your verified websites. Sign-ins are also limited per network address (429 with the code RATE_LIMITED; generous for a busy site, and a patient who is limited just tries again in a few minutes).
JavaScript API
| Call | What it does |
|---|---|
NezerWidget.identify(token) | Signs in the patient the token names, adding them on their first sign-in. |
NezerWidget.open() | Opens the widget's panel. |
NezerWidget.close() | Closes it. |
NezerWidget.greeting(false) | Keeps the greeting from appearing on this page, and takes it down if it's showing. greeting(true) allows it again. |
Every call can be queued before the script loads, like identify:
window.NezerWidget = window.NezerWidget || { q: [] };
window.NezerWidget.q.push(["greeting", false]); // e.g. on a checkout pageWhen a visitor who isn't signed in needs to sign in to reach your care team, the widget fires a nezer:sign-in-requested event on window, so you can show your own login:
window.addEventListener("nezer:sign-in-requested", showLogin);Pop-up greeting
When your team turns it on (Playground → Display → Pop-up greeting), the chat button says hello a few seconds after the page loads, in the style they pick: a short message pops up above it (the assistant's avatar, the message, who it's from, up to two quick replies and a close button), or your logo peeks out of it, says “Hi!” and ducks back in, and the chat opens on the message. Then there's a red 1 on the chat button. There's nothing to install.
- It shows at most once per browser session, never while the widget is open, and never again once the visitor opens the chat or closes it. With the message style, on phones (480 pixels wide or less) and short screens (under 500 pixels high) only the red 1 shows, and once the visitor scrolls on, a shown message folds into it. The peek plays on phones too; with reduced motion it doesn't play, and only the red 1 shows.
- A quick reply opens the widget and sends the reply as the visitor's first message, through the same path as a typed one. Your page only tells the widget which reply was picked.
{first_name}in your greeting is filled in only for a patient you signed in withidentify; for everyone else it disappears (“Hi 👋”). The name stays inside the widget's own elements and is never logged.- It stores only that it was shown, in your site's
sessionStorage(nezer-greeting:<organization>:<widget ID>). Nothing a visitor types is stored. - It never takes focus and is announced to screen readers once, politely. It always says the assistant is an AI.
Email links
Care-update emails link to your widget page with a one-time code in the URL fragment: #nezer_launch=<code>, plus &nezer_case=<id> for a care update, or &nezer_conversation=<id> when your team sent the patient a message. Fragments never reach your server, so the code stays out of your logs. The widget opens the case or conversation (or its home screen, for a code on its own) and removes the code from the address bar once it's been used. A code works once.
What your page can see
The widget runs in a frame served by NezerCare, so scripts on your page (analytics, tag managers, session replay) can't read what patients type or the messages they get. Your page can still see:
- The page address, which holds the one-time code until the widget has used it (usually under a second). Keep the snippet above your analytics tags, and don't capture URL fragments.
- Identity tokens your backend signs.
- That the widget is open, but not what's in it.
The widget's 911 line always shows and can't be hidden or restyled.
If your site sets a Content-Security-Policy
The widget needs four things from a strict policy. The script and the frame come from NezerCare's address, the same one as in the snippet, and the frame talks to NezerCare itself, so your connect-src needs nothing for it.
- Script: allow the NezerCare address in
script-src, or give the snippet's<script>tag your page's nonce. - Frame: allow the NezerCare address in
frame-src(orchild-src). - Styles: the button and greeting are styled by one
<style>element. If yourstyle-srcallows only nonced styles, put your nonce on the snippet's<script>tag: the widget gives the same nonce to its<style>. Otherwise allow inline styles. - Images: allow the NezerCare address and
https:inimg-srcfor your logo in the button and greeting.