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

Установка виджета

Создайте проект в админке, откройте раздел «Виджет на сайт» и скопируйте сниппет с уникальным `siteKey`. Вставьте перед закрывающим `</body>`:

<script src="https://widget.tg-desk.com/widget.v1.js"
        data-site-key="sk_live_…" async></script>

Виджет рендерится в Shadow DOM и не наследует стили вашего сайта. Размер ≤ 50 КБ gzip.

Настройка Telegram-группы

1. В админке нажмите «Подключить Telegram desk» — получите setup-токен.
2. Кликните «Открыть Telegram» — откроется `t.me/desktg_bot?startgroup=<токен>`.
3. Telegram сам предложит создать или выбрать существующую группу с ботом.
4. Назначьте бота админом с правом Manage Topics — токен подхватится автоматически.

Если бот ещё не успел стать админом, токен «подождёт» — никаких повторных команд не нужно. Когда права появятся, подключение завершится само.

Приглашение операторов

1. В «Операторы» добавьте сотрудника по имени и email.
2. Нажмите «Скопировать ссылку» — отправьте её оператору.
3. Оператор открывает ссылку в Telegram, бот привязывает его аккаунт — теперь он видит топики в супергруппе.

Отвязать Telegram можно кнопкой «Отвязать TG». Без пароля unlink запрещён — иначе пользователь потеряет единственный способ войти.

Создание базы знаний

В разделе «База знаний» создайте handbook, добавьте категории и статьи. Редактор — TipTap: заголовки, списки, изображения, код. Каждая публикация пишет `ArticleVersion` — откат и аудит из коробки.

Свой домен подключается через CNAME на `kb.tg-desk.com`. Сертификат выписывается автоматически.

Справочник API

Все эндпоинты под `https://api.tg-desk.com/v1/*`, авторизация — Bearer-токен из админки.

# Список диалогов проекта
GET /v1/conversations?status=open&limit=50

# Получить историю одного
GET /v1/conversations/:id/messages

# Отправить ответ от имени оператора
POST /v1/conversations/:id/messages
{
  "body": "Спасибо, мы разобрались",
  "agentId": "usr_…"
}

Webhooks

Подпишитесь на события в разделе «Интеграции → Webhooks». Каждое событие подписывается HMAC-SHA256 по вашему секрету:

conversation.created
conversation.assigned
conversation.closed
message.received

Заголовок `X-TGDesk-Signature` содержит подпись тела запроса. Повторы — экспоненциальный backoff до 24 часов.

Что если что-то не работает

• Бот не реагирует на /start <токен> — проверьте, что у вебхука включены `message`, `my_chat_member`, `chat_member` в `allowed_updates`.
• Нет прав Manage Topics — индикатор на странице «Telegram desk» останется красным; обновите права бота, индикатор перейдёт в зелёный сам (опрос каждые 3 секунды).
• Виджет не появляется — откройте консоль браузера и проверьте, что `siteKey` отдаёт CORS-заголовки. Если домен ещё не привязан — проверьте, что он указан в проекте.