账户与设置

只读 API

只读 API

Metricgram 提供基础的只读 API，外部工具可以在不访问仪表盘的情况下读取群组数据。

Beta： 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、用户名或名字搜索
  • limit：默认 100，最大 500
  • page：默认 1
  • include_email：true 或 false。默认：false。为 true 时，Metricgram 会先使用订阅邮箱；如果没有，则使用群组成员记录中保存的邮箱。可能为 null。

示例：

curl -G "https://metricgram.com/api/v1/members" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --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：文本形式的 Telegram ID。如果 Metricgram 没有保存该值，可能为 null。
  • username、first_name 和 language_code：Telegram 公开数据，可能为 null。
  • is_bot：true、false，或在 Telegram 未提供该值时为 null。
  • status：active、inactive、left、unbaned，或在未保存状态时为 null。
  • admin：true 或 false。
  • joined_at：ISO 8601 格式的加入时间，或 null。
  • email：仅在 include_email=true 时返回。Metricgram 会先使用订阅邮箱；如果没有，则使用群组成员记录中保存的邮箱。可能为 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 会先使用订阅邮箱；如果没有，则使用群组成员记录中保存的邮箱。可能为 null。

示例：

curl -G "https://metricgram.com/api/v1/active_users" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --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：文本形式的 Telegram ID。如果 Metricgram 没有保存该值，可能为 null。
  • username、first_name 和 language_code：Telegram 公开数据，可能为 null。
  • is_bot：true、false，或在 Telegram 未提供该值时为 null。
  • member_status：与 /api/v1/members 中的 status 文本取值相同；未保存状态时可能为 null。
  • admin：true 或 false；由于此端点会排除管理员，通常为 false。
  • joined_at：ISO 8601 格式的加入时间，或 null。
  • email：仅在 include_email=true 时返回。Metricgram 会先使用订阅邮箱；如果没有，则使用群组成员记录中保存的邮箱。可能为 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 时，风险订阅者会包含订阅记录中保存的邮箱。可能为 null。

示例：

curl -G "https://metricgram.com/api/v1/subscriber_health" \
  -H "Authorization: Bearer 你的_API_TOKEN" \
  --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: 仅在 include_email=true 时出现在 at_risk_subscribers 中。

这篇文章对您有帮助吗？

设置自定义机器人

更智能地管理您的 Telegram 群组

免费试用 Metricgram