Контакты и диалоги

В разделе Контакты живёт всё, что бот узнал о пользователях, которые ему писали хоть раз.

Что записывается

Поле	Источник
external_user_id	from.id из апдейта Telegram / Max
username	from.username
first_name, last_name	from.first_name, from.last_name
is_premium	from.is_premium (Telegram Premium)
language_code	from.language_code
phone	если пользователь поделился контактом
last_seen_at	время последнего инкоминг-сообщения
source_value	UTM-источник (если был параметр в /start)
campaign_name	название кампании (см. UTM-источники)

Аватарки

MaxBotStat подгружает аватар Telegram через getUserProfilePhotos + getFile (или соответствующий метод Max). Аватары идут через бэкенд-прокси:

GET /api/avatars/contact/<botRef>/<userId>

Это сделано, чтобы:

• не светить токен бота во фронтенд;
• избежать mixed-content (Telegram CDN не всегда отдаёт HTTPS-картинки в нужном виде);
• кэшировать ответ (TTL 60 минут).

Диалоги

Раздел Диалоги показывает контакты в порядке последнего сообщения — как мессенджер. Кликаете по контакту → открывается полная история переписки (in / out стрелочками).

Поиск

Сверху списка — поле поиска. Ищем по:

• username,
• first_name / last_name,
• external_user_id,
• содержанию последнего сообщения.

Поиск работает по подстроке без регистра.

Открыть карточку контакта

В карточке контакта вы увидите:

• метаданные пользователя;
• источник (UTM) и кампанию;
• общее число сообщений (входящих / исходящих);
• intents (если настроены);
• кнопку Написать — отправить сообщение от имени бота.

Через REST API

curl "https://capybara.maxbotstat.ru/api/v1/bots/<botId>/contacts?limit=100&offset=0" \
     -H "X-API-Key: mbs_..."

Полная схема ответа: API → Контакты.

Диалоги через WebSocket

Кабинет MaxBotStat обновляет ленту диалогов в реальном времени через WebSocket. Если вы делаете собственный UI — можно подписаться на webhook-событие message.created и обновлять состояние у себя. См. Webhook-подписки.