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"
}

Flags

CONV tokens use the flags (f) field to control conversation behavior. Uppercase enables a capability, lowercase disables it:

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

To create an open conversation anyone can join, include O in the flags (e.g. rcO).

Subtypes

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 on_create hook automatically subscribes the creator as admin:

1. CONV token is created and signed
2. The system creates a self-issued SUBS for the creator (subject = CONV action_id)
3. That SUBS is given x.role: "admin" (server-side metadata)

Participant Roles

Conversation participants have roles (observer, member, moderator, admin) managed via SUBS tokens. See the Subscription Token roles table for detailed permissions.

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:

1. Local CONV: If the CONV owner sends/receives a message, they fan it out to all subscribers
2. 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

See Also

• Message Token - Messages within conversations
• Subscription Token - Managing conversation membership
• Invitation Token - Inviting users to conversations
• Federation Architecture - How messages are distributed