---
title: "Transfer group or channel ownership through an assistant"
locale: en
url: https://tlg.builera.app/en/docs/agent-playbooks/transfer-ownership
verified: 2026-10-25
app_version: "2.1"
---

# Transfer group or channel ownership through an assistant

The assistant files a transfer request, the person confirms it in the conversation and then types the two-step verification password on a separate secure page.


## Goal

You help a person hand ownership of a group or channel to someone else **without ever** seeing the account's two-step verification password. You only file the request; the person types the password on Telegram-Auto's secure page.

## Permissions needed

- `groups.admin`, with the Owner or Manager role.
- The account that owns the group must be within the connection's scope.

## Ask the person before

Ask which group and **who the new owner is** (their Telegram user id). You cannot undo an ownership transfer: the new owner can remove the old account's rights.

## Check first

Call `whoami`. Read the group with `groups.info` to make sure the account is its owner. The new owner should already be a member (usually an administrator) of the group.

## Steps

1. Call `groups.request_transfer` with `conversationId` and `user: { id }`.
2. This operation **always asks for confirmation**, even when the connection is set to "allow". You get `409 confirmation_required` with a `summary`.

> [!IMPORTANT]
> Stop point — ask the person
>
> Give the person the `summary` as it is (group, new owner). Only when they agree to exactly that, call again with the same input and the `confirm_token`.

3. The answer has `transferId`, `secureUrl`, `expiresAt` and `status: awaiting_password`.
4. Give the person the `secureUrl` and tell them: open the link, sign in to Telegram-Auto if asked, check the group name and the new owner, tick "I understand this cannot be undone", then type the two-step verification password themselves.
5. Follow it with `groups.transfer_status` and the `transferId`.

Never ask for the password in the conversation, never repeat it, never put it in notes or logs. If the person sends you the password by mistake, tell them to change it and type the new one on the secure page.

## Check after

| `status` | Meaning |
|---|---|
| `awaiting_password` | Waiting for the person to type the password (up to 30 minutes) |
| `queued`, `running` | Password received, the machine is transferring |
| `done` | Transferred |
| `failed` | Telegram refused; read `code` |
| `expired` | Not typed within 30 minutes — file a new request if the person still wants it |
| `cancelled` | Cancelled |

The password is encrypted, handed only to that transfer job and deleted as soon as there is a result.

## If something goes wrong

- `transfer_pending`: the group already has a waiting request — follow it or cancel it.
- `too_many_transfers`: each connection holds at most 5 open requests — wait or cancel some.
- The person changes their mind before typing the password: call `groups.cancel_transfer`.

## Stop conditions

Stop when the status is `done`, `failed`, `expired` or `cancelled`, or when the person has not confirmed the request.