# How to Use the Telegram Bot for Remote Re-authentication When the iCloud Cookie Expires

> Learn to use the Telegram bot within docker-icloudpd to remotely re-authenticate iCloud and refresh your expired cookie without accessing the container shell.

- Repository: [boredazfcuk/docker-icloudpd](https://github.com/boredazfcuk/docker-icloudpd)
- Tags: how-to-guide
- Published: 2026-02-26

---

**The docker-icloudpd container includes a two-way Telegram bot that lets you trigger a fresh iCloud authentication flow remotely by sending a specific command, eliminating the need to open a shell inside the container when your cookie expires.**

The `boredazfcuk/docker-icloudpd` image ships with a built-in Telegram integration that handles remote re-authentication through a simple chat interface. When your iCloud session cookie expires—typically every 30 days or after password changes—Apple requires Multi-Factor Authentication (MFA) renewal. Instead of executing commands inside the running container, you can use the Telegram bot for remote re-authentication to trigger the entire flow from your phone.

## How the Telegram Bot Handles Remote Re-authentication

The remote re-authentication system consists of several coordinated scripts that manage bot initialization, message polling, command parsing, and the actual cookie regeneration.

### Bot Initialization and Verification

When the container starts, [`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh) (lines 673-702) checks the `telegram_bot_initialised` variable. If this is set to `false` (the default), the script sends a "ping" to the Telegram Bot API to verify the bot has received at least one message from your chat. If this check fails, the container logs a warning instructing you to send `/start` to the bot in Telegram.

### Command Polling and Detection

Once initialized, the container enters a polling loop controlled by [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) (lines 2390-2411). This loop repeatedly calls the Telegram `getUpdates` method, looking for new messages. When you send the remote re-authentication command, the script detects it in the remote-sync block (lines 2434-2445).

The bot recognizes messages that begin with your configured **user name** (default: `boredazfcuk`) followed by the word `auth`. For example: `boredazfcuk auth`.

### MFA Flow and Expect Script

Upon detecting the remote auth command, [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) (line 2445) executes the bundled `authenticate.exp` expect script in the background. This script initiates an iCloud login that triggers a push notification to your iPhone. After you approve the notification on your device, the script captures the MFA code displayed on your screen.

The [`sendmessage.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sendmessage.sh) script (lines 16-26) then sends you a Telegram message listing available MFA options and requesting the 6-digit code.

### Cookie Regeneration

When you reply with the valid 6-digit MFA code, the container executes [`reauth.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/reauth.sh) (lines 25-37). This script performs the actual remote re-authentication by:
1. Removing stale cookie files from `/config`
2. Running `icloudpd --auth-only` to obtain a fresh MFA-enabled cookie
3. Cleaning up temporary logs from `/tmp/icloudpd/reauth.log`

After successful completion, the bot sends a confirmation message and the regular photo sync resumes automatically.

## Configuring the Telegram Bot for Remote Re-authentication

To enable remote re-authentication, you must set several environment variables. These are written to [`/config/icloudpd.conf`](https://github.com/boredazfcuk/docker-icloudpd/blob/main//config/icloudpd.conf) by [`init_config.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/init_config.sh) during container startup.

Required variables:

- `telegram_token` – Your bot token from BotFather (format: `123456789:ABCdefGhIJKlmNoPQRstuVWXyz`)
- `telegram_chat_id` – The numeric chat ID where the bot will listen (e.g., `-1001122334455`)
- `telegram_polling` – Set to `true` to enable the polling loop (default: `true`)
- `telegram_user` – The username prefix for commands (default: `boredazfcuk`)

Optional variables for self-hosted setups:
- `telegram_http` – Set to `true` if using HTTP instead of HTTPS
- `telegram_server` – Custom Telegram API server address

### Docker Compose Example

```yaml
services:
  icloudpd:
    image: ghcr.io/boredazfcuk/docker-icloudpd:master
    container_name: icloudpd
    environment:
      - apple_id=you@example.com
      - apple_pass=********
      - telegram_token=123456789:ABCdefGhIJKlmNoPQRstuVWXyz
      - telegram_chat_id=-1001122334455
      - telegram_polling=true
      - telegram_user=boredazfcuk
    volumes:
      - ./config:/config
      - ./photos:/home/user/iCloud
    restart: unless-stopped

```

## Step-by-Step Remote Re-authentication Process

When your iCloud cookie expires, follow these steps to re-authenticate remotely:

1. **Open Telegram** and navigate to your bot chat.

2. **Send the authentication command** using your configured username prefix:
   
   ```text
   boredazfcuk auth
   ```

3. **Approve the push notification** on your iPhone when it appears.

4. **Check the MFA code** displayed on your iPhone screen (usually a 6-digit number).

5. **Reply to the bot** with the 6-digit code:
   
   ```text
   123456
   ```

6. **Wait for confirmation** – the bot will notify you when [`reauth.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/reauth.sh) successfully generates the new cookie and the sync resumes.

If the bot does not respond to the initial command, ensure you have previously sent `/start` to the bot so that `telegram_bot_initialised` is set to `true` in the container configuration.

## Summary

- The **Telegram bot for remote re-authentication** in `boredazfcuk/docker-icloudpd` eliminates the need to access the container shell when iCloud cookies expire.
- The system uses **[`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh)** for bot initialization, **[`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh)** for command polling, **`authenticate.exp`** for handling the MFA push notification, and **[`reauth.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/reauth.sh)** for generating fresh cookies.
- Configuration requires **`telegram_token`**, **`telegram_chat_id`**, and optionally **`telegram_user`** to set the command prefix.
- Users trigger re-authentication by sending **`[username] auth`** followed by the 6-digit MFA code displayed on their iPhone.

## Frequently Asked Questions

### What message format do I use to trigger remote re-authentication?

Send a message that starts with your configured `telegram_user` value (default: `boredazfcuk`) followed by the word `auth`. For example: `boredazfcuk auth`. The bot detects this pattern in [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) (lines 2434-2445) and initiates the authentication flow.

### Why does the bot ask me to send /start before authenticating?

The container verifies that the bot has been initialized by checking the `telegram_bot_initialised` variable in [`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh) (lines 673-702). Sending `/start` to the bot in Telegram creates a chat history that the container can verify via the Telegram API. Until this check passes, the container logs warnings and ignores remote auth commands to prevent unauthorized access.

### Can I use the Telegram bot for remote re-authentication with multiple Apple IDs?

Each container instance supports one Apple ID, but you can run multiple container instances with different `apple_id` values and separate Telegram bot configurations. Each instance requires its own `telegram_token` and `telegram_chat_id` (or separate chat IDs with the same bot), and each will respond independently to remote re-authentication commands sent to their respective chats.

### What happens if I enter the wrong MFA code via Telegram?

If you send an incorrect 6-digit code, the `authenticate.exp` expect script will fail to validate the MFA challenge, and [`reauth.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/reauth.sh) will not generate a valid cookie. The container will log the authentication failure and send an error message via Telegram. You must restart the process by sending the `auth` command again to generate a new push notification and obtain a fresh MFA code.