Аккаунт и настройки

API только для чтения

API только для чтения

В Metricgram есть базовый API только для чтения, чтобы внешние инструменты могли получать данные группы без доступа к панели управления.

Бета: API сейчас находится в тестовом режиме и доступен начиная с тарифа Pro.

Создание токена

Откройте Настройки, перейдите в раздел API-токены, выберите группу и нажмите Создать токен. Скопируйте токен сразу: он показывается только один раз.

Каждый токен привязан к одной группе. Сейчас можно иметь один активный токен на группу и отозвать его в любой момент.

Аутентификация

curl -H "Authorization: Bearer ВАШ_API_ТОКЕН" \
  "https://metricgram.com/api/v1/members"

Успешные ответы возвращаются в формате JSON.

Каждый токен ограничен 60 запросами в час.

GET /api/v1/members

Возвращает участников группы, связанной с токеном.

Доступные параметры:

  • status: all, active, inactive, left или unbaned
  • admin: true или false
  • is_bot: true или false. Этот параметр фильтрует только булевы значения; неизвестные значения (null) возвращаются только если фильтр не используется.
  • query: поиск по Telegram ID, username или имени
  • limit: по умолчанию 100, максимум 500
  • page: по умолчанию 1
  • include_email: true или false. По умолчанию: false. Если true, Metricgram сначала использует email подписки, затем email, сохраненный в записи участника группы. Может быть null.

Пример:

curl -G "https://metricgram.com/api/v1/members" \
  -H "Authorization: Bearer ВАШ_API_ТОКЕН" \
  --data-urlencode "status=active" \
  --data-urlencode "limit=100" \
  --data-urlencode "include_email=true" \
  --data-urlencode "page=1"

Пример ответа JSON:

{
  "data": [
    {
      "telegram_id": "123456789",
      "username": "ana",
      "first_name": "Ana",
      "language_code": "es",
      "is_bot": false,
      "status": "active",
      "joined_at": "2026-04-10T12:30:00Z",
      "admin": false,
      "email": "ana@example.com"
    }
  ],
  "meta": {
    "group_id": 42,
    "group_title": "Моя группа",
    "page": 1,
    "limit": 100,
    "count": 1,
    "has_more": false,
    "filters": {
      "status": "active"
    }
  }
}

Основные поля ответа:

  • telegram_id: ID Telegram в виде строки. Может быть null, если Metricgram не сохранил это значение.
  • username, first_name и language_code: публичные данные Telegram. Могут быть null.
  • is_bot: true, false или null, если Telegram не передал это значение.
  • status: active, inactive, left, unbaned или null, если статус не сохранен.
  • admin: true или false.
  • joined_at: дата входа в формате ISO 8601 или null.
  • email: возвращается только при include_email=true. Metricgram сначала использует email подписки, затем email, сохраненный в записи участника группы. Может быть null.
  • meta: данные пагинации и фильтров запроса.

GET /api/v1/active_users

Возвращает неадминистраторов с сообщениями или реакциями за выбранный диапазон дат. Владелец группы исключается из этого списка. Результаты отсортированы по убыванию активности: сначала по activity_count, затем по last_activity_at.

Доступные параметры:

  • start_date: начальная дата в формате YYYY-MM-DD. По умолчанию: 30 дней назад.
  • end_date: конечная дата в формате YYYY-MM-DD. По умолчанию: сегодня.
  • limit: по умолчанию 100, максимум 500
  • page: по умолчанию 1
  • include_email: true или false. По умолчанию: false. Если true, Metricgram сначала использует email подписки, затем email, сохраненный в записи участника группы. Может быть null.

Пример:

curl -G "https://metricgram.com/api/v1/active_users" \
  -H "Authorization: Bearer ВАШ_API_ТОКЕН" \
  --data-urlencode "start_date=2026-04-01" \
  --data-urlencode "end_date=2026-04-30" \
  --data-urlencode "limit=100" \
  --data-urlencode "include_email=true" \
  --data-urlencode "page=1"

Пример ответа JSON:

{
  "data": [
    {
      "telegram_id": "123456789",
      "username": "ana",
      "first_name": "Ana",
      "language_code": "es",
      "is_bot": null,
      "member_status": "active",
      "admin": false,
      "joined_at": "2026-04-10T12:30:00Z",
      "email": "ana@example.com",
      "message_count": 18,
      "reaction_count": 4,
      "activity_count": 22,
      "last_message_at": "2026-04-30T19:15:00Z",
      "last_reaction_at": null,
      "last_activity_at": "2026-04-30T19:15:00Z"
    }
  ],
  "meta": {
    "group_id": 42,
    "group_title": "Моя группа",
    "start_date": "2026-04-01",
    "end_date": "2026-04-30",
    "page": 1,
    "limit": 100,
    "count": 1,
    "has_more": false
  }
}

Основные поля ответа:

  • telegram_id: ID Telegram в виде строки. Может быть null, если Metricgram не сохранил это значение.
  • username, first_name и language_code: публичные данные Telegram. Могут быть null.
  • is_bot: true, false или null, если Telegram не передал это значение.
  • member_status: те же текстовые значения, что и status в /api/v1/members; может быть null, если статус не сохранен.
  • admin: true или false; в этом эндпоинте обычно false, потому что администраторы исключаются.
  • joined_at: дата входа в формате ISO 8601 или null.
  • email: возвращается только при include_email=true. Metricgram сначала использует email подписки, затем email, сохраненный в записи участника группы. Может быть null.
  • message_count, reaction_count и activity_count: целочисленные счетчики, рассчитанные только за выбранный диапазон дат, а не за всю историю пользователя. activity_count равен message_count + reaction_count.
  • last_message_at и last_reaction_at: дата в формате ISO 8601 или null, если активности этого типа не было.
  • last_activity_at: дата последней зарегистрированной активности в формате ISO 8601.
  • meta: данные группы, диапазона дат и пагинации запроса.

GET /api/v1/subscriber_health

Возвращает те же данные, что и панель здоровья подписчиков: активные привязанные подписчики, недавняя активность, сигналы риска, ближайшие продления и разбивка по планам.

По умолчанию используются те же окна, что и в панели: 30 дней для активности и 14 дней для ближайших продлений. Если изменить эти параметры, результаты могут не совпадать с панелью полностью.

Поддерживаемые параметры:

  • activity_days: количество дней для недавней активности. По умолчанию 30, максимум 365; значения выше 365 ограничиваются до 365.
  • renewal_days: количество дней для ближайших продлений. По умолчанию 14, максимум 90; значения выше 90 ограничиваются до 90.
  • include_email: true или false. По умолчанию: false. Если true, подписчики в зоне риска включают email из записи подписки. Может быть null.

Пример:

curl -G "https://metricgram.com/api/v1/subscriber_health" \
  -H "Authorization: Bearer ВАШ_API_ТОКЕН" \
  --data-urlencode "activity_days=30" \
  --data-urlencode "renewal_days=14" \
  --data-urlencode "include_email=true"

Пример ответа JSON:

{
  "data": {
    "total_subscribers": 24,
    "activity_days": 30,
    "renewal_days": 14,
    "activity_range": { "start_date": "2026-04-01", "end_date": "2026-04-30" },
    "previous_activity_range": { "start_date": "2026-03-02", "end_date": "2026-03-31" },
    "compare_activity_drop": true,
    "metrics": {
      "engaged": { "count": 18, "percentage": 75 },
      "at_risk": { "count": 3, "percentage": 13 },
      "upcoming_renewals": { "count": 5, "percentage": 21 }
    },
    "at_risk_subscribers": [
      {
        "telegram_id": "123456789",
        "username": "ana",
        "first_name": "Ana",
        "language_code": "es",
        "is_bot": false,
        "plan_lines": ["Pro ежемесячно", "29 EUR / месяц"],
        "subscribed_until": "2026-05-08T10:00:00Z",
        "subscription_attention": "renews_on",
        "subscription_attention_days": 2,
        "risk_indicators": ["activity_drop"],
        "risk_score": 1,
        "risk_level": "low",
        "current_message_count": 2,
        "current_reaction_count": 0,
        "current_activity_count": 2,
        "previous_message_count": 12,
        "previous_reaction_count": 1,
        "previous_activity_count": 13,
        "email": "ana@example.com"
      }
    ],
    "plan_rows": [
      {
        "plan_lines": ["Pro ежемесячно", "29 EUR / месяц"],
        "active_count": 12,
        "engaged_count": 9,
        "at_risk_count": 2,
        "engaged_percentage": 75,
        "at_risk_percentage": 17
      }
    ]
  },
  "meta": {
    "group_id": 42,
    "group_title": "Моя группа"
  }
}

Основные поля:

  • total_subscribers: активные привязанные подписчики, включенные в расчет.
  • activity_range / previous_activity_range: текущий и предыдущий периоды активности.
  • metrics: сводные счетчики и проценты.
  • at_risk_subscribers: подписчики с сигналами риска; risk_indicators может быть no_activity, activity_drop или canceled; risk_level может быть low, medium или high.
  • plan_rows: активные привязанные подписчики, сгруппированные по плану подписки.
  • email: возвращается только внутри at_risk_subscribers, когда include_email=true.

Возможные ошибки: 401 unauthorized, 403 forbidden, 400 invalid_date_range и 429 rate_limited.

Была ли эта статья полезной?

Пользовательский бот

Управляйте группой Telegram эффективнее

Попробуйте Metricgram бесплатно