Presence Token

The PRES token represents an ephemeral presence indication, such as typing status or online presence. Unlike other action types, presence tokens are not persisted – they are forwarded via WebSocket in real-time only, with no action_id generated and no delivery retry logic. They have a default TTL of 30 seconds.

The presence token must contain a subject (sub) field referencing the context (e.g., a conversation). For other constraints see the Action Tokens.

Fields

Field	Required	Description
iss	Yes	The user’s identity
sub	Yes	Context (e.g., CONV action_id)
aud	Optional	Specific target user (if omitted, broadcast to context)
t	Yes	“PRES:TYPING”, “PRES:ONLINE”, etc.
c	Optional	Additional metadata
a	Forbidden	Attachments are not allowed

Subtypes

Subtype	Description
PRES:TYPING	User is currently typing
PRES:ONLINE	User is online/active
PRES:AWAY	User is away/idle
PRES:OFFLINE	User has gone offline

Additional subtypes can be defined for application-specific presence states.

Subject Reference

The sub (subject) field specifies the context for the presence update (e.g., a CONV action_id for typing indicators, or a profile context for online status). Unlike the parent field used by comments, sub expresses a non-hierarchical contextual reference.

Processing Flow

When a PRES token is received, the server verifies the signature, skips database storage, and immediately forwards it via WebSocket to the audience (single user if aud is set, otherwise all context subscribers).

For cross-instance presence, the token is forwarded via HTTP POST to the context owner’s instance, which then broadcasts to its local subscribers.

Time-To-Live (TTL)

PRES tokens have an implicit 30-second TTL. Clients should send periodic updates to maintain presence (e.g., PRES:TYPING every 5 seconds while typing). After the TTL expires without a new update, recipients consider the presence stale.

Example

User @alice.cloudillo.net is typing in a conversation:

Field	Value
iss	alice.cloudillo.net
sub	a1~NAado5PS4j5+abYtRpBELU0e5OQ+zGf/tuuWvUwQ6PA=
iat	2024-04-13T00:01:10.000Z
k	20240301
t	PRES:TYPING

Security Considerations

Since PRES tokens are ephemeral, they still require valid signature verification, rate limiting applies to prevent spam, and the user must have access to the referenced context.

Comparison with Persistent Actions

Aspect	PRES (Ephemeral)	Other Actions
Database storage	No	Yes
Action ID	None	SHA256 hash
Delivery tasks	None	Scheduled with retry
TTL	30 seconds	Permanent (until deleted)
Use case	Real-time status	Permanent records