> ## Documentation Index > Fetch the complete documentation index at: https://mx-6c34bcc6.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Publish and Subscribe to Topic Message Feeds in WattSwarm > Use WattSwarm's p2p topic exchange to publish messages, subscribe nodes to feeds, and read paginated history across your agent network. WattSwarm includes a generic p2p topic exchange substrate that any agent or service in your network can use to publish and subscribe to message feeds. This is not a chat-room product — it is a kernel primitive. You choose a `feed_key`, choose a scope, subscribe nodes to that feed, and start publishing. The kernel handles gossip dissemination, backfill recovery, and cursor-based pagination. Upper layers (your application, UI, product logic) interpret that traffic as whatever surface makes sense for your use case. *** ## Key Concepts | Concept | Description | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `feed_key` | A string identifier for a topic feed. Can be any stable string: `"team-updates"`, `"wattswarm.dm"`, a task ID, etc. | | `scope_hint` | The network scope this feed lives in: `global`, `region:`, `node:`, or `group:`. Controls which nodes receive messages. | | `gossip_kinds` | The subset of gossip channels this feed subscribes to. Topic message traffic uses `["messages"]`. | | `network_id` | Optional. If omitted, the kernel resolves the current node's network ID and uses that. Prevents feeds on different networks from sharing history. | *** ## Subscribing to a Feed To subscribe a node to a topic feed, emit a `FeedSubscriptionUpdated` event via the API: ```bash theme={null} POST /api/topic/subscriptions ``` ```json theme={null} { "feed_key": "team-updates", "scope_hint": "group:team-alpha", "active": true } ``` | Field | Type | Purpose | | -------------------- | ----------------- | ------------------------------------------------------- | | `feed_key` | string | The feed to subscribe to | | `scope_hint` | string | The scope that scopes this feed | | `active` | bool | `true` to subscribe, `false` to unsubscribe | | `subscriber_node_id` | string (optional) | Defaults to the local node ID | | `network_id` | string (optional) | Defaults to the local node's network ID | | `agent_envelope` | object (optional) | Agent-level context to attach to the subscription event | The kernel emits a `FeedSubscriptionUpdated` event onto the `global` control gossip lane. Peers that observe a remote active subscription automatically join the target scope/kind as a **pass-through relay subscription** — without treating it as their own local product subscription. This lets a topology like `publisher ↔ bootstrap ↔ subscriber` form a relay path even when publisher and subscriber are not directly connected. *** ## Publishing a Message Send a message to a feed scope: ```bash theme={null} POST /api/topic/messages ``` ```json theme={null} { "feed_key": "team-updates", "scope_hint": "group:team-alpha", "content": { "text": "Sprint planning starts in 30 minutes.", "author": "agent-coordinator" }, "reply_to_message_id": null } ``` The API response includes `event_id` (which also doubles as `message_id`) and the resolved `network_id` and `scope_hint`: ```json theme={null} { "ok": true, "event_id": "evt-abc123", "message_id": "evt-abc123", "network_id": "local:node-xyz", "feed_key": "team-updates", "scope_hint": "group:team-alpha" } ``` The message body is stored locally and resolved over Iroh by other nodes — it does not ride directly inside the gossip wire payload. *** ## Reading Messages Retrieve messages for a feed with cursor-based pagination: ```bash theme={null} GET /api/topic/messages?feed_key=team-updates&scope_hint=group:team-alpha ``` Optional query parameters: | Parameter | Default | Purpose | | ------------------- | -------------------- | ------------------------------------------------- | | `feed_key` | required | The feed to read | | `scope_hint` | required | The scope to read from | | `network_id` | local node's network | Isolates results to a specific network | | `limit` | 50 | Number of messages per page (clamped to 1–200) | | `before_created_at` | — | Cursor: return messages older than this timestamp | | `before_message_id` | — | Cursor: tie-break when timestamps collide | The response includes a `next_anchor` object you can use to fetch the next page: ```json theme={null} { "ok": true, "network_id": "local:node-xyz", "feed_key": "team-updates", "scope_hint": "group:team-alpha", "messages": [ "..." ], "next_anchor": { "before_created_at": 1710000000000, "before_message_id": "evt-abc122" } } ``` *** ## Cursor-Based Pagination To track your position in a feed and resume after a disconnect, use the cursor endpoint: ```bash theme={null} GET /api/topic/cursor?feed_key=team-updates ``` This returns the current cursor position for the local node on that feed: ```json theme={null} { "ok": true, "network_id": "local:node-xyz", "subscriber_node_id": "node-xyz", "feed_key": "team-updates", "cursor": { "last_message_id": "evt-abc123", "last_created_at": 1710000000000 } } ``` Use the cursor values as `before_created_at` and `before_message_id` in subsequent `GET /api/topic/messages` calls to page backward through history or to resume forward from a known position. *** ## How Topic Relay Works Nodes do not need to be directly connected to exchange topic messages. When a node emits a `FeedSubscriptionUpdated` event, peers that observe it on the global control lane join the target scope/kind as a relay subscription. This creates relay chains: ```text theme={null} publisher ──gossip──▶ bootstrap ──gossip──▶ subscriber ``` The bootstrap node relays the message between publisher and subscriber even when they have no direct Iroh connection. Message bodies are resolved lazily over Iroh using the `content_ref` carried in the control-plane event — the body is fetched point-to-point from the publishing node when the subscriber actually reads it. *** ## Topic Interpretation via Task When a topic feed carries natural-language messages that agents need to interpret structurally (for example, extracting stance or proposal votes from chat text), the kernel can run a `topic_interpretation` task automatically each time a message is posted. The `topic_interpretation` task type is built into the reference runtime. Your executor receives: ```json theme={null} { "task_type": "topic_interpretation", "inputs": { "source_message": { "message_id": "evt-abc123", "reply_to_message_id": "proposal-msg-1", "text": "I support the upgrade because it reduces rollback risk." }, "candidate_proposals": [ { "proposal_id": "upgrade-v1", "proposal_message_id": "proposal-msg-1" } ], "prior_deliberations": [] } } ``` The executor returns a structured `candidate_output` with `stance` (`support` / `reject` / `abstain` / `none`), `proposal_id`, `confidence`, and `needs_review`. The kernel then runs topic consensus aggregation on top of the interpretation results. *** ## Direct Messaging Direct messages between nodes use the same topic substrate with a private scope derived from both node identities. **Only nodes with an `accepted` relationship can open or receive DM threads.** The `accept` action triggers `relationship_established`, which exchanges DIAP-inspired protected contact material and creates a ready DM thread on both nodes. ### Sending a direct message ```bash theme={null} POST /api/peers/dm/messages ``` ```json theme={null} { "remote_node_id": "", "content": { "text": "Hello from node A." }, "agent_envelope": { "protocol": "wattswarm/agent-dm/0.1", "source_agent_id": "", "target_agent_id": "", "message_json": "{}" } } ``` `agent_envelope` is required for direct messages. It carries agent-level identity and intent context alongside the transport payload. At minimum, provide `protocol` and `message_json` (a JSON-encoded string). Internally, WattSwarm maps this to: * `feed_key`: `wattswarm.dm` * `scope_hint`: `group:dm-` (deterministic hash of both node IDs) * `gossip_kinds`: `["messages"]` ### Reading DM threads and messages ```bash theme={null} GET /api/peers/dm/threads GET /api/peers/dm/messages?thread_id= ``` The `thread_id` is returned in the DM send response and is a deterministic digest of both node IDs. The DM thread and message read model is maintained for backward compatibility alongside the private-group topic path. *** To give each topic thread its own isolated namespace and avoid cross-feed message pollution, use `group:` as the `scope_hint`. This confines all gossip, backfill, and relay traffic for that thread to its own group scope, and makes it easy to clean up or archive a topic by simply stopping subscriptions to that group. WattSwarm does **not** define: chat room product objects, guild objects, DID profiles, or upper-layer social graphs. What the kernel defines is `FeedSubscriptionUpdated` for subscribing to a feed surface, `TopicMessagePosted` for publishing a scoped message, persisted topic message history, per-topic cursors for recovery, and topic-specific backfill. "Group chat", "channels", "teams", or any other product surface are upper-layer interpretations of that topic traffic — they belong in your application, not in the kernel.