Skip to content

Guides

Use NezerCare from your own patient portal

Your portal draws the screen. NezerCare does everything behind it exactly as it does for the widget: the emergency check first on every message, health concerns asked about and sent to your care team and never answered by AI, requests for your other teams gathered in a short chat, your own workflows, everyday questions answered from your knowledge, and your team's replies back in the same conversation.

When to use it

Use it when your patients are already logged in to a portal or app of yours with its own inbox, and the widget would be a second place to look. Your server tells NezerCare who the patient is, sends what they write, and shows what comes back. Your engineers build the screen; NezerCare is everything behind it.

Don't use it for someone who isn't logged in: nothing an anonymous visitor types is stored or answered here. For your public website, use the patient widget, which can be on the same site. There is no plan to buy for this; messages cost what they cost in the widget (an answer from your knowledge is one credit, each AI turn of the health-concern questions or the guided chat is one, a workflow run that finishes is two, and a request that reaches your billing, scheduling, fulfillment or support team is opened as a case in Operations, which is two; the patient's message, the emergency notice, sending a health concern to your care team and everything NezerCare does when the workspace is paused are free).

It is server to server: your server holds an API key and calls NezerCare, so the widget's website verification doesn't apply. The key never goes in code that runs on a patient's device or in their browser.

The safety requirements

NezerCare can't control your screen, so safety is shared. NezerCare decides what is an emergency, first, on its own side with no AI, files it with your care team, and sends the notice in the response to the very call that caused it, marked as an emergency and first in the list. Your portal must show it. An owner or administrator confirms this when they create the key; the confirmation is recorded and audited.

Your portal must

  1. Show an emergency message the moment it arrives, in full, in NezerCare's words, more prominently than any other message. Never hide, delay, queue, shorten, translate or rewrite it. That includes one that arrives when the patient reads the conversation again.
  2. Show a 911 line, with the sentence NezerCare sends in conversation.safety, at all times wherever the patient can write or read messages.
  3. Not answer a health question with its own AI (or any other) in these conversations, and not configure the screen to.
  4. Send each patient message to NezerCare as the patient wrote it, without filtering, holding or editing it first.
  5. Show NezerCare's messages without changing their meaning, and never present your own message as NezerCare's.
  6. When a send fails or a reply can't be read, say so plainly, keep the 911 line in view, and don't tell the patient the care team has the message unless NezerCare confirmed it (a 201).
  7. Identify only patients you have authenticated, keep each patient's messages separate, and keep the key on your servers.
  8. If you rely on your own notification when the care team replies, tell the patient promptly yourself: NezerCare also emails them (see below).

An error response to a message that was an emergency carries the same guidance (showCall911 and emergency), even when the request was refused for another reason (NezerCare reads the first 10,000 characters of the text, the longest message it takes, so words past that in a message refused for its length get no guidance). To see your screen handle one, send I have chest pain and I can't breathe as a test patient with a test key.

Quick start

  1. An owner or administrator creates a key under Integrations → API keys, turns on Patient messaging, and confirms the safety requirements above. Existing keys don't have it. Your organization's BAA must be signed. A NezerCare setup test key (nzh_test_…) can be given the same scope and works on made-up test patients before the BAA.
  2. Identify the patient when they first use messaging (from your server). Keep the returned patientId.
  3. Start a conversation with the patient's first message. Show the replies from the response.
  4. Send the patient's next messages into that conversation.
  5. Subscribe your endpoint to conversation.message_created (Integrations → Notifications) so replies arrive as they happen, and read the conversation when it opens, when the app returns to the foreground, and on a slow timer while it's open.
  6. Send a test emergency and check that your screen shows the notice at once.
cURL
# 1. Who the patient is (adds them the first time)
curl https://api.nezercare.com/v1/patients/identify \
  -H "Authorization: Bearer $NEZER_KEY" -H "Content-Type: application/json" \
  -d '{"externalPatientId":"pt_48213","givenName":"Maria","email":"maria@example.com"}'
# -> 201 {"patientId":"2c3d4e5f-…","externalPatientId":"pt_48213","created":true,"status":"active"}

# 2. Their first message
curl https://api.nezercare.com/v1/patients/$PATIENT_ID/conversations \
  -H "Authorization: Bearer $NEZER_KEY" -H "Content-Type: application/json" \
  -d '{"requestId":"9d1f7a52-3c6e-4b85-8f0a-5b2c1d7e9a30","language":"en","text":"Do you ship to Texas?"}'

# 3. Read it again later
curl "https://api.nezercare.com/v1/patients/$PATIENT_ID/conversations/$CONVERSATION_ID/messages?afterSequence=2" \
  -H "Authorization: Bearer $NEZER_KEY"

The calls can take a few seconds (a knowledge answer is usually under two): allow up to 60 seconds, and show your own "typing" state while the request is open.

What a message does

The reply to a message is in the response to that call. Every message goes through the same steps, in this order:

StepWhat happens
Emergency checkFirst, by the widget's own fixed rule (English and Spanish, and French, Haitian Creole and Portuguese for the core emergencies) and your own extra emergency phrases. No AI, no credits, no limit, and it works while your workspace is paused. A match is filed with your care team as an emergency case, and the notice is the first message of the response.
A health concernNever answered by AI. It starts the health-concern questions: the safety checks and your approved questions (question messages), then "Does this look right?" (review), and when the patient presses Send it goes to your care team (handoff).
A request for another teamBilling, scheduling, fulfillment and support start a short guided chat the same way (question, review, handoff).
A request you built a workflow forThe workflow runs: its replies, an order lookup's orders, and what it needs next.
An everyday questionAnswered from your own knowledge, with its sources: an answer message, one credit. Past the hourly AI limit, or when the knowledge has no answer, it goes to the right team.
A conversation your team already hasThe patient's next message goes into that thread. NezerCare doesn't answer it; the replies you get are your team's.
A paused workspaceThe trial ended, or it's out of credits: the health-concern questions run with no AI, anything else goes to your team with a notice that replies may be delayed. A message is never refused, and nothing is charged.

If a guided part can't run (NezerCare has switched the health-concern questions off for your clinic), the message goes straight to the right team as a handoff, so it always reaches a person.

The messages

Every message has an id, a sequence (1, 2, 3 with no gaps; order by it), kind, from (patient, nezer or care_team, with the label to show, never a staff name), priority, language and text. text is always the words to show: a portal that prints nothing else is correct. The other fields depend on the kind.

kindFromWhat it is
textpatient, care_teamThe patient's words, or a reply from your care team.
answernezerAn answer from your knowledge: sources (show them), a Book action when your site has one, and the buttons helpful and talk_to_team. Send a button as choiceId with inReplyTo.
questionnezerNezerCare asks something, in fixed or clinic-approved words: purpose (safety_check, intake, team_chat or workflow) and input: buttons (choice), words (text) or photos (attachments).
reviewnezer"Does this look right?" with the summary, the button send, and a text box for a correction.
ordersnezerA workflow's order lookup: the patient's latest orders (at most three), with status, carrier, expected date, items and an https tracking link.
handoffnezerIt reached a team (the patient sent it, or NezerCare did for an urgent concern they left unsent): a reference the patient and your team can both quote, and the team.
emergencynezerThe reviewed 911 guidance, in the language the patient wrote in. Always priority emergency, and first.
noticenezerpaused: replies from this clinic may be delayed.
closednezerYour team resolved the case or closed the conversation. Never the resolution note.

Each response also carries the conversation: its status, careStatus (only the widget's own words: Received, Your care team is on it, New reply from your care team, Appointment scheduled, Closed), appointment, showCall911, lastSequence and safety, the exact 911 line to print.

appointment is null or { "scheduledFor": "…", "visitUrl": "https://…" }: the appointment of the case the conversation is linked to, for your screen to show your patient and a button that opens visitUrl. It is there from booking until an hour after the start, and not once the case is closed or the appointment cancelled. visitUrl is null for an appointment booked before links were required. Show the link to that patient only, and don't log it or put it in a URL: it lets whoever has it join the visit. How an appointment is booked is in Take cases into your clinical system.

An emergency

Response, 201
{
  "conversation": { "id": "4a1c8e90-…", "showCall911": true, "safety": { "emergencyLine": "If this is a medical emergency, call 911.", "lines": [{ "label": "Call 911", "tel": "tel:911" }] }, "…": "…" },
  "message": { "sequence": 1, "kind": "text", "from": { "kind": "patient", "label": "You" }, "text": "I have chest pain and I can't breathe", "…": "…" },
  "replies": [
    {
      "sequence": 2,
      "kind": "emergency",
      "priority": "emergency",
      "from": { "kind": "nezer", "label": "NezerCare" },
      "text": "Call 911 now. What you described can need emergency care. Do not wait for your care team to reply.",
      "emergency": { "lines": [{ "label": "Call 911", "tel": "tel:911" }], "sentToCareTeam": true },
      "…": "…"
    }
  ],
  "showCall911": true,
  "emergency": {
    "language": "en",
    "message": "Call 911 now. What you described can need emergency care. Do not wait for your care team to reply.",
    "lines": [{ "label": "Call 911", "tel": "tel:911" }]
  },
  "duplicate": false
}

A second emergency within 15 minutes joins the patient's open emergency case, and the notice is shown again each time. Thoughts of self-harm add a Call or text 988 line. An emergency typed at any step of the questions, the chat or a workflow is handled the same way, and the case holds what the patient had said before it.

If filing with the care team doesn't succeed at once, sentToCareTeam is false and the notice is shown all the same, in the same words. NezerCare keeps trying (every minute, and whenever the conversation is read) until the care team has it; you don't need to do anything, and the 911 line stays in view.

Health concerns and requests for a team

A health concern is asked about, not answered. NezerCare asks the safety checks your clinic wrote, as written, and then your approved questions, one at a time; the AI only chooses which approved question comes next, and every word the patient reads is a fixed line, your question, or their own. The patient answers a question by pressing a button (send its id as choiceId, with inReplyTo the question's id) or by typing. When there is enough, a review shows a summary built from the patient's own words. Pressing send files it with your care team; typing instead is a correction that rewrites the summary.

A safety check, its answer, and the review
// a reply of the first message (kind "question")
{ "id": "b2c3d4e5-…", "kind": "question", "purpose": "safety_check",
  "text": "Is the redness spreading, or are there red streaks from the spot?",
  "input": { "type": "choice", "choices": [
    { "id": "yes", "label": "Yes" }, { "id": "no", "label": "No" }, { "id": "unsure", "label": "Not sure" } ] } }

// POST …/messages
{ "requestId": "3f8e2a10-…", "choiceId": "no", "inReplyTo": "b2c3d4e5-…" }

// later, a reply (kind "review")
{ "id": "c3d4e5f6-…", "kind": "review", "text": "Does this look right?", "status": "ready",
  "summary": "Here's what I understood: …",
  "choices": [{ "id": "send", "label": "Yes, send it" }],
  "input": { "type": "text", "hint": "Need to change something?" } }

// POST …/messages
{ "requestId": "7a8b9c0d-…", "choiceId": "send", "inReplyTo": "c3d4e5f6-…" }
// -> a reply of kind "handoff": "Sent to your care team. …", team "clinical"
  • conversation.awaiting says what the latest message waits for (choice, text, attachments): a hint for your composer, never a lock. Free text is always accepted.
  • A button on a message that isn't the latest, or that doesn't offer it, is 409 STALE_ANSWER: read the conversation again.
  • A safety check answered yes or not sure can make the concern urgent: the next message carries the shortcut send_now ("Send to my care team now"), and the concern is sent at once when pressed. One the patient walks away from is filed for them after ten minutes, and the conversation then contains a handoff saying so: it reaches your webhook (conversation.message_created) within seconds, and a read of the conversation or its messages shows it too. A safety check your clinic marked as an emergency, answered yes, is an emergency: the notice, first, as above.
  • Questions or a chat left for more than an hour, or a workflow run left for 30 minutes, are over: the patient's next message starts a new topic in the same conversation (an urgent concern is never let go: NezerCare files it).
  • Billing, scheduling, fulfillment and support requests use the same question, review, send and handoff, with purpose: "team_chat". While your workspace is paused they don't run: the message goes straight to the team.

Workflows

A request you built a workflow for runs it, as it would in the widget. Each reply is a text message; the step that needs something is a question with purpose: "workflow": input.type is text (answer in words), choice (yes or no), or attachments (add photos with the attachments call, then press done, or skip when there are none). An order lookup's orders come as an orders message, before the question. When the run ends, a last question offers a person (talk_to_team); a run that hands off ends with a handoff in your own words. Pressing talk_to_team sends the whole exchange to your team. A workflow run that finishes costs two credits.

Photos and PDFs

Upload a file first, then name it in the patient's next message. The same limits as the widget apply: up to 10 MB, a JPEG, PNG, WebP, HEIC or PDF (the file's first bytes decide, not its name), and up to 10 files for a conversation or a run. Your team sees it as a widget upload. Sending the same bytes again returns the same file. Send only the file: one file in the field file and no other form fields, or the request is 400 INVALID_REQUEST.

The file is checked and cleaned before it is stored. A JPEG, PNG or WebP is decoded and saved again (same format, at most 4096 pixels on the long side), so its location, camera details, comments and anything after the image are gone and its orientation is applied. A HEIC has its metadata erased in place. A PDF is kept exactly as sent, unless it holds JavaScript, a launch action, an embedded file, rich media, an XFA form or encryption. A file that can't be accepted for what is in it is 422 ATTACHMENT_REJECTED, with the same message whatever the reason (We couldn't accept this file. Please try a different photo or PDF.): tell the patient and let them choose another file; don't retry the same one. The sizeBytes and sha256 in the answer are the stored file's, so for a photo they differ from the bytes you sent.

cURL
curl https://api.nezercare.com/v1/patients/$PATIENT_ID/conversations/$CONVERSATION_ID/attachments \
  -H "Authorization: Bearer $NEZER_KEY" -F "file=@spot.jpg;type=image/jpeg"
# -> 201 {"id":"a0b1c2d3-…","fileName":"spot.jpg","contentType":"image/jpeg","sizeBytes":482113,"sha256":"…"}

curl https://api.nezercare.com/v1/patients/$PATIENT_ID/conversations/$CONVERSATION_ID/messages \
  -H "Authorization: Bearer $NEZER_KEY" -H "Content-Type: application/json" \
  -d '{"requestId":"6c1d9e47-…","text":"Here is a photo of the spot.","attachments":[{"id":"a0b1c2d3-…"}]}'

A file goes to the workflow run that is asking for photos, or to the conversation your team has with the patient; anywhere else it's 409 ATTACHMENT_NOT_EXPECTED (tell the patient to send words). While the workspace is paused, photos for a workflow run are refused, and photos for your team's conversation are taken. The feed shows a file's name, type and size, never its contents.

The care team's replies

When your team replies (in Conversations, in the Clinical queue, or from your own system through the clinical-case API), the reply appears in the conversation's feed as a message from.kind: "care_team" with the label Care team. Read the feed to get it:

GET …/messages?afterSequence=2
{
  "messages": [
    {
      "id": "e5f6a7b8-c9d0-4e1f-8a3b-4c5d6e7f8091",
      "sequence": 3,
      "kind": "text",
      "from": { "kind": "care_team", "label": "Care team" },
      "priority": "normal",
      "language": "en",
      "text": "Please keep the spot clean and dry. A nurse will call you today.",
      "createdAt": "2026-10-18T16:21:44.000Z"
    }
  ],
  "lastSequence": 3,
  "hasMore": false,
  "conversation": { "status": "open", "careStatus": { "code": "replied", "label": "New reply from your care team" }, "…": "…" }
}
  • Reading brings the feed up to date first, so a read is never stale. A reply appears once, however often you read.
  • Internal notes, resolution notes and anything staff-only are never in the feed or in an event.
  • When the case is resolved or the conversation closed, a closed message arrives and the conversation's status is closed. A new message is then 409 CONVERSATION_CLOSED (start a new conversation), except an emergency, which is always taken and reopens it. A message your system sends to the case through the clinical-case API after that is stored for the case but isn't added to the closed feed.

Webhooks

Webhooks tell your server of a reply within a second or two, so you needn't poll fast. In Integrations → Notifications add your endpoint and tick Portal conversation: a new message and Portal conversation: its state changed. They are the existing signed webhooks (the same headers, signature, 12 retries and BAA hold); you verify and deduplicate them the same way.

EventSent when
conversation.message_createdA message was added to a conversation: the patient's own, NezerCare's reply, or the care team's. The body is data.message (exactly what the feed returns), its sequence, who it is about (conversationId, patientId, and your own externalPatientId and externalConversationId) and a short conversation snapshot (status, careStatus, showCall911, version).
conversation.updatedThe conversation's status, careStatus, appointment (booked, moved or cancelled), showCall911 or awaiting changed with no message to carry it (a teammate took the case: "Your care team is on it"). The body is the conversation as the API returns it, except that appointment has only scheduledFor: a webhook never carries the visit link, so read the conversation for it. A change that comes with a message arrives in that message's event, though one can still follow it right away with the same version: keep the higher version, and applying one you already have changes nothing.
conversation.message_created
{
  "id": "5f0c1d7e-3a5b-4c6d-9e8f-0a1b2c3d4e5f",
  "type": "conversation.message_created",
  "createdAt": "2026-10-18T16:21:45.000Z",
  "data": {
    "conversationId": "4a1c8e90-…",
    "externalConversationId": "portal-thread-991",
    "patientId": "2c3d4e5f-…",
    "externalPatientId": "pt_48213",
    "sequence": 3,
    "message": { "id": "e5f6a7b8-…", "sequence": 3, "kind": "text", "from": { "kind": "care_team", "label": "Care team" }, "priority": "normal", "language": "en", "text": "Please keep the spot clean and dry. A nurse will call you today.", "createdAt": "2026-10-18T16:21:44.000Z" },
    "conversation": { "status": "open", "careStatus": { "code": "replied", "label": "New reply from your care team" }, "showCall911": false, "version": 7 }
  }
}

Webhooks are for speed; the feed is the truth

  • Delivery is at least once, in parallel and in no promised order, and a delivery gives up after 12 attempts. Apply messages by sequence, not by arrival.
  • If an event's sequence is more than one above the last you have, read GET …/messages?afterSequence=<the last you have> and apply what it returns. The feed always works, even when your endpoint was down.
  • Deduplicate by x-nezer-event-id and by message.id: the patient's own messages and NezerCare's replies to them are sent too, so a second device or tab sees them.
  • An emergency message in an event must be shown at once like the one in a response. The response to the patient's call always carries it first; a webhook is never the only way you hear of an emergency.
  • Bodies hold patient messages: keep them out of ordinary logs. Your endpoint must be https on a public DNS name; NezerCare never sends to a private or local address.

Still read the conversation when it opens, when the app returns to the foreground, and on a slow timer while it's open (every minute is plenty with webhooks, 5 to 15 seconds without). An empty read costs nothing and isn't logged.

Tell us what your screen did

Report each message your screen showed, read or couldn't show. A failed report opens a work item for your care team ("External delivery failed", in Operations), urgent when the message was an emergency notice, so a person can reach the patient another way.

Confirm every 911 notice. Send delivered the moment your screen shows an emergency notice. A notice with no receipt of any kind two minutes after it was sent opens an urgent work item for your care team ("Emergency notice not confirmed", due within 15 minutes), because NezerCare can't know the patient saw it. Notices of one conversation within 15 minutes share one item. A portal that sends no receipts at all gets an item for every emergency.

POST …/messages/{messageId}/delivery
curl https://api.nezercare.com/v1/patients/$PATIENT_ID/conversations/$CONVERSATION_ID/messages/$MESSAGE_ID/delivery \
  -H "Authorization: Bearer $NEZER_KEY" -H "Content-Type: application/json" \
  -d '{"status":"failed","errorCode":"render_error"}'
# -> 201 {"conversationId":"…","messageId":"…","status":"failed","duplicate":false,"recordedAt":"…"}

Each status is recorded once per message (a repeat is 200 with duplicate: true). errorCode is a short machine word, never anyone's words. Only messages NezerCare or the care team sent can have a receipt.

A patient's conversations

GET /v1/patients/{patientId}/conversations lists the patient's conversations, newest activity first (status, limit up to 50, and after with the page's nextCursor): what an inbox screen draws, with each conversation's careStatus and lastSequence, and no message text. GET /v1/patients/{patientId}/conversations/{conversationId} reads one, never stale. A list is as the care team's replies last reached it (a second or two behind); open a conversation to read its messages. Another patient's conversation or another workspace's is 404.

Retries

Every patient message has a requestId you generate (a UUID). To retry one that failed or timed out, send the same requestId and the same words: NezerCare returns the stored turn (duplicate: true) and never charges or sends to your team twice, even if a first attempt stopped halfway: the questions aren't answered twice, the AI isn't asked again, and the team doesn't get the message twice. Two patients (or two clinics) may use the same requestId without any effect on each other. The same ID with different words is 409 REQUEST_ID_REUSED. While the first attempt is still running, a retry gets 409 TURN_IN_PROGRESS with Retry-After: wait, then try again. An emergency message is never made to wait.

Limits

The limits below are an abuse backstop, far above what a portal uses. A refused message is 429 RATE_LIMITED with Retry-After (seconds): wait that long, then retry with the same requestId, and tell the patient it wasn't sent while it waits.

LimitHow much
One patient20 messages a minute
One API key, requests600 a minute and 20,000 an hour, on every route the key can call: this API, the conversation gateway and the care hand-off together (a patient's message counts as one)
One API key, new conversations60 a minute and 1,000 an hour
One API key, credits500 a day unless your clinic chose another number (Integrations → Notifications → Patient messaging), counted from midnight UTC

An emergency is never refused

The emergency check comes first, before any limit. An emergency message is never counted against these limits, refused or charged, never waits for another message, and works while the workspace is paused: its notice is always in the response, and the case is always in your care team's queue.

What NezerCare stores of a key's emergencies has a ceiling, so that a leaked key cannot fill your clinic's records with them: up to 300 emergency messages an hour for a key are stored in full. Past that, a patient whose emergency your care team already has (an unresolved emergency case of theirs from the last 15 minutes) is still answered at once with the 911 notice, first and in full (showCall911: true, emergency.sentToCareTeam: true), with duplicate: true, and the repeat is not stored: it won't be in the feed. Show the notice from the response; never wait for the feed. A different patient's emergency is always filed. Your care team is told, in Integrations, when the notices of a key's emergencies go unconfirmed: up to 20 items an hour, then one summary. Confirm each notice with a delivered receipt.

A key that has used its credits for the day is not refused. Its patients' messages run as a paused workspace's do: no AI reply, nothing charged, every message goes to your care team with a notice that replies may be delayed, until midnight UTC. Your clinic can raise the number, and sees which key reached it.

When you test with emergency messages, use a nzh_test_ key and made-up patients. Your care team is told of a real key's emergencies one by one for the first 10 in an hour; past that it gets one summary ("N more emergencies from your API key in the last hour") instead of one alert each. Every one of them is still a case in the Clinical queue and still has its 911 notice in your portal.

Errors

Every error is { "code": "…", "message": "…" }; the message is for you, never for the patient.

StatuscodeWhat to do
400INVALID_REQUESTFix the request (both or neither of text and choiceId, text over 10,000 characters; for a file, anything in the upload besides one file in the field file).
400PATIENT_PROFILE_REQUIREDNezerCare doesn't know this patient yet: send a valid givenName and email.
401MISSING_API_CREDENTIAL, INVALID_API_CREDENTIALFix the key. Tell the patient the message wasn't sent.
403BAA_REQUIREDDon't retry: sign the BAA. Tell the patient the message wasn't sent and keep the 911 line in view.
403INSUFFICIENT_SCOPEThe key doesn't have patient messaging. Create a key with it.
404PATIENT_NOT_FOUND, CONVERSATION_NOT_FOUND, MESSAGE_NOT_FOUNDNot in this workspace, or not this patient's. Don't retry.
404ATTACHMENT_NOT_FOUNDA file listed in a message isn't one this patient added to this conversation (or was deleted since). Upload it again.
409REQUEST_ID_REUSEDUse a new requestId for a new message.
409CONVERSATION_CLOSEDStart a new conversation.
409STALE_ANSWERThat answer isn't waiting any more. Read the conversation again.
409TURN_IN_PROGRESSWait for Retry-After, then retry with the same requestId.
409PATIENT_INACTIVEThe patient's care was cancelled. An emergency is still taken: show its guidance.
409PATIENT_ID_UNAVAILABLEOn identify: this externalPatientId can't be used here. Use the ID your site signs the patient in with.
409ENVIRONMENT_RETIREDThe key belongs to an earlier copy of your workspace. Create a new key.
409ATTACHMENT_NOT_EXPECTEDThere is nowhere to attach a file right now. Tell the patient to send words.
409ATTACHMENT_LIMIT_REACHEDThe conversation or run already has 10 files.
413ATTACHMENT_TOO_LARGEOver 10 MB.
415ATTACHMENT_TYPE_NOT_ALLOWEDNot a JPEG, PNG, WebP, HEIC or PDF.
422ATTACHMENT_REJECTEDA photo or PDF refused for what is in it (it won't decode, or holds JavaScript, an embedded file or similar). Show the patient the message and let them choose another file.
409EXTERNAL_CONVERSATION_ID_IN_USESend follow-ups to the existing conversation.
429RATE_LIMITEDA patient may send 20 messages a minute, and an API key has its own limits on requests (on every route it can call) and new conversations (never an emergency message). Honor Retry-After.
429PATIENT_CAP_REACHEDAt most 500 new patients per workspace per hour; patients already known keep working.
503PATIENT_FILES_UNAVAILABLENo attachment was stored. Wait for Retry-After, then retry the upload.
5xxnoneRetry with the same requestId and backoff. If it keeps failing, tell the patient the message wasn't received and keep the 911 line in view.

A patient's message is never answered with 423 or 402, and is never refused for credits.

What patients are emailed

When your team replies, NezerCare sends the patient the same short "your care team sent you a message" email it sends for the widget (it never contains the message). Your clinic chooses who tells the patient in Integrations → Notifications → Patient messaging (an owner or administrator, with a recent two-step sign-in):

ChoiceWhat NezerCare does
NezerCare and your portalThe default. NezerCare emails the patient and your portal tells them too.
Your portal onlyNezerCare sends no email about a reply in a portal conversation. Your portal must tell the patient itself, promptly.
NezerCare onlyNezerCare emails the patient; your portal doesn't notify them.

The setting is only about conversations that come from your portal; the widget's are never affected. It also covers the reminders of an appointment on a case your portal's conversation is linked to (an email a day and an hour before): under Your portal only NezerCare sends none, so your portal reminds its own patient from appointment. It never changes the emergency alerts to your team, the 911 notice your portal shows, or the email for a conversation that has had an emergency: those are always sent.

Who the email says it is from. It comes from NezerCare's address as "Your Clinic via NezerCare", under your clinic's plain name (no link, address or domain in it; a name that leans on words like "bank", "security" or "official" is shown as "Your care team"). A clinic with a verified sending domain sends from its own address instead. A workspace can email only so many patients an hour (30 emails to 20 different addresses on the free trial, 500 to 400 on a paid plan): an email past that waits for the hour and is sent, none is dropped. The email to the address you gave identify is not held for the patient to confirm it, so give NezerCare only addresses your patients gave you, or choose "Your portal only" above.

What is built

Built now: identifying patients, starting a conversation, the patient's messages and buttons, the emergency path (including filing one that couldn't be filed at first), the health-concern questions and review, the guided chat for your other teams, your workflows and order lookups, photos and PDFs, everyday answers, sends to the team, the paused workspace, the care team's replies in the feed, signed webhooks (conversation.message_created,conversation.updated), delivery receipts and the check on a 911 notice nobody confirmed, listing and reading a patient's conversations, the email setting, and the limits on an API key. Planned, and not in this API yet: a reply that arrives later by webhook for a gateway with a short timeout (Prefer: respond-async), and thumbs on an answer. See the API reference for every field.