---
title: "Get message by id"
method: GET
path: "/messages/{messageId}"
tags: ["messages"]
---

# Get message by id

`GET /messages/{messageId}`

## Path parameters

- `messageId` string, required

## Response `200`

Message

- MessageResponse — A Message represents a single communication sent or received between Luma Health and a patient, or between staff members, across channels such as SMS, email, voice, fax, WhatsApp, and in-app chat. It tracks delivery status from the messaging vendor (sent, delivered, opened, undelivered, etc), links back to related records like the appointment, provider, referral, or recall that triggered it, and captures the classification of patient replies such as positive, negative, or unrecognized. It also distinguishes public patient-facing messages from private staff notifications and internal staff-to-staff conversations.
  - `_id` string — Luma's internal ID of an object.
  - `user` string — The ID of the root account user.
  - `deleted` 0 | 1 — Flag for logical deletion where 1 means deleted.
  - `createdBy` string — The ID of the user who created this object.
  - `updatedBy` string — The ID of the user who updated this object.
  - `createdAt` string, date-time — The date/time when this object was created.
  - `updatedAt` string, date-time — The date/time when this object was updated.
  - `patient` string — The ID of the patient linked to this message.
  - `key` string — The MessageTemplate name. There are only 2 templates available through the RESTful API. The secure template means that the patient only gets a generic message with a link to open the patient web app and then read the real message. In that case, there are 2 messages, one with that generic message, and one with the real message. This parameter is set automatically on the message, depending on the `secure` parameter which was chosen when the message was created.
  - `from` string — the phone number or e-mail address from whom this message was received. It depends on the value of the parameter `channel`.
  - `to` string — the phone number or e-mail address to whom this message was sent. It depends on the value of the parameter `channel`.
  - `type` 'inbound' | 'outbound' — Indicates if a message was sent from Luma to an external person, or the other way around.
  - `voiceAnsweredBy` 'human' | 'fax' | 'unknown' | 'machine-start' | 'machine-end-beep' | 'machine-end-silence' | 'machine-end-other' — voiceAnsweredBy
  - `ref` 'reminder' | 'referral-reminder' | 'feedback-reminder' | 'followup' | 'outbound-referral-reminder' | 'form-reminder' | 'reschedule' | 'waitlist' | 'appointment-offer' | 'chat-notification' | 'pin-verification' | 'chat' | 'chat-audit' | 'chat-audit-tz' | 'feedback' | 'waitlist-offer' | 'referral-followup' | 'outbound-referral-outreach' | 'referral-redirect' | 'broadcast' | 'generic' | 'stop' | 'bot:followup' | 'telehealth' | 'waiting-room-patient' — Indicates what this is about. Depending on this value, you also know what the parameter `refId` refers to.<br/> - reminder (`refId` will be the ID of a `Reminder`)<br/> - referral-reminder (`refId` will be the ID of a `Reminder`)<br/> - feedback-reminder (`refId` will be the ID of a `Reminder`)<br/> - followup (`refId` will be the ID of a `Reminder`)<br/> - outbound-referral-reminder (`refId` will be the ID of a `Reminder`)<br/> - form-reminder (`refId` will be the ID of a `Reminder`)<br/> - reschedule (`refId` will be the ID of a `Reminder`)<br/> - waitlist (`refId` will be the ID of a `Waitlist`)<br/> - appointment-offer (`refId` will be the ID of a `Offer`)<br/> - chat-notification (`refId` will be the ID of a `Message`)<br/> - pin-verification (`refId` will be the ID of a `Message`)<br/> - chat (`refId` will be the ID of a `ChatActivity`)<br/> - chat-audit (`refId` will be the ID of a `ChatActivity`)<br/> - chat-audit-tz (`refId` will be the ID of a `ChatActivity`)<br/> - feedback (`refId` will be the ID of a `Feedback` request)<br/> - waitlist-offer (`refId` will be the ID of an `Appointment`)<br/> - referral-followup (`refId` will be the ID of a `Referral`)<br/> - outbound-referral-outreach (`refId` will be the ID of a `Referral`)<br/> - referral-redirect (`refId` will be the ID of a `Referral`)<br/> - broadcast (`refId` will be the ID of a `Broadcast`)<br/> - generic (`refId` will refer to the same object of the previous message to this same patient)<br/> - stop (`refId` will refer to the same object of the previous message to this same patient)<br/> - bot:followup (`refId` will be the ID of a `Patient`)<br/> - telehealth (`refId` will be the ID of a `Telehealth` object)<br/> - waiting-room-patient (`refId` will be the ID of a `WaitingRoomPatient` object)<br/>
  - `refId` string — The ID of the object referenced by the `ref` parameter.
  - `patientMessageTemplate` string — The ID of a Hub Message Template (or `PatientMessageTemplate`). These are custom messages, created by users, to make their typing experience easier.
  - `outboundMessage` string — This field is only present on a patient's reply (aka `messages` whose `type` are `inbound`) so as to link it to the original outbound `message` that was sent to them.
  - `status` 'sent' | 'pending' | 'delivered' | 'undelivered' | 'opened' | 'skipped' — The deliverability status, provided by Luma's external vendors.<br/> Messages are initially created as `sent`, and later updated to some other status.<br/> - Sent = vendor has acknowledged receipt of request<br/> - Pending = vendor has sent non-terminating status update<br/> - Delivered = vendor has confirmed a delivered message<br/> - Undelivered = vendor has confirmed an undelivered message<br/> - Opened = vendor has confirmed an opened message<br/> - Skipped = system skipped sending the message<br/>
  - `skippedStatusReason` string — This field is only present on messages whose `status` is `skipped`. It contains the reason why Luma decided to skip sending the message out.
  - `language` 'ar' | 'bn' | 'cn' | 'de' | 'en' | 'es' | 'fa' | 'fl' | 'fr' | 'gr' | 'gu' | 'hi' | 'ht' | 'hy' | 'it' | 'ja' | 'km' | 'ko' | 'mr' | 'my' | 'pa' | 'pl' | 'pt' | 'ru' | 'so' | 'th' | 'ti' | 'ur' | 'vi' | 'zh-t' | 'zh' — Language
  - `externalStatus` object — Delivery status codes and messages provided by external vendors.
    - `code` string — Status code provided by vendor
    - `reason` string — Status message provided by vendor
  - `channel` 'sms' | 'email' | 'voice' | 'inapp' | 'chat' | 'fax' | 'whatsapp' — The channel used to send this message.<br/> On our RESTful API, you may search for multiple channels, but only POST `chat` messages.<br/> Two of them deserve an explanation:<br/> - `chat` will check the recipient's contact and pick the channel automatically.<br/> - `inapp` are meant for internal messages, when a staff user `@mentions` another staff user on Hub. The mentioned person only gets a notification on their browser window, by fetching from the `notifications` API.
  - `notifyTo` object[] — Messages with channel=chat may specify in this field where the message notification must be sent.
    - `channel` 'sms' | 'email' | 'voice' | 'inapp' | 'chat' | 'fax' | 'whatsapp' — channel
    - `to` string — to
  - `shouldForceContactWithNotifyTo` boolean — When the patient has the patient web app open, we detect that and only send messages through the web interface. This is to avoid having the patient receive the same message both on the web and also by SMS. But if this flag is set to TRUE, then we will send to the contact specified in the `notifyTo` field, regardless of the patient's online presence.
  - `text` string — The content of the message. If the channel was `chat`, then the text was manually provided when the message was created. For all other channels, the `key` was used to fetch a `messageTemplate` and determine the `text` based on that template.
  - `classification` 'positive' | 'negative' | 'irregular' | 'recognized-keywords' | 'unclassified' — The classification of patient replies (inbound messages) interpreted by our NLP (Natural Language Processing) service.<br/> - `positive` indicates a yes-type answer (e.g. "sounds good", "yes", or "ok")<br/> - `negative` indicates a no-type answer (e.g. "no way", "negative", "no good")<br/> - `irregular` indicates classification attempt was not able to classify the text as positive or negative<br/> - `recognized-keywords` indicates that an expected keyword was identified (e.g. "waitlist")<br/> - `unclassified` indicates no classification attempted - yet<br/>
  - `externalId` ExternalId
    - `source` 'gcalendar' | 'successehs' | 'drchrono' | 'dentrix' | 'webpt' | 'theraoffice' | 'mi7' | 'practicefusion' | 'advancedmd' | 'acomrapidpm' | 'kareo' | 'nextech' | 'mwtherapy' | 'clinicient' | 'carecloud' | 'eclinicalmobile' | 'duxware' | 'labretriever' | 'optimispt' | 'referral' | 'recall' | 'allscriptspm' | 'lytec' | 'brightree' | 'fullslate' | 'nuemd' | 'centricityps' | 'officeally' | 'greenwayintergy' | 'compulink' | 'adspm' | 'dsnpm' | 'lumamock' | 'medicalmastermind' | 'meditouch' | 'healthnautica' | 'ezemrx' | 'hl7' | 'amazingcharts' | 'greenwayprimesuite' | 'raintree' | 'athenahealth' | 'revflow' | 'eclinicalworks10e' | 'hl7pickup' | 'mindbody' | 'eclinicalworkssql' | 'nextgen' | 'practiceperfect' | 'avimark' | 'clinix' | 'keymedical' | 'mdoffice' | 'webedoctor' | 'emapm' | 'medinformatix' | 'imsgo' | 'emds' | 'allscriptsunity' | 'medevolve' | 'caretracker' | 'clearpractice' | 'valant' | 'micromd' | 'systemedx' | 'medicalmaster' | 'athenamdp' | 'gmed' | 'roche' | 'onetouch' | 'somnoware' | 'managementplus' | 'lumacare' | 'nextechfhir' | 'curemd' | 'epic' | 'phoenixortho' | 'ezderm' | 'ggastromobile' | 'epicconfirmationpickup' | 'cerner' | 'allmeds' | 'oncoemrfilepickup' | 'imedicware' | 'modmedfhir' | 'clinux' | 'acuityscheduling' | 'medstreaming' | 'isalus' | 'meditechexpanse' | 'openemr' | 'genericfhir' | 'nextechpracticeplus' | 'sms' | 'voice' | 'email' | 'none' — externalId.source
    - `value` string — externalId.value
  - `secure` boolean — Indicates how a message with channel `chat` will be delivered.<br/> Secure messages are created on the database but not really sent to patients. Instead, we create another unsecure message whose content is the messageTemplate `chatRequestInsecure`, which basically instructs the patient to click on a link to open patient-web-app to log in and then read the secure message. Insecure messages are sent directly to patients. Their text should not contain any PHI or sensitive information.
  - `automated` boolean — Indicates if a message was created by users (chat) or by the system (reminders, recalls, etc).
  - `visibility` 'public' | 'private' | 'internal' — Helps determine where a certain message should be displayed. - `public` = manual and automated messages sent to patients, visible to patients logged into our patient web app;<br/> - `private` = automated messages sent to staff, only visible to one recipient staff user;<br/> - `internal` = manual messages sent from staff to staff, visible to both staff users involved in a conversation, whenever one @mentined the other, both logged into our internal web app, and usually on Hub rather than any notification areas.<br/>
  - `file` string — The ID of a `FileUpload`, in case this message has any attachment, sent via the `FileUpload` RESTful API.
  - `media` object — Any recorded media (voice recording, fax image, etc) that represents this message. URL should be the location from which to retreive it
    - `url` string
    - `contentType` string
  - `stats` object — stats
    - `timers` object
      - `elapsedReplyTime` number — How long it took for a user to reply to a message in seconds
      - `pricing` object
        - `segments` number
        - `carrierFee` number
        - `baseRate` number
    - `pricing` string
  - `retry` object — Information about additional messages that were created in an attempt to retry sending messages that failed to be delivered.
    - `originalMessage` string — ID of the original Message that had an undelivered status
    - `count` number — Sequential number of attempts
  - `terminatingStateAt` string, date-time — The time that we recognize a terminal state of a message updated based on the vendor status callbacks.
  - `mentions` object[] — Array of IDs of either users or groups that have been `@mentioned` inside messages, usually messages with visibility `internal`.
    - `ref` 'user' | 'group' — Describes if the `@mention` refers to a `User` ID or a `Group` ID. Determines the meaning of the `refId` field.
    - `refId` string — The ID of either a user or a group that was @mentioned, based on the `ref` value.
    - `mention` string — Literally the string `@SomeOnesName` or `@GroupName` that was used.
  - `recipient` string — The ID of the User receiving the message. Usually, for messages `type outbound`, the recipient is the ID of a patient.
  - `recipientType` 'doctor' | 'staff' | 'patient' — The type of the user in the field `recipient`
  - `appointment` string — ID of Appointment
  - `provider` string — ID of Provider
  - `appointmentType` string — ID of AppointmentType
  - `followup` string — ID of Followup or Custom Action
  - `recall` string — ID of Recall
  - `referral` string — ID of Referral
  - `messageFailure` string — ID of MessageFailure

---

[API](https://skmtc.net/lumahealth/apis/rest-service.md) · [All operations](https://skmtc.net/lumahealth/apis/rest-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lumahealth/rest-service/revisions/d3c75c2a2f1d/schema)