reply-end-controls/telegram-v1-design.md

reply-end-controls - Telegram V1 Design

Scope

This project is Telegram-only.

No Discord, Slack, or cross-channel abstraction is part of V1.

Product behavior

At the end of every assistant reply sent to Telegram, attach two inline buttons:

• A. 繼續
• B. 就這樣吧，不需要額外處理

Button selection must be captured and stored in conversation/session state.

If the user types a new message instead of pressing a button, the typed message takes priority.

V1 rules

Rule 1

Every assistant reply gets reply-end buttons.

Rule 2

If the user taps 繼續:

• store lastChoice=continue
• allow follow-up behavior on later turns

Rule 3

If the user taps 就這樣吧，不需要額外處理:

• store lastChoice=stop
• suppress unnecessary continuation behavior on later turns

Rule 4

If the user sends a new typed message, that input overrides the button state.

Rule 5

After a button is clicked, the original message buttons should be updated so the selection is visually resolved and repeated clicks are reduced.

State model

Store this in Telegram conversation/session state:

{
  "replyEndControls": {
    "lastChoice": "continue | stop",
    "lastChoiceAt": "ISO timestamp",
    "sourceMessageId": "telegram message id",
    "sourceCallbackId": "telegram callback query id",
    "active": true
  }
}

Telegram callback payloads

Suggested callback data format:

• rec:continue
• rec:stop

If message-scoped state is needed later, extend to:

• rec:continue:<messageId>
• rec:stop:<messageId>

Technical flow

Outbound reply flow

1. Assistant reply text is produced.
2. Telegram reply payload is decorated with inline keyboard.
3. Message is sent to Telegram.

Callback flow

1. User clicks button.
2. Telegram sends callback query.
3. Callback handler parses continue or stop.
4. State is persisted.
5. Original message buttons are updated to reflect the chosen option.

Next-turn behavior

1. A later turn begins.
2. Runtime checks replyEndControls.lastChoice.
3. If stop, do not proactively extend or continue the previous thread unless the user explicitly asks.
4. If continue, normal continuation behavior is allowed.

Suggested implementation modules

1. Reply decorator

Responsibility:

• append Telegram inline keyboard to every assistant reply

2. Callback handler

Responsibility:

• receive Telegram callback queries
• parse reply-end action
• update state

3. State storage helper

Responsibility:

• persist and retrieve the latest reply-end selection for the current conversation/session

4. Behavior policy hook

Responsibility:

• inspect lastChoice
• suppress proactive continuation when stop is active

Acceptance criteria for V1

V1 is complete when all of the following are true:

1. A normal Telegram assistant reply shows both buttons.
2. Clicking 繼續 is received and stored.
3. Clicking 就這樣吧，不需要額外處理 is received and stored.
4. After click, the original message is updated to show the choice state.
5. A new typed user message still works without pressing any button.
6. A later turn can read the stored choice and alter continuation behavior.

Non-goals for V1

• multi-channel abstraction
• governance integration
• analytics dashboard
• complex branching controls beyond continue and stop