> For the complete documentation index, see [llms.txt](https://docs.mdintegrations.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mdintegrations.com/partner/key-concepts/messaging.md).

# Messaging

Messaging connects patients, clinicians, and support staff throughout an Encounter, and it does so while keeping patient-facing conversations cleanly separated from internal coordination between your team and MDI's.

Every message travels over one of two channels — the Patient Channel or the Support/Internal Channel — and both support rich content well beyond plain text.

### Message types

Messages can include:

* Text
* Image and document attachments
* Audio and video attachments
* Emoji reactions
* Metadata
  * Upsell Offerings
  * Frequently asked questions

### Channels

**Patient Channel** connects a patient with their care team. Use it for clinical follow-up, support requests, and treatment questions — anything the patient should see and respond to directly.

**Support/Internal Channel** connects physicians with MDI or Partner support staff, and patients never see it. Use it for case coordination that shouldn't reach the patient, such as flagging incomplete intake information or sorting out a shipping issue.

{% hint style="danger" %}
Check a message's channel before rendering it. Never display Support/Internal messages in a patient-facing interface.
{% endhint %}

### Integration options

Once you know which channel a message belongs to, the next question is how patients and clinicians actually see and send messages. Most Partners lean on MDI's messaging experience, which comes built in on the white-label Patient Portal, but if you'd rather build your own interface, MDI also exposes endpoints and webhooks so you can drive messaging through your own platform instead.

| Option            | Build effort                        | Branding control | Best for                            |
| ----------------- | ----------------------------------- | ---------------- | ----------------------------------- |
| White-label embed | <p>Minimal</p><p>(embed a link)</p> | Extensive        | Partners using the Patient Portal   |
| Custom-built      | Full UI required                    | Full control     | Partners integrating purely via API |

{% hint style="warning" %}
When doing custom-built, your UI must support rich-content including video and audio recording as well as rendering additional content such as FAQs and CarePair recommendations.
{% endhint %}

### Webhooks and filters

Whichever integration option you choose, the same event stream drives it under the hood. Every message creation triggers a **New Case Message** event, also called **Message Created**, and it fires the same way regardless of whether the sender is a patient, a physician, or a support agent, and regardless of which channel the message lands in.

The payload identifies:

* The Encounter through `case_id`
* The Patient or Support/Internal channel
* The sender through `from`
* The content through `text` and `message_files`

Because patient-sent and clinician-sent messages trigger the identical event, you'll need to filter on `from` before deciding whether — and whom — to notify.

{% hint style="warning" %}
Never notify the sender about their own message. If `from` is the clinician or support side, notify the patient. If `from` is `patient`, notify support or log the event.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.mdintegrations.com/partner/key-concepts/messaging.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.