Abitly CRM/Support bot

Метадані

Поле	Значення
Продукт	Abitly.org
Тип	Bot (helpdesk / CRM)
Статус	🟢 prod (E2E 21.07.2026: Telegram + Instagram Direct повний цикл)
Власник	@Vladbandurin

Призначення

Омніканальна підтримка користувачів: звернення з трьох каналів — Telegram DM (@Abitly_support_bot), Instagram Direct (@abitly_org) та Facebook Messenger (сторінка Abitly.org) — потрапляють у форум-супергрупу «Abitly CRM» (-1004465988569): топік на розмову/людину, двосторонній міст переписки, журнал усіх повідомлень у DynamoDB.

Telegram-канал: інтейк-візард (кнопки, дерево конфігурується в БД) → топік на звернення; підтримка reply/edit/реакцій/медіа в обидва боки (copyMessage, анонімно від імені бота).
Meta-канали: перше вхідне DM одразу створює топік 📸 Ім'я @username (IG) / 📘 (Messenger); відповіді операторів ідуть через Send API; відповіді з Meta Business Suite дзеркаляться в топік (echo), власні send-и придушуються.
Статус у назві топіка: 🔵 чекає команду · ⚪️ чекає користувача · ⚫️ закрито. /close оператором — без сповіщення користувачу (рішення власника 21.07).

stateDiagram-v2
    [*] --> CREATING_QUESTIONS : TG /start (візард)
    [*] --> WAITING_OPERATOR : IG/FB перше DM (без візарда)
    CREATING_QUESTIONS --> CREATING_TITLE : категорія
    CREATING_TITLE --> WAITING_OPERATOR : текст → топік 🔵
    WAITING_OPERATOR --> WAITING_USER : оператор відповів → ⚪️
    WAITING_USER --> WAITING_OPERATOR : користувач написав → 🔵
    WAITING_OPERATOR --> CLOSED : /close → ⚫️
    WAITING_USER --> CLOSED : /close
    CLOSED --> [*]

Репозиторій та рантайм


Репо	`abitly-org/abitly-crm-bot` (`main`)
Стек	grammY (TypeScript) · esbuild-бандл · vitest (35 тестів)
Хостинг	AWS Lambda `abitly-crm-bot` (`us-east-1`, nodejs22.x, arm64, 256 MB, timeout 25 s)
Вхід	API Gateway HTTP API `uzvdt7dc5e`: `POST /update` (Telegram webhook, secret token) + `GET/POST /meta` (Meta webhook: hub.challenge + `X-Hub-Signature-256`). Анонімний Lambda Function URL заборонений org-політикою
БД	DynamoDB `abitly-crm-bot` (PAY_PER_REQUEST, single-table): `USER#`/`CONVO#`/`TOPIC#`/`RMSG#`/`CHAN#`/`MID#`/`LOG#`/`CONFIG`
Meta app	`abitly` (`2557934751302228`) — той самий, що для Marketing API; app-level subscriptions: `object=instagram` (messages, postbacks, seen) + `object=page` (messages, postbacks, echoes, reactions); Page `602615379596867` ↔ IG `@abitly_org` (IGSID `17841472778891677`)
Bot username	`@Abitly_support_bot` (`8795373237`)
Обмеження Meta	вікно відповіді: ≤24 год `RESPONSE`, ≤7 діб тег `HUMAN_AGENT`, далі — тільки чекати нового повідомлення. Dev mode: DM від сторонніх користувачів запрацюють після App Review (Advanced Access: `pages_messaging`, `instagram_manage_messages`, Human Agent) — `TODO:` подати

Залежності

Залежить від: Telegram Bot API · Meta Graph API (graph.facebook.com v25.0, page token) · DynamoDB. Від Abitly API / shared Postgres не залежить — повністю ізольований сервіс.
Від нього залежать: команда підтримки (операційний інструмент; група «Abitly CRM»).

Env-змінні

Лише назви (значення — Lambda env; резерв у SSM). Повний індекс: environments.

Змінна	Призначення	Де зберігається
`BOT_TOKEN`	токен `@Abitly_support_bot`	Lambda env
`WEBHOOK_SECRET`	Telegram `X-Telegram-Bot-Api-Secret-Token`	Lambda env
`GROUP_CHAT_ID`	id форум-групи «Abitly CRM»	Lambda env
`TABLE_NAME`	DynamoDB таблиця	Lambda env
`META_ACCESS_TOKEN`	page token (вмикає Meta-канали; порожній = вимкнено)	Lambda env + SSM `/abitly/prod/crm-bot/META_PAGE_TOKEN`
`META_APP_SECRET`	HMAC-перевірка вебхуків Meta	Lambda env + SSM `/abitly/prod/crm-bot/META_APP_SECRET`
`META_VERIFY_TOKEN`	hub.challenge-верифікація підписки	Lambda env
`META_GRAPH_HOST` / `META_API_VERSION`	`graph.facebook.com` / `v25.0`	Lambda env
—	long-lived user token (перевипуск page token)	SSM `/abitly/prod/crm-bot/META_LONG_USER_TOKEN`

Ключові ендпоінти / команди

npm ci && npm run typecheck && npm test   # 35 тестів (vitest)
npm run package                            # esbuild → dist/lambda.zip
AWS_PROFILE=abitly ./scripts/deploy.sh     # ручний деплой (GH Actions billing зламаний)
AWS_PROFILE=abitly ./scripts/provision.sh  # ідемпотентний провіжининг (таблиця, роль, Lambda, роути)
python3 scripts/e2e_full.py                # живий E2E: юзер → топік → оператор → /close

Команди оператора в топіку: /close · /ban · /unban · /notes · /rm · \... (внутрішній коментар). Для Meta-розмов доступний лише /close — решта TG-only.

Деплой та відкат

Merge у main → вручну ./scripts/deploy.sh (typecheck + тести + zip + update-function-code). Відкат: aws lambda update-function-code з попереднім zip (артефакти неверсіоновані — TODO: S3-версіонування). CI/CD workflow готовий, чекає полагодження GH Actions billing на org.

Логи та моніторинг

CloudWatch Logs /aws/lambda/abitly-crm-bot (structured console.log). Журнал усіх повідомлень — DynamoDB LOG#<chatId> (Meta-канали: псевдо-chatId 0). Алармів нема — TODO: CloudWatch alarm на ERROR.

Типові проблеми

Топік не створюється (not enough rights) → боту бракує права Manage topics у групі; стан не втрачається, наступне повідомлення повторить спробу.
⛔ Meta відхилила повідомлення в топіку → вікно 7 діб минуло або page token інвалідовано (зміна пароля FB / відкликання сесій) → перевипустити з META_LONG_USER_TOKEN (SSM).
Кастомні емоджі-іконки топіків неможливі: Telegram віддає PREMIUM_ACCOUNT_REQUIRED для ботів (перевірено); канал позначається текстовим бейджем у назві.