Message Token

This token represents a message — either a direct message to another user or a message within a conversation.

MSG serves two cases:

  • Direct message (DM): set aud to the recipient. Sent directly to that one recipient.
  • Conversation message: set p (parent) to the CONV action_id (or a parent MSG for replies). The message is fanned out to all conversation subscribers.

The content (c) field is required and holds the message text (markdown). 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 links the message into a conversation:

  • For a message in a conversation, p is the CONV action_id; for a reply, it is the parent MSG action_id (a1~...).
  • A MSG with a parent in a CONV requires the sender to have an active subscription (SUBS) to that conversation.
  • The parent must exist and be verified.

Message Example

A direct message to Bob:

{
  "iss": "alice.example.com",
  "k": "20240101",
  "t": "MSG",
  "aud": "bob.example.com",
  "c": "Hey Bob, want to grab coffee tomorrow?",
  "iat": 1738483200
}

For a conversation message, replace aud with p set to the CONV (or parent MSG) action_id. a (attachments) and exp (expiry, for disappearing messages) are optional in both cases.

Fields

Field Required Description
iss ✓ The identity sending the message
k ✓ Key ID used to sign the token
t ✓ Token type (“MSG” or “MSG:DEL”)
c ✓ Message content (markdown)
aud * Recipient (required for a DM)
p * Parent CONV or MSG action_id (required for a conversation message)
iat ✓ Timestamp when message was sent
a Attachments (file IDs)
exp Optional expiration (for disappearing messages)

aud and p are mutually defining: a DM uses aud, a conversation message uses p.

Delivery

  • DM (aud set): delivered directly to the recipient. Not broadcast to followers.
  • Conversation message (p in a CONV): delivered to all subscribers via subscriber fan-out — see Conversation Token. Requires the sender to hold an active SUBS to the conversation.

MSG triggers a push notification (subject to the recipient’s notify.push.message setting).

Threading

Replies set p to the parent message’s action_id:

Message 1 (p: CONV)
  ├─ Reply 1 (p: Message 1)
  └─ Reply 2 (p: Message 1)
      └─ Reply 3 (p: Reply 2)

See Also