Conversation Token

This token represents a group conversation (group chat) between multiple participants.

The conversation token must contain a content (c) field with conversation metadata. For other constraints see the Action Tokens.

Note: For 1-to-1 direct messaging, see Message Token (MSG). CONV is for group conversations with multiple participants.

Content-Addressing

This token is content-addressed using SHA-256:

The entire JWT token (header + payload + signature) is hashed
Action ID format: a1~{base64_hash}
See Content-Addressing & Merkle Trees for details

Immutability: Once created, a CONV token cannot be modified without changing its action ID.

Content Structure

The content (c) field must be a JSON object with the following structure:

{
  "name": "Project Discussion",
  "description": "Weekly sync about the project"
}

Property	Type	Required	Description
name	string	Yes	Display name for the conversation
description	string	No	Optional description of the conversation purpose

Flags

CONV tokens use the flags (f) field to control conversation behavior:

Flag	Default	Description
R/r	r (disabled)	Reactions allowed on the conversation itself
C/c	c (disabled)	Comments allowed on the conversation itself
O/o	o (closed)	Open (anyone can join) vs Closed (invite-only)

Default flags: rco (no reactions, no comments, closed/invite-only)

To create an open conversation that anyone can join, use flags O.

Subtypes

Subtype	Description
CONV	Create a new conversation
CONV:UPD	Update conversation metadata (name, description, flags)
CONV:DEL	Delete/archive the conversation

Subscribable Behavior

CONV is a subscribable action type, meaning:

Users can subscribe to receive messages in the conversation
Subscription is managed via SUBS tokens
Users can be invited via INVT tokens
Messages sent to the conversation (MSG with parent=CONV) are delivered to all subscribers

Auto-Subscription

When a CONV is created, the creator is automatically subscribed as an admin:

CONV token is created and signed
System automatically creates a SUBS token for the creator
Creator’s SUBS has role = “admin”

Participant Roles

Conversation participants can have different roles, managed via SUBS tokens:

Role	Permissions
observer	Can read messages, cannot send
member	Can read and send messages
moderator	Can read, send, and invite/remove members
admin	Full control including conversation settings

Federation

Creating a Conversation

Creator creates CONV token
         │
         ▼
┌─────────────────────────────┐
│ ActionCreatorTask runs      │
│ - Signs CONV token          │
│ - Creates admin SUBS        │
└───────────┬─────────────────┘
            │
            ▼
    CONV ready for messages

Adding Participants

Participants join via invitation or (for open conversations) self-subscription:

Admin creates INVT for new participant
         │
         ▼
INVT delivered to invitee (includes CONV token)
         │
         ▼
Invitee creates SUBS token to accept
         │
         ▼
SUBS auto-accepted (INVT exists)
         │
         ▼
Participant now receives MSG in conversation

Message Fan-Out

When a message is sent to a conversation:

Local CONV: If the CONV owner sends/receives a message, they fan it out to all subscribers
Remote CONV: If a subscriber sends a message, it goes to the CONV owner who fans it out

See Subscriber Fan-Out for detailed federation flow.

Example

Field	Value
iss	alice.cloudillo.net
aud
iat	2024-04-13T00:00:00.000Z
k	20240109
t	CONV
c	{“name”: “Project Team”, “description”: “Discussion for project X”}
f	rco

Conversation Flow Example

CONV: @alice.cloudillo.net creates "Project Team"
  │
  ├─ SUBS: @alice.cloudillo.net (auto-created, role=admin)
  │
  ├─ INVT: @alice.cloudillo.net → @bob.cloudillo.net
  │   └─ SUBS: @bob.cloudillo.net (accepts invitation, role=member)
  │
  ├─ INVT: @alice.cloudillo.net → @charlie.cloudillo.net
  │   └─ SUBS: @charlie.cloudillo.net (accepts invitation, role=member)
  │
  ├─ MSG: @alice.cloudillo.net "Hi everyone!"
  │   └─ Fan-out to bob, charlie
  │
  ├─ MSG: @bob.cloudillo.net "Hello!"
  │   ├─ REACT:LIKE @alice.cloudillo.net
  │   └─ Fan-out to alice, charlie
  │
  └─ SUBS:DEL: @charlie.cloudillo.net (leaves conversation)