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 Unix epoch time in milliseconds) of when the message thread was created.

  • Name
    last_message_at
    Type
    number
    Description

    Timestamp (in Unix epoch time in milliseconds) 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/v1/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/v1/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/v1/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/v1/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,
    },
  ]
}