Messagey messaging

Messagey is the fictional primary-care messaging workspace beside GP Records and Document Inbox. Open Riverside Practice on the neighbourhood map and choose Messagey. It uses the same team world and patient directory as the other products.

Send a patient message

1. Select New message and find any synthetic patient by name or ID.
2. Enter a subject and message, or choose an editable practice template.
3. Choose SMS or email and whether to allow replies.
4. Select Queue message.
5. Open Delivery simulator and choose Deliver or Fail delivery.

Messages never leave the simulation. A queued message does not appear in the patient's app until it is delivered. Failed messages can be retried; the complete delivery history remains attached to the original message.

Reply from home

Open Messages at the patient's home, or follow the patient Messages link from a practice conversation. Choose the same patient, open a delivered conversation and send a reply. Replies appear in the practice inbox. A completed conversation or one-way message cannot accept replies. The practice can reopen a completed conversation.

Internal practice notes and assignments are not shown in the patient app. The patient selector lets hackathon teams role-play different synthetic people inside their own world.

Manage the inbox

Conversations can be assigned to a named clinician or team, supplemented with internal notes and marked done. Done holds completed conversations and offers a reopen action. Patient messages retain their original text and author when colleagues add subsequent messages.

Templates supports creating, editing and archiving reusable SMS and email text. Applying a template copies its content into an editable composer; changing a template does not rewrite previously sent messages.

Send messages through the API

Open the Messaging group in the API explorer. Authorize with your team key. Both practice and patient operations require gp scope and stay inside your team's world. The key lets participants role-play synthetic patients; selecting a patient is not an identity sign-in.

Use these operations:

Operation	Purpose
GET /api/sites/gp/messages	Read practice conversations, optionally filtered by patientId
POST /api/sites/gp/messages	Send as the practice or doctor, manage delivery, and configure patient scripts
GET /api/sites/patient/messages?patientId=SIM-000003	Read one patient's visible conversations
POST /api/sites/patient/messages	Start a patient conversation or reply as that patient
GET /api/messaging/reply-presets	Retrieve editable administrative reply scripts without authentication

List responses contain items, total, offset, limit, and now. The default page size is 100; the maximum limit is 500. Increase offset to retrieve further pages. Conversations retain storage order. Patient reads require patientId and exclude private notes, queued or failed outgoing messages, and script configuration.

Start as a patient

Post this request to /api/sites/patient/messages:

{
	"patientId": "SIM-000003",
	"command": {
		"kind": "patient_create",
		"subject": "Appointment request",
		"body": "Could I arrange an afternoon appointment?",
		"channel": "sms"
	}
}

The incoming conversation appears immediately in the practice inbox and patient app. Save the returned id and version.

Send as the practice or doctor

To start a practice conversation, post to /api/sites/gp/messages:

{
	"patientId": "SIM-000003",
	"command": {
		"kind": "create",
		"subject": "Appointment preference",
		"body": "Would a morning or afternoon appointment suit you?",
		"channel": "sms",
		"allowReply": true
	}
}

To send another message in an existing conversation, use command: {"kind": "send", "body": "Please confirm Tuesday.", "channel": "sms"} with top-level resourceId and expectedVersion. The message is queued. Copy the outgoing entry's id from data.entries, then send a delivery command with that entryId and status: "delivered".

Practice messages have direction outgoing; patient messages have direction incoming. The authenticated team remains the audit actor, so the API cannot forge another participant's identity.

Enable scripted patient replies

1. Retrieve /api/messaging/reply-presets. Choose appointment preference, acknowledgment, or collection availability. You can edit the returned text or supply your own synthetic administrative script.
2. Before delivering the practice message, post a script to /api/sites/gp/messages. Replace the conversation ID and version below with the latest returned values.

{
	"resourceId": "REPLACE_WITH_CONVERSATION_ID",
	"expectedVersion": 1,
	"command": {
		"kind": "configure_auto_reply",
		"steps": [
			{"body": "An afternoon appointment would suit me, thank you.", "delayMinutes": 2},
			{"body": "Tuesday works for me.", "delayMinutes": 1}
		]
	}
}

3. Use the new version to deliver the queued outgoing message:

{
	"resourceId": "REPLACE_WITH_CONVERSATION_ID",
	"expectedVersion": 2,
	"command": {
		"kind": "delivery",
		"entryId": "REPLACE_WITH_OUTGOING_ENTRY_ID",
		"status": "delivered"
	}
}

4. Post {"paused": true, "advanceMinutes": 2} to /api/clock.
5. Read the conversation again. The first scripted reply appears as an incoming message attributed to the synthetic patient. Use its updated version for further commands.

Each successfully delivered practice message consumes one script step. The second step waits for another outgoing message to be delivered; it does not follow the first reply automatically. A script accepts up to 20 steps, each delayed by 0 through 10,080 simulation minutes. A zero-minute step runs on the next clock advance, including an advance of zero. Pausing the clock pauses replies. Scripts and pending replies persist in the team's world.

Only open conversations with replies enabled accept a nonempty script. Failed delivery does not consume a step. Scripts stop when their steps run out. Multiple delivered messages can have separate pending replies. Each delay starts at that message's delivery, so shorter delays can produce replies before earlier scheduled ones.

To disable automation, send configure_auto_reply with steps: []. Replacing a script cancels pending replies, resets its sequence, and applies only to future deliveries. Manually replying as the patient or completing the conversation also cancels pending replies. Those reserved steps remain consumed, including after reopening. Private notes and assignments do not cancel replies. No model or external SMS/email provider generates these responses.

Reply manually as the patient

Post to /api/sites/patient/messages with the matching patientId, the conversation's resourceId and expectedVersion, and command: {"kind": "reply", "body": "Tuesday afternoon works for me."}. A reply requires an open conversation with replies enabled and a delivered practice message. The patient API rejects practice commands and a mismatched patient.

Retry and manage conversations

Send an Idempotency-Key header when retrying the same request. Reuse its original body. A changed body with the same key returns 409. Existing resources require the latest expectedVersion; stale updates also return 409. Scheduled replies change the version, so refresh before the next update.

The practice API also accepts note, assign, complete, reopen, retry, save_template, and archive_template. Their fields appear in the Explorer's PracticeMessageRequest schema. Templates remain in GET /api/sites/gp/messaging-workspace alongside conversations.

Existing integrations can continue posting type: "messaging_action" with messagingCommand to /api/sites/gp/actions or /api/sites/patient/actions. The same role restrictions, versions, scripts, and retry handling apply.