Communication

Overview

The messaging system uses CareTeam-based rooms rather than 1:1 messaging. Each conversation is identified by:

careteam:{care_team_id}:patient:{patient_id}

All CareTeam participants can see and send messages in the room.

Patient ──► CarePlan ──► CareTeam ──► Practitioners (multiple)
                              │
                              ▼
                         Message Room

List Conversations

GET /communication/conversations

Returns all conversations for the authenticated user with unread counts.

Response

[
  {
    "room_id": "careteam:team-001:patient:patient-001",
    "patient": { "id": "patient-001", "name": "Jan Novak" },
    "care_team": { "id": "team-001", "name": "Primary Care Team" },
    "last_message": {
      "content": "Please take your medication",
      "sent_at": "2026-03-03T10:30:00Z",
      "sender": "Practitioner/ZCT_doctor_001"
    },
    "unread_count": 2
  }
]

Get Messages

GET /communication/messages?room_id={roomId}&_count={limit}&_offset={offset}

Parameters

Parameter	Type	Description
`room_id`	string	Room identifier
`_count`	number	Page size
`_offset`	number	Pagination offset

Send Message

POST /communication/messages
Content-Type: application/json

{
  "room_id": "careteam:team-001:patient:patient-001",
  "content": "Your lab results look normal. Continue current treatment.",
  "message_type": "text",
  "sender_resource_id": "ZCT_doctor_001"
}

Message Types

Type	Description
`text`	Plain text message
`medication_request`	Medication-related request
`medication_response`	Response to medication request
`system_notification`	System-generated notification
`template`	Message from a template

Mark Messages as Read

POST /communication/messages/mark-read
Content-Type: application/json

{
  "room_id": "careteam:team-001:patient:patient-001",
  "reader_resource_id": "ZCT_doctor_001"
}

Message Templates

List Templates

GET /communication/templates

Create Template

POST /communication/templates
Content-Type: application/json

{
  "name": "Appointment Reminder",
  "content": "Reminder: You have an appointment on {date} at {time}.",
  "category": "scheduling"
}

Patient Groups

List Groups

GET /communication/groups

Bulk Message

Send a message to a group of patients:

POST /communication/bulk-message
Content-Type: application/json

{
  "group_id": "group-uuid",
  "content": "The clinic will be closed on Monday.",
  "message_type": "system_notification"
}

CareTeam Lookup

Endpoint	Description
`GET /communication/patient-care-teams?patient={id}`	Care teams for a patient
`GET /communication/care-team-patients?care_team={id}`	Patients in a care team
`GET /communication/default-team?patient={id}`	Default care team for a patient
`GET /communication/check-team-membership?care_team={id}`	Check if current user is a member

Real-time

Messages are delivered in real-time via Supabase Realtime. The frontend subscribes to the communication.messages table for the current user's rooms.

Database Tables

Table	Description
`communication.messages`	Message storage with real-time triggers
`communication.message_read_status`	Per-user read tracking
`communication.message_templates`	Reusable templates
`communication.patient_groups`	Patient groups for bulk messaging
`communication.patient_group_members`	Group membership