# Telegram Bot / Mini App Integration

## Current managed bot

The Git-managed bot source is:

```text
bot/bot.cjs
```

The bot runs as:

```text
pixdala-bot
/opt/pixdala/current/bot/bot.cjs
```

The stable test Mini App URL is:

```text
https://im-test.bktis.ru/apps/miniapp/
```

The public-facing project name is DigiDala; technical identifiers remain PixDala where required by the existing deployment/repository setup.

## Telegram launch mechanisms

There are two intentionally different launch mechanisms.

### Private chat

In a private chat, `🪷 Открыть DigiDala` is an `InlineKeyboardButton.web_app` using the stable Mini App URL. The Telegram Menu Button is also configured as `type: web_app` to the same URL. Both mechanisms have been verified to work on Telegram Desktop and Mobile.

The `startapp` deep-link mechanism is used for Mini App navigation from group messages and depends on the bot's Main Mini App configuration.

### Group navigation

Telegram `web_app` inline buttons are not available in group chats, so the group navigation uses Main Mini App deep links instead:

```text
🪷 Открыть DigiDala
https://t.me/PixDala_bot?startapp

🤝 Мандала поддержки
https://t.me/PixDala_bot?startapp=support

🎨 Мандала творчества
https://t.me/PixDala_bot?startapp=creative

⭐ Поддержать проект
https://t.me/PixDala_bot?start=support
```

The first three links depend on the bot having a configured **Main Mini App**. The last link is an ordinary bot deep link and enters the existing private Stars support flow.

### Main Mini App operational prerequisite

For `@PixDala_bot`, the Main Mini App must be configured in BotFather to:

```text
https://im-test.bktis.ru/apps/miniapp/
```

This is an external Telegram configuration item; it is not stored in `bot/bot.cjs`. Without it, `?startapp` links can fail with `BOT_INVALID` on Desktop or open the Mini App without the requested start parameter on Android, causing the client to fall back to Sandbox.

## Mini App routing

`apps/miniapp/app.js` resolves the initial Mandala slug in this order:

```text
mandala
→ startapp
→ tgWebAppStartParam
→ Telegram.WebApp.initDataUnsafe.start_param
→ sandbox
```

The final `sandbox` value is a deliberate fallback only. With a correctly configured Main Mini App, `startapp=support` and `startapp=creative` reach the requested Mandalas.

## Verified state — 2026-09-14

After configuring the Main Mini App, manual Telegram verification passed on Android and Desktop for:

- group `🪷 Открыть DigiDala` → Sandbox;
- group `🤝 Мандала поддержки` → Support;
- group `🎨 Мандала творчества` → Creative;
- `⭐ Поддержать проект` → private Stars support flow;
- private `web_app` launch.

---

# Telegram Test Bot

## Назначение

Тестовый Telegram-бот DigiDala используется для запуска тестовой версии Mini App.

## Расположение

Исходный код тестового бота находится отдельно от основного репозитория Mini App:

```text
/opt/pixdala/bot-test/bot.js
```

Основной репозиторий DigiDala:

```text
/opt/pixdala/repo
```

Поэтому поиск кода бота только внутри `/opt/pixdala/repo` ничего не найдёт.

## Mini App URL

Тестовый бот запускает:

```text
https://im-test.bktis.ru/apps/miniapp/
```

URL задаётся в файле:

```text
/opt/pixdala/bot-test/bot.js
```

через:

```js
const MINI_APP_URL = 'https://im-test.bktis.ru/apps/miniapp/';
```

## Кнопка запуска

Команда `/start` отправляет сообщение с кнопкой:

```text
🧪 Запустить тест
```

Кнопка реализована через Telegram:

```js
reply_markup: {
  inline_keyboard: [[
    {
      text: '🧪 Запустить тест',
      web_app: {
        url: MINI_APP_URL
      }
    }
  ]]
}
```

Таким образом, используется:

```text
InlineKeyboardButton
+
WebAppInfo
+
web_app.url
```

Это важно при диагностике Telegram `initData`: Mini App запускается через inline keyboard, а не через обычную reply keyboard.

## Особенности запуска

Тестовый бот работает через long polling.

При запуске бот:

1. вызывает `getMe`;
2. удаляет webhook через `deleteWebhook`;
3. запускает `getUpdates`.

Используется:

```js
allowed_updates: ['message']
```

## Связь с проблемой Telegram initData

Текущая цепочка запуска:

```text
Telegram Test Bot
    ↓
inline keyboard
    ↓
web_app
    ↓
Mini App
    ↓
Telegram.WebApp.initData
```

При диагностике кнопки «Занять клетку» ранее наблюдался на Android симптом:

```text
Нет Telegram InitData
```

при том, что Mini App успешно загружал данные мандалы через API.

На Desktop занятие клетки уже успешно проходило через:

```text
POST /api/v1/mandalas/.../occupy
```

со статусом `201`.

Следующий этап диагностики должен проверить жизненный цикл `Telegram.WebApp` и наличие `initData` на Android отдельно при загрузке Mini App и непосредственно перед занятием клетки.

## Важное замечание для диагностики UI

Статусы:

```text
Подключение
Синхронизировано
```

отображаются под мандалой.

При открытом модальном окне занятия этот участок интерфейса перекрыт модальным окном, поэтому эти статусы нельзя использовать как визуальный диагностический индикатор в момент заполнения формы.

Для диагностики состояния внутри модального окна следует использовать отдельный диагностический индикатор.

## Связанные файлы

Основной файл тестового бота:

```text
/opt/pixdala/bot-test/bot.js
```

Основной репозиторий:

```text
/opt/pixdala/repo
```

Тестовый Mini App:

```text
https://im-test.bktis.ru/apps/miniapp/
```