Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
version: 2.0.0
title: Rest-Service Messages API
x-logo:
url: https://lumahealth-assets.s3.us-west-2.amazonaws.com/new_luma_logo_black.png
backgroundColor: '#FFFFFF'
altText: Luma Health
description: OpenAPI [Basic Structure](https://swagger.io/docs/specification/basic-structure/)
servers:
- url: https://api.lumahealth.io/api/v2
security:
- Bearer: []
tags:
- name: messages
description: Messages (chat, sms, voice, email, whatsapp, fax, in-app)
paths:
/messages:
get:
summary: List messages
operationId: messagesList
tags:
- messages
parameters:
- name: patient
in: query
description: The ID of the patient linked to this message.
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
- name: key
in: query
description: '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.
'
schema:
type: string
enum:
- chatRequest
- chatRequestInsecure
- name: from
in: query
description: the phone number or e-mail address from whom this message was received. It depends on the value of the parameter `channel`.
schema:
type: string
- name: to
in: query
description: the phone number or e-mail address to whom this message was sent. It depends on the value of the parameter `channel`.
schema:
type: string
- name: type
in: query
description: Indicates if a message was sent from Luma to an external person, or the other way around.
schema:
type: string
enum:
- inbound
- outbound
- name: voiceAnsweredBy
in: query
description: voiceAnsweredBy
schema:
type: string
enum:
- human
- fax
- unknown
- machine-start
- machine-end-beep
- machine-end-silence
- machine-end-other
- name: ref
description: 'Indicates what this message 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 `Message`)<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/>
'
in: query
schema:
type: string
enum:
- 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
- name: refId
in: query
description: The ID of the object referenced by the `ref` parameter.
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
- name: patientMessageTemplate
in: query
description: The ID of a Hub Message Template (or `PatientMessageTemplate`). These are custom messages, created by users, to make their typing experience easier.
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
- name: outboundMessage
in: query
description: '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.
'
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
- name: status
in: query
description: '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/>
'
schema:
type: string
enum:
- sent
- pending
- delivered
- undelivered
- opened
- skipped
- name: externalStatus
in: query
description: 'Delivery status codes and messages provided by external vendors. <br/>
`code` : Status code provided by vendor <br/>
`reason` : Status message provided by vendor
'
schema:
type: array
items:
type: string
enum:
- code
- reason
- name: skippedStatusReason
in: query
description: 'This field is only present on messages whose `status` is `skipped`.
It contains the reason why Luma decided to skip sending the message out.
'
schema:
type: string
- name: channel
in: query
description: '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.
'
schema:
type: string
enum:
- sms
- email
- voice
- inapp
- chat
- fax
- whatsapp
- name: text
in: query
description: '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.
'
schema:
type: string
- name: classification
in: query
description: '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/>
'
schema:
type: string
default: unclassified
enum:
- positive
- negative
- irregular
- recognized-keywords
- unclassified
- name: secure
in: query
description: '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.
'
schema:
type: boolean
- name: automated
in: query
description: Indicates if a message was created by users (chat) or by the system (reminders, recalls, etc).
schema:
type: boolean
- name: visibility
in: query
description: '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/>
'
schema:
type: string
default: public
enum:
- public
- private
- internal
- name: file
in: query
description: 'The ID of a `FileUpload`, in case this message has any attachment,
sent via the `FileUpload` RESTful API.
'
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
- name: recipient
in: query
description: The ID of the User receiving the message. Usually, for messages `type outbound`, the recipient is the ID of a patient.
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
- name: recipientType
in: query
description: The type of the user in the field `recipient`
schema:
type: string
enum:
- doctor
- staff
- patient
- name: shouldForceContactWithNotifyTo
in: query
description: '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.
'
schema:
type: boolean
- name: appointment
in: query
description: ID of Appointment
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
- name: provider
in: query
description: ID of Provider
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
- name: appointmentType
in: query
description: ID of AppointmentType
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
- name: followup
in: query
description: ID of Followup, or Custom Action.
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
- name: recall
in: query
description: ID of Recall
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
- name: referral
in: query
description: ID of Referral
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
- name: messageFailure
in: query
description: ID of MessageFailure
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
- name: groups
in: query
description: An _id or array of _ids separated by comma. Filters by message.facility within the facilities from the specified groups
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
- $ref: '#/components/parameters/languageParam'
- $ref: '#/components/parameters/createdByParam'
- $ref: '#/components/parameters/updatedByParam'
- $ref: '#/components/parameters/createdAtParam'
- $ref: '#/components/parameters/updatedAtParam'
- $ref: '#/components/parameters/pageParam'
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/populateParam'
- $ref: '#/components/parameters/selectParam'
responses:
'200':
description: List of messages
content:
application/json:
schema:
type: object
required:
- response
- page
- size
properties:
response:
type: array
minItems: 0
items:
$ref: '#/components/schemas/MessageResponse'
page:
type: integer
format: int32
minimum: 1
size:
type: integer
format: int32
minimum: 0
additionalProperties: false
'401':
description: Not authenticated
'403':
description: Access token does not have the required scope
post:
summary: Create message
operationId: messageCreate
tags:
- messages
requestBody:
description: Optional description in *Markdown*
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MessageRequest'
responses:
'201':
description: Successful creation
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
'401':
description: Not authenticated
'403':
description: Access token does not have the required scope
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/messages/{messageId}:
get:
summary: Get message by id
operationId: messageGet
tags:
- messages
parameters:
- name: messageId
in: path
required: true
description: Messages' unique identifier in Luma's database.
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
responses:
'200':
description: Message
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResponse'
put:
summary: Update message visibility
operationId: messageUpdateVisibility
tags:
- messages
parameters:
- name: messageId
in: path
required: true
description: Messages' unique identifier in Luma's database.
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
- name: markMessageAs
in: query
description: '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/>
'
schema:
type: string
default: public
enum:
- public
- private
- internal
requestBody:
description: The message visibility status
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/MessagesUpdateVisibilityRequest'
responses:
'200':
description: Success updating message visibility
content:
application/json:
schema:
type: object
required:
- message
properties:
body:
type: object
properties:
message:
type: string
additionalProperties: false
'400':
description: Bad params or the address are invalid
content:
application/json:
schema:
type: object
required:
- message
properties:
error:
type: object
properties:
message:
type: string
additionalProperties: false
'500':
description: An unexpected error occurred
content:
application/json:
schema:
type: object
required:
- message
properties:
error:
type: object
properties:
message:
type: string
additionalProperties: false
components:
parameters:
pageParam:
in: query
name: page
required: false
type: integer
format: int32
default: 1
minimum: 1
schema:
type: integer
format: int32
default: 1
minimum: 1
createdAtParam:
in: query
name: createdAt
type: string
format: date-time
schema:
type: string
format: date-time
required: false
description: The date/time when this object was created.
updatedAtParam:
in: query
name: updatedAt
type: string
format: date-time
schema:
type: string
format: date-time
required: false
description: The date/time when this object was updated.
updatedByParam:
in: query
name: updatedBy
required: false
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
description: The ID of the user who updated this object.
languageParam:
in: query
name: language
type: string
schema:
type: string
enum:
- 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
description: Language code.
createdByParam:
in: query
name: createdBy
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
required: false
description: The ID of the user who created this object.
populateParam:
name: _populate
in: query
description: Response properties which will be replaced by the referenced objects, separated by commas.
required: false
type: string
schema:
type: string
selectParam:
name: _select
in: query
description: Response properties that should be returned, separated by commas.
required: false
type: string
schema:
type: string
limitParam:
name: limit
in: query
description: How many items to fetch per page
required: false
type: integer
format: int32
default: 500
minimum: 1
maximum: 1000
schema:
type: integer
format: int32
default: 500
minimum: 1
maximum: 1000
schemas:
userParam:
in: query
name: user
required: false
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
description: The ID of the root account user.
Error:
type: object
required:
- code
- message
properties:
code:
type: integer
format: int32
message:
type: string
idParam:
in: query
name: _id
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
required: false
schema:
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
description: Luma's internal ID of an object.
MessageRequest:
type: object
required:
- patient
- type
- ref
- channel
- text
- secure
properties:
patient:
description: The ID of the patient linked to this message.
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
key:
description: '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.
'
type: string
enum:
- chatRequest
- chatRequestInsecure
type:
description: Indicates if a message was sent from Luma to an external person, or the other way around.
type: string
enum:
- inbound
- outbound
voiceAnsweredBy:
description: voiceAnsweredBy
type: string
enum:
- human
- fax
- unknown
- machine-start
- machine-end-beep
- machine-end-silence
- machine-end-other
ref:
description: 'On our RESTful API, you can only create messages with ref `chat`, but you may see these other refs when fetching messages.
Indicates what this message is about. Depending on this value, you also know what the parameter `refId` refers to.<br/>
- chat (`refId` will be the ID of a `ChatActivity`)<br/>
'
type: string
enum:
- chat
refId:
description: The ID of the object referenced by the `ref` parameter.
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
patientMessageTemplate:
description: The ID of a Hub Message Template (or `PatientMessageTemplate`). These are custom messages, created by users, to make their typing experience easier.
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
language:
$ref: '#/components/schemas/Language'
channel:
description: "description: |\nThe channel used to send this message.<br/>\nOn our RESTful API, you may search for multiple channels, but only POST `chat` messages.<br/>\nCheck the response format to see other possible channels.<br/>\nTwo of them deserve an explanation:<br/>\n- `chat` will check the recipient's contact and pick the channel automatically.<br/>\n- `inapp` are meant for internal messages, when a staff user `@mentions` another staff user on Hub.\nThe mentioned person only gets a notification on their browser window, \nby fetching from the `notifications` API.\n"
type: string
enum:
- chat
notifyTo:
description: Messages with channel=chat may specify in this field where the message notification must be sent.
type: array
items:
type: object
required:
- channel
properties:
channel:
description: channel
type: string
enum:
- sms
- email
- voice
- inapp
- chat
- fax
- whatsapp
to:
description: to
type: string
shouldForceContactWithNotifyTo:
description: '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.
'
type: boolean
text:
description: 'The content of the message.<br/>
On our RESTful API, you can only POST messages with channel `chat`,
and you must provide a `text`.<br/>
Just as an information for when fetching messages (not creating them),
all the other channels determine the `text` automatically, based on the `key`.
The key is the name of a messageTemplate, which is fetched then parsed (for squigglies)
to generate the final `text` automatically.
'
type: string
externalId:
$ref: '#/components/schemas/ExternalId'
secure:
description: '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.
'
type: boolean
automated:
description: Indicates if a message was created by users (chat) or by the system (reminders, recalls, etc).
type: boolean
default: true
visibility:
description: '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/>
'
type: string
default: public
enum:
- public
- private
- internal
file:
description: 'The ID of a `FileUpload`, in case this message has any attachment,
sent via the `FileUpload` RESTful API.
'
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
media:
description: Any recorded media (voice recording, fax image, etc) that represents this message. URL should be the location from which to retreive it
type: object
properties:
url:
type: string
contentType:
type: string
mentions:
description: Array of IDs of either users or groups that have been `@mentioned` inside messages, usually messages with visibility `internal`.
type: array
items:
type: object
properties:
ref:
description: Describes if the `@mention` refers to a `User` ID or a `Group` ID. Determines the meaning of the `refId` field.
type: string
enum:
- user
- group
refId:
description: The ID of either a user or a group that was @mentioned, based on the `ref` value.
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
mention:
description: Literally the string `@SomeOnesName` or `@GroupName` that was used.
type: string
recipient:
description: The ID of the User receiving the message. Usually, for messages `type outbound`, the recipient is the ID of a patient.
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
recipientType:
description: The type of the user in the field `recipient`
type: string
enum:
- doctor
- staff
- patient
appointment:
description: ID of Appointment
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
provider:
description: ID of Provider
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
appointmentType:
description: ID of AppointmentType
type: string
pattern: '[0-9a-f]'
minLength: 24
maxLength: 24
followup:
description: ID of Followup o
# --- truncated at 32 KB (53 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/luma-health/refs/heads/main/openapi/luma-health-messages-api-openapi.yml