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 and get notified when new messages come in
Observers: Who only have read access to the message thread and do not get notified when new messages come in

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 "patientCareTeam" thread between them and the care team when the patient is created. Each caregiver automatically has a "caregiverCareTeam" 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:
patientCareTeam
caregiverCareTeam
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 "patientCareTeam" or "caregiverCareTeam". Patient this message thread is about.
Name
caregiver
Type
string
Description
Only applies if the type of the thread is "caregiverCareTeam". Caregiver this message thread is about.
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
messages
Type
array of strings
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 strings
Description
Tags associated with the message thread.
Name
created_by
Type
string
Description
Creator of 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
number
Description
Timestamp (in ISO 8601 format) of when the message thread was created.
Name
last_message_at
Type
number
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": "patientCareTeam",
  "name": "Sally Chen & Care Team",
  "patient": "user_Z1zXZKvqrpwxbznuW6lJ",
  "caregiver": null,
  "participants": [
    "user_IsW3SoxZQxW0agHKyP2V",
  ],
  "observers": [
      "user_o14kEdLdUloOyS4RGkII",
  ],
  "messages": ["msg_Akeb8izH7pbIFi61gaSC", "msg_pCIB5UiIfIoZt25PqKux"],
  "read_by": ["user_Z1zXZKvqrpwxbznuW6lJ", "user_IsW3SoxZQxW0agHKyP2V"],
  "priority": "low",
  "tags": ["tag_Z1zXZKvqrpwxbznuW6lJ"],
  "statusHistory": [
    {
      "status": "active",
      "changed_by": "automationBot",
      "changed_at": 1653798303000,
    },
  ],
  "created_by": "automationBot",
  "created_at": 1653798303000,
  "last_message_at": 1653798303000,
}

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.
Name
created_by
Type
string
Description
Creator 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 strings
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": "other",
    "name": "Sally Chen, Teddy Smith",
    "participants": [
      "user_IsW3SoxZQxW0agHKyP2V",
    ],
    "observers": [
        "user_o14kEdLdUloOyS4RGkII",
    ],
    "messages": ["msg_Akeb8izH7pbIFi61gaSC", "msg_pCIB5UiIfIoZt25PqKux"],
    "read_by": ["user_Z1zXZKvqrpwxbznuW6lJ", "user_IsW3SoxZQxW0agHKyP2V"],
    "priority": "low",
    "tags": ["tag_Z1zXZKvqrpwxbznuW6lJ"],
    "statusHistory": [
      {
        "status": "active",
        "changed_by": "automationBot",
        "changed_at": 1653798303000,
      },
    ],
    "created_by": "automationBot",
    "created_at": 1653798303000,
    "last_message_at": 1653798303000,
}

GET/v2/message_threads/:id

Retrieve a message thread

Retrieves the specified message thread.

Response

{
 "id": "thrd_kkF8SgJmcgaTmmziHoCv",
 "object": "message_thread",
 "type": "patientCareTeam",
 "name": "Sally Chen & Care Team",
 "patient": "user_Z1zXZKvqrpwxbznuW6lJ",
 "participants": [
   "user_IsW3SoxZQxW0agHKyP2V",
 ],
 "observers": [
     "user_o14kEdLdUloOyS4RGkII",
 ],
 "messages": ["msg_Akeb8izH7pbIFi61gaSC", "msg_pCIB5UiIfIoZt25PqKux"],
 "read_by": ["user_Z1zXZKvqrpwxbznuW6lJ", "user_IsW3SoxZQxW0agHKyP2V"],
 "priority": "low",
 "tags": ["tag_Z1zXZKvqrpwxbznuW6lJ"],
 "statusHistory": [
   {
     "status": "active",
     "changed_by": "automationBot",
     "changed_at": 1653798303000,
   },
 ],
 "created_by": "automationBot",
 "created_at": 1653798303000,
 "last_message_at": 1653798303000,
}

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

Name
updated_by
Type
string
Description
Updates to the message thread made by.

Optional attributes

Name
name
Type
string
Description
Name of the message thread.
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
messages
Type
array of strings
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 strings
Description
Tags associated with the message thread.
Name
status
Type
string
Description
Status of the message thread.
Possible values:
active
completed

Response

{
  "id": "thrd_kkF8SgJmcgaTmmziHoCv",
  "object": "message_thread",
  "type": "patientCareTeam",
  "name": "Sally Chen & Care Team",
  "patient": "user_Z1zXZKvqrpwxbznuW6lJ",
  "participants": [
    "user_IsW3SoxZQxW0agHKyP2V",
  ],
  "observers": [
      "user_o14kEdLdUloOyS4RGkII",
  ],
  "messages": ["msg_Akeb8izH7pbIFi61gaSC", "msg_pCIB5UiIfIoZt25PqKux"],
  "read_by": ["user_Z1zXZKvqrpwxbznuW6lJ", "user_IsW3SoxZQxW0agHKyP2V"],
  "priority": "low",
  "tags": ["tag_Z1zXZKvqrpwxbznuW6lJ"],
  "statusHistory": [
    {
      "status": "active",
      "changed_by": "automationBot",
      "changed_at": 1653798303000,
    },
    {
      "status": "completed",
      "changed_by": "user_IsW3SoxZQxW0agHKyP2V",
      "changed_at": 1713798303000,
    },
  ],
  "created_by": "automationBot",
  "created_at": 1653798303000,
  "last_message_at": 1653798303000,
}

GET/v2/message_threads

List all message threads

Returns a list of all message threads.

Response

  {
    "object": "list",
    "data": [
    {
      "id": "thrd_kkF8SgJmcgaTmmziHoCv",
      "object": "message_thread",
      "type": "patientCareTeam",
      "name": "Sally Chen & Care Team",
      "patient": "user_Z1zXZKvqrpwxbznuW6lJ",
      "participants": [
        "user_IsW3SoxZQxW0agHKyP2V",
      ],
      "observers": [
          "user_o14kEdLdUloOyS4RGkII",
      ],
      "messages": ["msg_Akeb8izH7pbIFi61gaSC", "msg_pCIB5UiIfIoZt25PqKux"],
      "read_by": ["user_Z1zXZKvqrpwxbznuW6lJ", "user_IsW3SoxZQxW0agHKyP2V"],
      "priority": "low",
      "tags": ["tag_Z1zXZKvqrpwxbznuW6lJ"],
      "statusHistory": [
        {
          "status": "active",
          "changed_by": "automationBot",
          "changed_at": 1653798303000,
        },
      ],
      "created_by": "automationBot",
      "created_at": 1653798303000,
      "last_message_at": 1653798303000,
    },
  ]
}