Message Token

This token represents a direct message sent from one profile to another.

A message token enables private, one-on-one communication between users. Unlike posts (which are broadcast to followers), messages are sent directly to a specific recipient and are not federated to other instances.

The token must contain an audience (aud) field pointing to the recipient of the message. For other constraints see the Action Tokens.

Content-Addressing

This token is content-addressed using SHA-256:

Attachments

The a (attachments) field can contain file references:

  • Each entry is a file_id (f1~...)
  • File IDs are content-addressed (SHA256 of file descriptor)
  • Files contain multiple variants (different resolutions)
  • See File Storage for details

Parent Reference

The optional p (parent) field enables message threading:

  • Contains the parent message’s action_id (a1~...)
  • Creates conversation threads and reply chains
  • Parent must exist and be verified

Database Key

The database key for a message token is [iss, t, id]

Purpose: Each message has a unique ID, allowing multiple messages in a conversation thread. The key includes the action ID itself, so messages are never overridden.

Message Example

{
  "iss": "alice.example.com",
  "aud": "bob.example.com",
  "iat": 1738483200,
  "k": "20240101",
  "t": "MSG",
  "c": "Hey Bob, want to grab coffee tomorrow?",
  "a": ["f1~abc123..."],
  "p": "a1~xyz789..."
}

All fields shown; in practice a (attachments) and p (parent/reply) are optional. The structure is the same regardless of whether the message is a simple text, has attachments, or is a reply – only the presence of optional fields differs.

Fields

Field Required Description
iss ✓ The identity sending the message
aud ✓ The identity receiving the message
iat ✓ Timestamp when message was sent
k ✓ Key ID used to sign the token
t ✓ Token type (always “MSG”)
c ✓ Message content (markdown)
p Parent message ID (for threading/replies)
a Attachments (files, images, etc.)
exp Optional expiration (for disappearing messages)

Visibility and Federation

Message tokens are direct actions, meaning they are:

  • Sent only to the specified audience (recipient)
  • NOT broadcast to followers
  • Private between sender and recipient
  • Delivered to POST https://cl-o.{recipient}/api/inbox

Federation Flow

When Alice sends a message to Bob:

  1. Alice’s instance creates a MSG token with aud: bob.example.com
  2. The token is signed by Alice’s private key
  3. The message is sent to https://cl-o.bob.example.com/api/inbox
  4. Bob’s instance verifies the signature
  5. Bob’s instance stores the message for Bob to read
  6. Bob receives a notification (via WebSocket bus or push notification)

Permission Checks

When receiving a message token:

  1. Verify signature: Ensure the token is signed by the claimed issuer
  2. Check audience: Verify aud field matches the local user
  3. Check relationship: Verify sender is connected or followed (configurable)
  4. Spam prevention: Check sender is not blocked
  5. Rate limiting: Enforce message rate limits per sender

Message Delivery

Messages use a different delivery mechanism than broadcast actions:

Aspect Broadcast Actions (POST) Direct Messages (MSG)
Delivery To all followers To specific recipient only
Federation Sent to multiple instances Sent to one instance
Storage Stored publicly (with permissions) Stored privately
Visibility Timeline/feed Message inbox
Retry Best-effort Reliable delivery with retry

Message Threading

Messages can be threaded using the parent (p) field:

Message 1 (no parent)
  ├─ Reply 1 (p: Message 1)
  ├─ Reply 2 (p: Message 1)
  │   └─ Reply 3 (p: Reply 2)
  └─ Reply 4 (p: Message 1)

Message Storage

Messages are stored in MetaAdapter with:

  • Sender and recipient identity tags
  • Read/unread status
  • Delivery status
  • Optional expiration timestamp

Privacy considerations:

  • Messages stored locally at sender and recipient instances
  • Not replicated to other instances
  • Can be deleted by either party
  • Retention policies configurable per user

See Also