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.
Possible values:
patient_care_team
caregiver_care_team
other
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.
Possible values:
low
medium
high
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": "2024-04-03T04:12:01.781Z",
    },
  ],
  "created_by": "automationBot",
  "created_at": "2024-05-06T22:16:46.391Z",
  "last_message_at": "2024-05-07T22:16:46.391Z",
}

POST/v2/message_threads

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'.
Possible values:
low
medium
high
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'.
Possible values:
active
completed

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": "2024-04-03T04:12:01.781Z",
    },
  ],
  "created_by": "automationBot",
  "created_at": "2024-05-06T22:16:46.391Z",
  "last_message_at": "2024-05-07T22:16:46.391Z",
}

GET/v2/message_threads/:id

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": "2024-04-03T04:12:01.781Z",
   },
 ],
 "created_by": "automationBot",
 "created_at": "2024-05-06T22:16:46.391Z",
 "last_message_at": "2024-05-07T22:16:46.391Z",
}

POST/v2/message_threads/:id

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.
Possible values:
low
medium
high
Name
tags
Type
array of strings
Description
Tags associated with the message thread.
Name
status
Type
string
Description
New status of the message thread.
Possible values:
active
completed

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": "2024-04-03T04:12:01.781Z",
    },
  ],
  "created_by": "automationBot",
  "created_at": "2024-05-06T22:16:46.391Z",
  "last_message_at": "2024-05-07T22:16:46.391Z",
}

GET/v2/message_threads

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.
Possible values:
patient_care_team
caregiver_care_team
other
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.
Possible values:
active
completed
Name
priority
Type
string
Description
All message threads with this priority level.
Possible values:
low
medium
high
Name
tags
Type
array of objects
Description
All message threads with at least one of these tags.

Request

GET

/v2/message_threads

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": "2024-04-03T04:12:01.781Z",
          },
        ],
        "created_by": "automationBot",
        "created_at": "2024-05-06T22:16:46.391Z",
        "last_message_at": "2024-05-07T22:16:46.391Z",
    },
  ]
}