К содержанию
База CRMДокументация
Открыть Базу

Telegram

Подключение и прокси

Интеграция с Telegram — первая живая База. Она принимает входящие сообщения клиентов в общий архив «Взаимодействия», связывает их с контактами и позволяет отвечать прямо из карточки диалога.

Интеграция с Telegram — первая живая База. Она принимает входящие сообщения клиентов в общий архив «Взаимодействия», связывает их с контактами и позволяет отвечать прямо из карточки диалога.

#Что требуется

  • Токен бота от @BotFather.
  • SOCKS5 прокси — Telegram API заблокирован в РФ, без прокси подключение не пройдёт.
  • Роль владельца или админа рабочего пространства.
  • Публичный APP_URL вашей Базы — на него Telegram будет доставлять входящие сообщения.

Подключить Telegram

  1. Создайте бота у @BotFather

    Отправьте команду /newbot в диалоге с BotFather, задайте имя и username. Скопируйте токен — он выглядит как 123456789:AAHdqTcvbXyz....

  2. Настройте SOCKS5 прокси

    В РФ Telegram API заблокирован. Укажите адрес прокси — формат socks5://host:port (DNS-резолвит клиент), socks5h://host:port (DNS-резолвит прокси) или socks5://user:pass@host:port с авторизацией.

  3. Откройте «Интеграции» → «Каталог» → Telegram

    Нажмите «Подключить».

  4. Введите токен бота и прокси

    Заполните оба поля. Система проверит формат токена и сразу вызовет метод getMe через прокси, чтобы убедиться, что всё работает.

  5. Сохраните

    Если токен верный и прокси доступен — подключение сохранится со статусом «Подключено», и рядом появится username бота.

#Форматы прокси

  • socks5://host:port — DNS-запрос выполняет клиент (сервер Базы).
  • socks5h://host:port — DNS-запрос выполняет сам прокси. Полезен, если на сервере нет доступа к DNS или нужен обход DNS-фильтров.
  • socks5://user:pass@host:port — прокси с авторизацией (логин и пароль).

#Вебхук и входящие сообщения

Что происходит после подключения

  1. Регистрация вебхука

    Система генерирует секрет и вызывает setWebhook, направляя Telegram на адрес /telegram/webhook/… вашей Базы.

  2. Маппинг коллекций

    При подключении вы выбираете, куда Telegram будет писать данные: коллекцию контактов (обязательно) и коллекцию сделок (опционально). Система не ищет коллекции по названию — маппинг явный.

  3. Один диалог — одна карточка

    Каждый чат становится карточкой во «Взаимодействиях» (системная коллекция с системным кодом interactions). Поле «Источник» помечает её как Telegram, последнее сообщение отражается в Текст/Из/Направление/Время, а полная переписка — в ленту комментариев на карточке. Одна карточка обновляется, а не плодит по записи на сообщение.

  4. Связь с контактами

    При первом сообщении в диалоге создаётся карточка в выбранной коллекции контактов, и чат связывается с ней.

  5. Отвечайте из CRM

    В карточке диалога (и в карточке контакта) есть поле «Ответить в Telegram» — текст уйдёт клиенту через sendMessage, а ответ запишется в ту же карточку диалога.

Баланс вклада

Webhook проверяется по двум признакам: уникальный идентификатор подключения в URL и заголовок X-Telegram-Bot-Api-Secret-Token. Запросы без правильного секрета отклоняются (403) до любой работы с данными.

#Переустановка вебхука

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

#Фоновый опрос вместо вебхука

Webhook — Telegram сам доставляет сообщения на ваш адрес. Если входящие от Telegram не проходят (таймауты доставки, блокировки на уровне сети хоста), переключите приём на «Фоновый опрос» в карточке интеграции: вебхук будет удалён, а системная очередь (Horizon) начнёт опрашивать getUpdates через сохранённый SOCKS5-прокси. Это исходящие запросы вашей Базы — они работают там же, где работает отправка ответов.

Опрос выполняется цепочкой фоновых задач: каждый job получает одну порцию сообщений, пишет их во «Взаимодействия» и перезапускается. Сообщения приходят почти мгновенно. Признак жизни — строка «Последний опрос: …» в карточке подключения. Переключиться обратно на webhook можно в любой момент тем же переключателем.

#Проверка подключения

После сохранения подключения можно нажать «Проверить» — система запросит Telegram API снова через прокси и обновит статус. Если токен стал недействительным (бот удалён, токен отозван) или прокси недоступен, статус сменится на «Ошибка», и появится текст ошибки.

#Валидация токена

  • Формат токена — цифры:буквы/цифры/_/-, не короче 20 символов после двоеточия.
  • Пробелы по краям отбрасываются автоматически при сохранении.
  • Если формат неверный — сохранение будет отклонено до запроса к Telegram API.

Прокси обязателен в РФ

Без SOCKS5 прокси подключение из РФ завершится ошибкой Connection timed out. Убедитесь что прокси работает и доступен с вашего сервера.
При успешном подключении в карточке интеграции виден botUsername — это подтверждение, что бот существует и доступен. Учётные данные (токен и прокси) не показываются — только флаг hasCredentials.

Диагностика

Если подключение не проходит — проверьте: работает ли прокси (например, через curl --socks5-hostname), указан ли он в формате socks5:// или socks5h://, и что сервер Базы доступен снаружи по HTTPS. Секретный токен хранится в настройках подключения и не возвращается API — при «Переустановке вебхука» он меняется автоматически.