Contextual Messaging Overview

Entity-scoped, multi-party conversations with role-based visibility and lifecycle rules.

PlatformXe Contextual Messaging (internally called Threads) provides entity-bound, multi-party conversation threads for any business domain. Unlike generic chat APIs, every conversation is scoped to a business entity -- a booking, a service order, a claim, an appointment -- and inherits its participants, visibility rules, and lifecycle from that entity.

Why Contextual Messaging?

Challenge	Generic Chat SDKs	PlatformXe Contextual Messaging
Entity binding	You implement it	Native -- threads are created for an entity
Participant resolution	You implement it	Webhook -- your app resolves participants; PlatformXe caches
Role-based visibility	You implement it	Built-in -- per-message `visibility[]` field
Lifecycle rules	You implement it	Configurable -- auto-close on entity status change
System messages	You implement it	Event-driven -- entity events generate system messages
Multi-tenant	No	Native -- tenant isolation, per-tenant channel config

Core Concepts

Channels

A channel defines the shape of conversations for an entity type. Each channel specifies:

Entity type (e.g., BOOKING, SERVICE_ORDER, APPOINTMENT)
Participant roles (e.g., GUEST, HOST, PLATFORM)
Default visibility (who sees messages by default)
Lifecycle rules (when threads auto-close or archive)
Escalation rules (what happens when a message is flagged)

Threads

A thread is a single conversation tied to one entity. There is exactly one thread per entity per channel. Threads have a status (OPEN, CLOSED, ARCHIVED) and track message count, last activity, and metadata.

Participants

Each thread has N participants, each with a role and an external ID (the user's ID in your application). PlatformXe never authenticates end users -- your application resolves identity and passes the participant context.

Messages

Messages carry content, a sender, and a visibility array. Visibility determines which participant roles can see the message:

["ALL"] -- every participant sees it
["HOST", "PLATFORM"] -- only host and platform admin see it (private note)
["GUEST", "HOST"] -- direct guest-host conversation, platform excluded

Visibility is enforced server-side. Clients never receive messages outside their role scope.

Lifecycle

Channels define lifecycle rules that automatically manage thread state:

Auto-close on entity status change (e.g., CHECKED_OUT, CANCELLED, COMPLETED)
Auto-archive after a configurable period post-close
System messages generated on lifecycle events

Escalation

Conversations surface problems. The escalation framework bridges messages to formal issue tracking:

Flag reasons -- tenant-defined codes (SAFETY, DISPUTE, COMPLAINT, etc.)
Auto-detection -- keyword patterns that auto-flag messages without human action
Escalation rules -- JSON Logic conditions that evaluate flag context and trigger actions
Actions -- create issues, fire webhooks, post system messages, close threads
Cooldowns -- prevent duplicate escalations per thread per rule

PlatformXe provides the engine. You define the rules. A hospitality tenant configures SAFETY/DISPUTE/COMPLAINT. A healthcare tenant configures CLINICAL_CONCERN/MEDICATION_ERROR. PlatformXe evaluates the same engine -- it just does not know the difference.

See the Escalation Framework guide for full configuration details.

Authentication

All API calls use your tenant API key (x-api-key header). Your application calls PlatformXe from its backend, never from the browser directly. The calling app's frontend talks to its own API, which proxies to PlatformXe with the participant context.

Scopes

Scope	Access
`threads:read`	List/get threads, messages, read state, inbox, list flags
`threads:write`	Create/update threads, send messages, manage participants, flag messages
`threads:admin`	Channel CRUD, system messages, lifecycle management, escalation config, review flags

Rate Limits

Operation	Limit
Message send	1,000/hr per API key
Message list	5,000/hr per API key
Channel admin	100/hr per API key