API: Каналы

Эндпоинты для работы с Telegram-каналами.

Список каналов

GET /api/channels

Ответ:

[
  {
    "id": 1,
    "title": "My Channel",
    "username": "mychannel",
    "member_count": 5400,
    "bot_is_admin": true,
    "is_active": true
  }
]

Сводка по всем каналам

GET /api/channels/summary

Ответ:

{
  "totalChannels": 3,
  "activeChannels": 2,
  "totalSubscribers": 15000,
  "totalGrowth30d": 420
}

Пересечение аудиторий

GET /api/channels/overlap?channel_a=1&channel_b=2

Query параметры: channel_a, channel_b — ID каналов (должны быть разными)

Ответ:

{
  "overlap": 320,
  "overlap_pct": 12.5,
  "channel_a_unique": 2200,
  "channel_b_unique": 1800,
  "total_a": 2520,
  "total_b": 2120,
  "channel_a": { "id": 1, "title": "Channel A", "username": "chan_a" },
  "channel_b": { "id": 2, "title": "Channel B", "username": "chan_b" }
}

Отправить PNG пересечения

POST /api/channels/send-overlap-image

Body:

{
  "channelA": 1,
  "channelB": 2
}

Генерирует и отправляет PNG-изображение пересечения аудиторий в бот-чат.

Ответ:

{ "ok": true }

Отправить PNG сравнения каналов

POST /api/channels/send-compare-image

Body:

{
  "channelIds": [1, 2, 3]
}

Поддерживается 2–3 канала. Генерирует и отправляет PNG-изображение сравнения в бот-чат.

Ответ:

{ "ok": true }

Отправить PNG статистики канала

POST /api/channels/:id/send-image

Генерирует и отправляет PNG-изображение со статистикой канала за 30 дней в бот-чат.

Ответ:

{ "ok": true }

Информация о канале

GET /api/channels/:id

Ответ:

{
  "id": 1,
  "title": "My Channel",
  "username": "mychannel",
  "member_count": 5400,
  "bot_is_admin": true,
  "is_active": true,
  "created_at": "2025-01-01T00:00:00Z"
}

Подписчики

GET /api/channels/:id/subscribers?period=7d

Ответ:

{
  "period": "7d",
  "totalChange": 120,
  "avgPerDay": 17.14,
  "trend": "growing",
  "data": [
    { "date": "2025-01-15T00:00:00Z", "count": 5280, "change": 0 },
    { "date": "2025-01-16T00:00:00Z", "count": 5300, "change": 20 }
  ]
}

События (вступления / выходы)

GET /api/channels/:id/members?period=7d&type=join

Query параметры: period, type (join | leave | all)

Ответ:

{
  "period": "7d",
  "joins": 150,
  "leaves": 30,
  "netGrowth": 120,
  "events": [
    {
      "id": 1,
      "event_type": "join",
      "event_at": "2025-01-15T10:30:00Z",
      "user_telegram_id": 123456
    }
  ]
}

Посты

GET /api/channels/:id/posts?period=7d&sort=views

Query параметры: period, sort (views | date | engagement)

Ответ:

{
  "period": "7d",
  "totalPosts": 15,
  "avgViews": 3200,
  "avgEngagement": 62.4,
  "posts": [
    {
      "message_id": 100,
      "text_preview": "Новый пост...",
      "views": 4500,
      "forwards": 12,
      "reactions_total": 85,
      "post_date": "2025-01-15T12:00:00Z",
      "engagement_rate": 83.33
    }
  ]
}

Детали поста

GET /api/channels/:id/posts/:msgId

Ответ:

{
  "message_id": 100,
  "text_preview": "Новый пост...",
  "views": 4500,
  "forwards": 12,
  "reactions_total": 85,
  "post_date": "2025-01-15T12:00:00Z",
  "engagement_rate": 83.33
}

Лучшее время постинга

GET /api/channels/:id/best-time

Ответ:

{
  "bestHour": 14,
  "bestDay": 2,
  "heatmap": [{ "day": 1, "hour": 14, "avgViews": 3500 }]
}

Рост

GET /api/channels/:id/growth?period=30d

Ответ:

{
  "period": "30d",
  "growth": 420,
  "growthPercent": 8.44,
  "dataPoints": 30
}

Атрибуция

GET /api/channels/:id/attributions

Ответ:

[
  {
    "link_id": 1,
    "link_code": "x7k2m1",
    "link_title": "Промо",
    "attributedJoins": 45
  }
]

Данные для сравнения

GET /api/channels/:id/compare?period=30d

Ответ:

{
  "id": 1,
  "title": "My Channel",
  "username": "mychannel",
  "member_count": 5400,
  "subscriberChange24h": 15,
  "avgViews": 3200,
  "er": 62.4,
  "subscribers": [{ "date": "2025-01-15T00:00:00Z", "count": 5280 }]
}

Воронка

GET /api/channels/:id/funnel?period=30d

Ответ:

{
  "impressions": 50000,
  "clicks": 2000,
  "joins": 150,
  "retention7d": 120,
  "conversionRate": 7.5
}

Удержание

GET /api/channels/:id/retention?period=30d

Ответ:

{
  "cohorts": [
    {
      "week": "2025-W03",
      "joined": 50,
      "retained": [50, 45, 40, 38]
    }
  ]
}

Аналитика реакций

GET /api/channels/:id/reactions-analytics?period=30d

Ответ:

{
  "totalReactions": 1200,
  "postsWithReactions": 12,
  "avgReactionsPerPost": 100,
  "reactionRate": 1.85,
  "emojiBreakdown": [
    { "emoji": "👍", "count": 500, "percentage": 41.67 },
    { "emoji": "❤️", "count": 300, "percentage": 25.0 }
  ],
  "dailyTrend": [{ "date": "2025-01-15", "total": 85, "breakdown": { "👍": 40, "❤️": 25 } }],
  "topPosts": [{ "message_id": 100, "text_preview": "...", "reactions_total": 150 }]
}

Экспорт CSV

GET /api/channels/:id/export?period=30d

Ответ:

{
  "filename": "mychannel_30d.csv",
  "content": "section,date,value,detail\nsubscribers,2025-01-15T00:00:00Z,5280,\n..."
}

Query параметры

• period — 1d | 7d | 30d | 90d | 1y | all
• sort — views | date | engagement (для постов)
• type — join | leave | all (для событий)

Для всех эндпоинтов используйте заголовок Authorization: Bearer <token>.