Non-visible channel control messages

nonVisible: true marks channel content for bots and plugins. Official clients have no composer switch and ordinary history/synchronization omits these records, keeping them out of transcripts, search, unread counts and notifications. Authorized API consumers can explicitly retrieve them.

Send and receive

await server.sendMessage(channelId, JSON.stringify({

  type: 'com.example.build.finished', version: 1, job: 'job-42', status: 'passed',

}), { nonVisible: true });



const page = await server.history(channelId, cursor, true);

for (const message of page.messages) {

  const text = decryptMessage(message, keys); // Authenticate before acting.

  if (message.envelope.nonVisible === true) {

    const event = JSON.parse(text);

    // Validate sender, event schema, permitted action and application deduplication.

  }

}

cursor = page.cursor;

For the existing deployment server's ordinary channels, use client.sendMessage(channelId, text, {nonVisible:true}) and client.history(channelId, cursor, true).

Wire contract

The channel-control-messages/1 capability advertises support. The optional envelope field nonVisible is boolean; omission and false mean an ordinary visible message. Null, strings and numbers are rejected. Its value is covered by the Ed25519 envelope signature and bound inside each E2EE recipient payload. For server-readable channels the signed plaintext variant applies.

GET .../history?after=0&includeNonVisible=1 includes both visible and non-visible eligible records. The existing deployment's sync route accepts the same query. Omission or 0 hides controls; values other than 0 and 1 fail. Filtering follows bounded pagination, and the returned cursor advances across omitted records. Use the cursor even when messages is empty.

Access and retention

Control traffic uses current channel admission, recipient-device coverage, encryption mode, membership-interval history, seven-day retention, instance storage quotas, body limits and send-rate limits. It does not bypass permissions, count as a new bot privilege, or become secret from other authorized channel members. It is retained traffic, not an ephemeral guaranteed-delivery queue. A consuming plugin may see it more than once after reconnect; deduplicate application actions using the authenticated message ID and your own durable state.

Control messages cannot be pinned, used as thread roots/reply parents, sent as replies, or sent in direct/group conversations. Ordinary members cannot use the flag to create executable authority; each bot/plugin owns validation and authorization of its control payloads. A channel creator should choose encryption deliberately: a server-readable channel remains server-readable.