Documentation

Agent sessions: keep notifications and replies in one conversation

Preview Ntfyx Session conversations: group CLI and agent messages by session ID inside a Topic, confirm the original message, and send text replies with a clear reference.

Updated 8 October 2026

Availability: next-release preview

Session conversations and message-level replies are implemented for the next Ntfyx CLI, Web, iOS and Android release. They are not included in the currently published CLI 0.1.2. Check ntfyx help for --session-id before using the examples below. This guide describes the upcoming experience; the homepage animation is an illustration, not a live remote agent.

Published downloads and platform availability

Inbox → Topic → Session → messages

A Topic is an authorized delivery channel. A Session is a conversation within that Topic, usually representing one agent run, deployment or long-running job. The Inbox groups conversations under their Topics and shows each session’s latest message. Opening a session shows its chronological notifications, questions and verified replies.

Session grouping does not create another Topic or change its access controls.

Level	Purpose	Example
Inbox	Your authorized receiving device	Phone or Web Inbox
Topic	Sources, permissions and notification settings	Development
Session	One task and its conversation	Release v2.4
Message	A notification or one request for input	Build passed / Publish preview?

Send related messages with the same session ID

After connecting your CLI to a Topic, supply --session-id to send and ask. Use a stable ID for one task and a different ID for a new run. --session-name gives the conversation a readable name. The identifier is matched within a Topic; reusing it in another Topic does not merge the conversations. Multiple authorized sources in the same Topic can contribute to the same session.

ntfyx send "Build passed" --session-id release-24 --session-name "Release v2.4"
ntfyx ask "Publish the preview?" --allow-deny --session-id release-24
ntfyx ask "What should I check next?" --text --session-id release-24

Use one ID for an agent run

An agent or script can set NTFYX_SESSION_ID and optionally NTFYX_SESSION_NAME for a run. Explicit command flags override the environment. The --sessionid spelling is also accepted. Choose non-secret opaque identifiers; session names provide the readable context.

export NTFYX_SESSION_ID=release-24
export NTFYX_SESSION_NAME="Release v2.4"
ntfyx send "Tests passed"
ntfyx ask "What should I check next?" --text

Confirm the message; quote the question

Allow once, Deny and choice options appear on the message asking for the decision. For a text answer, select Reply on the original message. The composer quotes that question. Close it to keep a draft without sending; select another message to answer that one. A newly arriving question does not replace the current reply target.

Sent answers appear at their reply time and include a reference back to the original question. Sending, retry and terminal states stay attached to the request they describe.

No session ID means a separate conversation

An ordinary notification without a session ID keeps the independent-message behavior: each new notification becomes a separate session. Equal titles do not merge messages. Requests remain separate decisions even when they share a session ID; replying to one does not answer the others. Session grouping does not restore earlier history to a newly authorized browser.

Grouping does not change approval or encryption

The sender still verifies the reply against the original request, revision and deadline. Cancellation, expiry and a Deny never become an Allow. Messages and replies remain end-to-end encrypted for authorized devices, while the relay retains operational metadata. A session is not a general chat endpoint and does not grant remote-shell access.

Use the existing result and single-claim workflow for actions that must run only once.