Сбор отзывов и NPS после покупки

Бот для магазинов, ресторанов, сервисов и селлеров маркетплейсов, которым важны отзывы и повторные покупки. После заказа клиент получает в Telegram короткий опрос: «Насколько вероятно, что вы нас порекомендуете?» — и отвечает одной кнопкой от 0 до 10.

Довольные клиенты (9–10) сразу получают кнопки для отзыва на Яндекс Картах, 2ГИС, Wildberries или Ozon — так растёт рейтинг. Недовольные (0–6) рассказывают, что пошло не так, а менеджер мгновенно видит оценку с номером заказа и может ответить клиенту прямо из чата.

Опросы отправляются из CRM или сайта через HTTP API, командой, списком из файла или по ссылке и QR-коду на чеке. Команда /nps показывает NPS, доли промоутеров и критиков и последние негативные комментарии за любой период.

Для кого: Магазины, рестораны, сервисы, селлеры маркетплейсов

Что умеет

• Опрос NPS кнопками 0–10, одна оценка на опрос
• Негативные оценки (0–6) — сразу менеджеру с контекстом заказа
• Менеджер отвечает реплаем — ответ уходит клиенту
• Довольных (9–10) — на отзыв: Яндекс Карты, 2ГИС, WB, Ozon
• HTTP API POST /survey для CRM и сайта, с задержкой отправки
• Рассылка опроса списком из файла и командой /survey
• Ссылка и QR-код на чеке: ?start=nps_ЗАКАЗ
• Отчёт /nps за период и выгрузка ответов /export в CSV

Технологии и интеграции

Как запустить

1. Скопируйте .env.example в .env и впишите BOT_TOKEN и ADMIN_CHAT_ID (и SURVEY_API_TOKEN для CRM)
2. docker compose up -d --build (или pip install -r requirements.txt && python -m app)
3. Откройте бота и поставьте оценку — проверьте, что негативная пришла менеджеру
4. Подключите отправку из CRM: POST /survey с chat_id клиента

Что понадобится

Ключи и токены не вводятся на сайте — их кладут в файл .env на своём сервере.

• BOT_TOKENТокен бота — @BotFather → /newbot
• ADMIN_CHAT_IDЧат менеджеров — Ваш ID у @userinfobot или ID группы (отправьте боту /id в группе)
• SURVEY_API_TOKENТокен HTTP API — Длинная случайная строка; пусто — API выключен
• HTTP_PORTПорт HTTP API — По умолчанию 8080
• ADMIN_IDSДополнительные менеджеры — ID через запятую

Что можно доработать с AI

• Ежедневный отчёт NPS в чат менеджеров
• Анализ комментариев нейросетью: темы и причины недовольства
• Отправка опросов по статусу заказа из amoCRM или Битрикс24
• NPS по магазинам, менеджерам или товарам
• Повторный опрос, если клиент не ответил за сутки
• Дашборд NPS в Google Таблицах
• Промокод на следующую покупку за отзыв

Файлы проекта (18)

• .env.example0.7 КБ
• .gitignore0.1 КБ
• Dockerfile0.7 КБ
• README.md5.3 КБ
• app/__init__.py0.1 КБ
• app/__main__.py3.6 КБ
• app/admin.py8.1 КБ
• app/api.py3.0 КБ
• app/config.py3.9 КБ
• app/db.py8.3 КБ
• app/keyboards.py1.2 КБ
• app/nps.py4.8 КБ
• app/sender.py3.3 КБ
• app/survey.py7.3 КБ
• docker-compose.yml0.4 КБ
• pytest.ini0.0 КБ
• requirements.txt0.1 КБ
• tests/test_nps.py2.9 КБ

README

# {{BRAND}} — бот отзывов и NPS в Telegram

После покупки бот спрашивает клиента: «Насколько вероятно, что вы порекомендуете нас?» (0–10).
Довольных (9–10) просит оставить отзыв на Яндекс Картах, 2ГИС, Wildberries или Ozon, недовольных (0–6) — рассказать,
что пошло не так, и сразу передаёт это менеджеру с контекстом заказа. Отчёт NPS за любой период — командой `/nps`.

## Что умеет

- **Опрос 0–10** кнопками, одна оценка на опрос; после оценки — уточняющий вопрос.
- **Негатив (0–6) → менеджеру** сразу: клиент, заказ, контекст, оценка, затем комментарий. Менеджер отвечает реплаем —
  клиент получает ответ от имени компании.
- **Позитив (9–10) → отзыв на площадке**: кнопки-ссылки на Яндекс Карты, 2ГИС, WB, Ozon (только заполненные).
- **Три способа отправить опрос**:
  1. HTTP API `POST /survey` — из CRM, сайта, Make/n8n после выдачи заказа (можно с задержкой);
  2. команда `/survey 123456789 A-1001 Иван` или файл со списком клиентов с подписью `/survey`;
  3. ссылка или QR-код на чеке: `https://t.me/ваш_бот?start=nps_A1001` — клиент сам открывает опрос.
- **Защита от повторов**: один опрос на заказ (повторный вызов API вернёт `duplicate`).
- **Отчёт `/nps [дней]`**: NPS, доли промоутеров/нейтральных/критиков, средняя оценка, отклик, гистограмма,
  последние негативные комментарии. **`/export`** — все ответы в CSV для Excel.

## Запуск за 5 минут

### 1. Получите токены

| Что | Где взять |
|---|---|
| `BOT_TOKEN` | [@BotFather](https://t.me/BotFather) → `/newbot` → имя и юзернейм → скопируйте токен |
| `ADMIN_CHAT_ID` | Ваш ID — напишите [@userinfobot](https://t.me/userinfobot). Для группы менеджеров: добавьте бота в группу и отправьте `/id` |
| `SURVEY_API_TOKEN` | Придумайте длинную случайную строку — нужна, только если опросы будет отправлять CRM или сайт |

Скопируйте `.env.example` в `.env` и впишите значения.

### 2а. Запуск в Docker

```bash
docker compose up -d --build
docker compose logs -f   # смотреть логи
```

HTTP API слушает порт 8080. Для доступа из интернета поставьте перед ним HTTPS-прокси (nginx, Caddy).

### 2б. Запуск без Docker (Python 3.12+)

```bash
python -m venv .venv
# Windows: .venv\Scripts\activate    Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python -m app
```

## HTTP API

```http
POST /survey
Authorization: Bearer <SURVEY_API_TOKEN>
Content-Type: application/json

{"chat_id": 123456789, "order_id": "A-1001", "name": "Иван", "context": "Пицца, доставка 40 мин", "delay_minutes": 120}
```

| Поле | Обязательно | Что это |
|---|---|---|
| `chat_id` | да | Telegram ID клиента (клиент должен хотя бы раз запустить бота — например, когда оформлял заказ) |
| `order_id` | нет | номер заказа, до 64 символов; второй опрос по тому же заказу не отправится |
| `name`, `context` | нет | имя клиента и детали заказа — их увидит менеджер при негативной оценке |
| `delay_minutes` | нет | отправить через N минут (до 7 дней), например через 2 часа после доставки |

Ответ: `{"ok": true, "survey_id": 15, "status": "sent"}`. Статусы: `sent`, `scheduled`, `duplicate`;
`blocked`/`failed` (HTTP 422) — клиент не запускал бота или заблокировал его. Ошибки: 400 (неверный JSON),
401 (неверный токен), 503 (API выключен). Проверка работы: `GET /health`.

```bash
curl -X POST http://localhost:8080/survey -H "Authorization: Bearer ваш_токен" \
     -H "Content-Type: application/json" -d '{"chat_id": 123456789, "order_id": "A-1001"}'
```

## Рассылка списком

Пришлите боту в чате менеджеров файл `.csv` или `.txt` с подписью `/survey`. Строки — `chat_id;заказ;имя`
(разделитель `;`, `,` или Tab; заголовок и неверные строки пропускаются). Опросы уходят в фоне с паузами.

## Команды

| Команда | Кто | Что делает |
|---|---|---|
| `/start` | клиенты | оценить компанию (ссылка `?start=nps_ЗАКАЗ` — оценить заказ) |
| `/nps [дней]` | менеджер | отчёт NPS, по умолчанию за 30 дней |
| `/export` | менеджер | все опросы и ответы в CSV |
| `/survey ID [ЗАКАЗ] [ИМЯ]` | менеджер | отправить опрос одному клиенту |
| `/id` | все | ID текущего чата |

## Проверка

```bash
pip install -r requirements.txt pytest==9.1.1
pytest
```

Тесты проверяют расчёт NPS, категории оценок, гистограмму, проверку запросов API, разбор списка и токен.

## Структура

```
app/
  __main__.py   запуск бота, HTTP API и фоновой отправки
  config.py     настройки: .env + тексты и ссылки на отзывы из мастера
  nps.py        NPS, категории, проверка запросов (чистая логика)
  db.py         SQLite: клиенты, опросы, связи сообщений
  sender.py     отправка опросов: сразу, по расписанию, списком
  survey.py     оценка, комментарий, отзыв на площадке
  admin.py      /nps, /export, /survey, ответы менеджера реплаем
  api.py        POST /survey и GET /health (aiohttp)
  keyboards.py  кнопки
```

## FAQ

**Опрос не доставляется (`failed`).** Бот может писать только тем, кто хотя бы раз нажал «Старт». Давайте клиентам
ссылку `?start=nps_ЗАКАЗ` (QR-код на чеке или в письме) — так они откроют бота сами.

**NPS — это сколько?** NPS = % промоутеров (9–10) − % критиков (0–6), от −100 до +100. Выше 0 — хорошо, выше 50 — отлично.

**Где взять ссылку на отзывы?** Яндекс Карты и 2ГИС: карточка организации → «Отзывы» → скопируйте ссылку.
WB и Ozon: ссылка на карточку товара. Ссылки меняются в начале `app/config.py`.

**Где хранятся данные?** В SQLite: `data/nps.db` (в Docker — том `nps-data`). Делайте резервные копии.