Message Thread
With our message threads, you can allow:
- Patients to message their care team and vice versa
- Organization members to chat with groups of patients
- Organization members to chat internally with other organization members
Each message thread has two types of members:
- Participants: Who have read and write access to the message thread
- Observers: Who only have read access to the message thread
The purpose behind splitting members into participants and observers is that you can create automations that only notify e.g. participants about new messages sent to the thread, without pinging the observers as well.
The message thread model
- Name
id
- Type
- string
- Description
Unique identifier for the message thread.
- Name
object
- Type
- string
- Description
Always 'message_thread'.
- Name
type
- Type
- string
- Description
Type of message thread. Each patient automatically has a "patient_care_team" thread between them and the care team when the patient is created. Each caregiver automatically has a "caregiver_care_team" thread between them and the care team of the patient they are caregiver for when the caregiver is created. All other message threads are of type "other". Only message threads of type "other" can be created via the API — the rest are created automatically.
patient_care_team
caregiver_care_team
other
Possible values:- Name
name
- Type
- string
- Description
Name of the message thread.
- Name
patient
- Type
- string
- Description
Only applies if the type of the thread is "patient_care_team" or "caregiver_care_team". Patient this message thread is about.
- Name
caregiver
- Type
- string
- Description
Only applies if the type of the thread is "caregiver_care_team". Caregiver this message thread is about.
- Name
participants
- Type
- array of strings
- Description
Users who have read and write access to the message thread.
- Name
observers
- Type
- array of strings
- Description
Users who only have read access to the message thread.
- Name
messages
- Type
- array of objects
- Description
List of messages in the message thread.
- Name
read_by
- Type
- array of strings
- Description
List of users who have read the latest message in the thread.
- Name
priority
- Type
- string
- Description
Priority level of the message thread.
low
medium
high
Possible values:- Name
tags
- Type
- array of objects
- Description
Tags associated with the message thread.
- Name
status_history
- Type
- array of objects
- Description
- Status history of the message thread.
- Name
created_by
- Type
- string
- Description
Creator of the message thread.
- Name
created_at
- Type
- date-time
- Description
Timestamp (in ISO 8601 format) of when the message thread was created.
- Name
last_message_at
- Type
- date-time
- Description
Timestamp (in ISO 8601 format) of when the last message in the message thread was sent.
Response
{
"id": "thrd_kkF8SgJmcgaTmmziHoCv",
"object": "message_thread",
"type": "patient_care_team",
"name": "Sally Chen & Care Team",
"patient": "user_Z1zXZKvqrpwxbznuW6lJ",
"caregiver": null,
"participants": [
"user_IsW3SoxZQxW0agHKyP2V",
],
"observers": [
"user_o14kEdLdUloOyS4RGkII",
],
"messages": [{
"id": "msg_Akeb8izH7pbIFi61gaSC",
"object": "in_app_message",
"type": "text",
"message_thread": "thrd_kkF8SgJmcgaTmmziHoCv",
"mode": "text",
"text": "Need a prescription refill.",
"created_by": "user_IsW3SoxZQxW0agHKyP2V",
"created_at": "2024-05-07T22:16:46.391Z",
}],
"read_by": ["user_Z1zXZKvqrpwxbznuW6lJ", "user_IsW3SoxZQxW0agHKyP2V"],
"priority": "low",
"tags": [{
"id": "tag_vqrpwxbZ1zXZKznuW6lJ",
"object": "tag",
"name": "Refills",
}],
"status_history": [
{
"status": "active",
"changed_by": "automationBot",
"changed_at": 1653798303000,
},
],
"created_by": "automationBot",
"created_at": "2024-05-06T22:16:46.391Z",
"last_message_at": "2024-05-07T22:16:46.391Z",
}
Create a message thread
Creates a new message thread.
Required attributes
- Name
name
- Type
- string
- Description
Name of the message thread.
Optional attributes
- Name
participants
- Type
- array of strings
- Description
Users who have read and write access to the message thread and get notified when new messages come in
- Name
observers
- Type
- array of strings
- Description
Users who only have read access to the message thread and do not get notified when new messages come in.
- Name
read_by
- Type
- array of strings
- Description
List of users who have read the latest message in the thread.
- Name
priority
- Type
- string
- Description
Priority level of the message thread. By default, the priority level is set to 'low'.
low
medium
high
Possible values:- Name
tags
- Type
- array of objects
- Description
Tags associated with the message thread.
- Name
status
- Type
- string
- Description
Status of the message thread. By default, the status is set to 'active'.
active
completed
Possible values:
Response
{
"id": "thrd_kkF8SgJmcgaTmmziHoCv",
"object": "message_thread",
"type": "patient_care_team",
"name": "Sally Chen & Care Team",
"patient": "user_Z1zXZKvqrpwxbznuW6lJ",
"caregiver": null,
"participants": [
"user_IsW3SoxZQxW0agHKyP2V",
],
"observers": [
"user_o14kEdLdUloOyS4RGkII",
],
"messages": [{
"id": "msg_Akeb8izH7pbIFi61gaSC",
"object": "in_app_message",
"type": "text",
"message_thread": "thrd_kkF8SgJmcgaTmmziHoCv",
"mode": "text",
"text": "Need a prescription refill.",
"created_by": "user_IsW3SoxZQxW0agHKyP2V",
"created_at": "2024-05-07T22:16:46.391Z",
}],
"read_by": ["user_Z1zXZKvqrpwxbznuW6lJ", "user_IsW3SoxZQxW0agHKyP2V"],
"priority": "low",
"tags": [{
"id": "tag_vqrpwxbZ1zXZKznuW6lJ",
"object": "tag",
"name": "Refills",
}],
"status_history": [
{
"status": "active",
"changed_by": "automationBot",
"changed_at": 1653798303000,
},
],
"created_by": "automationBot",
"created_at": "2024-05-06T22:16:46.391Z",
"last_message_at": "2024-05-07T22:16:46.391Z",
}
Retrieve a message thread
Retrieves the specified message thread.
Response
{
"id": "thrd_kkF8SgJmcgaTmmziHoCv",
"object": "message_thread",
"type": "patient_care_team",
"name": "Sally Chen & Care Team",
"patient": "user_Z1zXZKvqrpwxbznuW6lJ",
"caregiver": null,
"participants": [
"user_IsW3SoxZQxW0agHKyP2V",
],
"observers": [
"user_o14kEdLdUloOyS4RGkII",
],
"messages": [{
"id": "msg_Akeb8izH7pbIFi61gaSC",
"object": "in_app_message",
"type": "text",
"message_thread": "thrd_kkF8SgJmcgaTmmziHoCv",
"mode": "text",
"text": "Need a prescription refill.",
"created_by": "user_IsW3SoxZQxW0agHKyP2V",
"created_at": "2024-05-07T22:16:46.391Z",
}],
"read_by": ["user_Z1zXZKvqrpwxbznuW6lJ", "user_IsW3SoxZQxW0agHKyP2V"],
"priority": "low",
"tags": [{
"id": "tag_vqrpwxbZ1zXZKznuW6lJ",
"object": "tag",
"name": "Refills",
}],
"status_history": [
{
"status": "active",
"changed_by": "automationBot",
"changed_at": 1653798303000,
},
],
"created_by": "automationBot",
"created_at": "2024-05-06T22:16:46.391Z",
"last_message_at": "2024-05-07T22:16:46.391Z",
}
Update a message thread
Updates the specified message thread object by setting the values of the parameters passed. Any other parameters not provided will not be modified.
Required attributes
Optional attributes
- Name
name
- Type
- string
- Description
Name of the message thread.
- Name
new_participants
- Type
- array of strings
- Description
New users to add to the participants list. If this user is already in the observers list, they will be removed from the observers list.
- Name
participants
- Type
- array of strings
- Description
Replace the current set of participants with this new set of participants.
- Name
new_observers
- Type
- array of strings
- Description
New users to add to the observers list. If this user is already in the participants list, they will be removed from the participants list.
- Name
observers
- Type
- array of strings
- Description
Replace the current set of observers with this new set of observers.
- Name
removed_members
- Type
- array of strings
- Description
Users to remove from the participants and/or observers list.
- Name
read_by
- Type
- array of strings
- Description
List of users who have read the latest message in the thread.
- Name
priority
- Type
- string
- Description
Priority level of the message thread.
low
medium
high
Possible values:- Name
tags
- Type
- array of strings
- Description
Tags associated with the message thread.
- Name
status
- Type
- string
- Description
New status of the message thread.
active
completed
Possible values:
Response
{
"id": "thrd_kkF8SgJmcgaTmmziHoCv",
"object": "message_thread",
"type": "patient_care_team",
"name": "Sally Chen & Care Team",
"patient": "user_Z1zXZKvqrpwxbznuW6lJ",
"caregiver": null,
"participants": [
"user_IsW3SoxZQxW0agHKyP2V",
],
"observers": [
"user_o14kEdLdUloOyS4RGkII",
],
"messages": [{
"id": "msg_Akeb8izH7pbIFi61gaSC",
"object": "in_app_message",
"type": "text",
"message_thread": "thrd_kkF8SgJmcgaTmmziHoCv",
"mode": "text",
"text": "Need a prescription refill.",
"created_by": "user_IsW3SoxZQxW0agHKyP2V",
"created_at": "2024-05-07T22:16:46.391Z",
}],
"read_by": ["user_Z1zXZKvqrpwxbznuW6lJ", "user_IsW3SoxZQxW0agHKyP2V"],
"priority": "low",
"tags": [{
"id": "tag_vqrpwxbZ1zXZKznuW6lJ",
"object": "tag",
"name": "Refills",
}],
"status_history": [
{
"status": "active",
"changed_by": "automationBot",
"changed_at": 1653798303000,
},
],
"created_by": "automationBot",
"created_at": "2024-05-06T22:16:46.391Z",
"last_message_at": "2024-05-07T22:16:46.391Z",
}
List all message threads
Returns a list of all message threads. Pass attributes as query params to filter the list of message threads based on that criteria.
Optional query parameters
- Name
type
- Type
- string
- Description
All message threads of this type.
patient_care_team
caregiver_care_team
other
Possible values:- Name
patient
- Type
- string
- Description
All message threads of type 'patient_care_team' with this patient ID.
- Name
caregiver
- Type
- string
- Description
All message threads of type 'caregiver_care_team' with this caregiver ID.
- Name
member
- Type
- string
- Description
All message threads with this user ID as a participant or observer.
- Name
participants
- Type
- array of strings
- Description
All message threads with at least one these user IDs as participants.
- Name
observers
- Type
- array of strings
- Description
All message threads with at least one these user IDs as observers.
- Name
status
- Type
- string
- Description
All message threads with this as the latest status.
active
completed
Possible values:- Name
priority
- Type
- string
- Description
All message threads with this priority level.
low
medium
high
Possible values:- Name
tags
- Type
- array of objects
- Description
All message threads with at least one of these tags.
Request
curl https://{{base_subdomain}}.avonhealth.com/v2/message_threads?status=active \
-H "Authorization: Bearer {{token}}" \
-H "x-jwt: {{jwt}}"
Response
{
"object": "list",
"data": [
{
"id": "thrd_kkF8SgJmcgaTmmziHoCv",
"object": "message_thread",
"type": "patient_care_team",
"name": "Sally Chen & Care Team",
"patient": "user_Z1zXZKvqrpwxbznuW6lJ",
"caregiver": null,
"participants": [
"user_IsW3SoxZQxW0agHKyP2V",
],
"observers": [
"user_o14kEdLdUloOyS4RGkII",
],
"messages": [{
"id": "msg_Akeb8izH7pbIFi61gaSC",
"object": "in_app_message",
"type": "text",
"message_thread": "thrd_kkF8SgJmcgaTmmziHoCv",
"mode": "text",
"text": "Need a prescription refill.",
"created_by": "user_IsW3SoxZQxW0agHKyP2V",
"created_at": "2024-05-07T22:16:46.391Z",
}],
"read_by": ["user_Z1zXZKvqrpwxbznuW6lJ", "user_IsW3SoxZQxW0agHKyP2V"],
"priority": "low",
"tags": [{
"id": "tag_vqrpwxbZ1zXZKznuW6lJ",
"object": "tag",
"name": "Refills",
}],
"status_history": [
{
"status": "active",
"changed_by": "automationBot",
"changed_at": 1653798303000,
},
],
"created_by": "automationBot",
"created_at": "2024-05-06T22:16:46.391Z",
"last_message_at": "2024-05-07T22:16:46.391Z",
},
]
}