Docs

Concepts

Confirmation before dangerous actions

Understand how the app and agents ask for confirmation before dangerous or irreversible actions.

View Markdown

Confirmation gives you a chance to stop before a risky action. It does not replace access permissions, account scope, or the safety gate. A confirmed request can still be rejected because permissions are missing or conditions are not met.

Types of risk

Each operation has a risk level: read (read), write (write), or dangerous (dangerous). Some write operations become dangerous depending on the data you submit.

Example Why it needs attention
messages.delete Deletes messages
conversations.clear_history Deletes conversation history
accounts.logout Logs out the current session
accounts.kill_session Terminates a Telegram session
groups.delete_topic Deletes a topic and its contents
groups.delete_chat Deletes a group or channel for everyone
jobs.redrive May repeat an effect
accounts.update_settings with limitMode: free Removes Safe mode's soft protections

These are examples, not a complete list. Each operation's REST reference states its risk level and whether confirmation is required.

How must an agent ask the user?

REST and MCP use the same mechanism. A 409 confirmation_required response contains summary (a description of what is about to happen) and confirm_token.

The agent must:

  1. Stop.
  2. Present the full meaning of summary to you.
  3. Wait for your approval of that exact action and scope.
  4. Call again with the same data, adding confirm_token.

The token is valid for 10 minutes, can be used once, and is bound to that exact request. If the recipient, account, or content changes, the old token cannot be used. Giving an agent a general goal does not mean approving every dangerous action it might take later.

validate_only: true checks the request without carrying out its effects.

MCP tool names use the operation code with dots replaced by underscores; for example, groups.delete_chat corresponds to groups_delete_chat. Tool availability also depends on the connection profile and permission scope.

Deleting a group or channel

In the deletion dialog, you must type the displayed name exactly. The delete button is enabled only when the name matches. Leading and trailing spaces are ignored, but accents and letter case must match.

Ownership transfer and two-step verification passwords

Only a person can transfer ownership, in the app; AI connections do not have this operation.

You enter your two-step verification password for that specific transfer. The password is encrypted, passed only to the machine assigned the job, then deleted immediately — entered once, used once. Do not put the password in messages to an agent, logs, or API examples.