Tài khoản & Cài đặt

API chỉ đọc

API chỉ đọc

Metricgram cung cấp API chỉ đọc cơ bản để công cụ bên ngoài có thể đọc dữ liệu nhóm mà không cần truy cập bảng điều khiển.

Beta: API hiện đang trong giai đoạn thử nghiệm và khả dụng từ gói Pro trở lên.

Tạo token

Vào Cài đặt, mở phần Token API, chọn nhóm rồi nhấn Tạo token. Hãy sao chép token ngay vì token chỉ hiển thị một lần.

Mỗi token được liên kết với một nhóm. Hiện tại bạn có thể có một token đang hoạt động cho mỗi nhóm và có thể thu hồi bất cứ lúc nào.

Xác thực

curl -H "Authorization: Bearer TOKEN_API_CUA_BAN" \
  "https://metricgram.com/api/v1/members"

Phản hồi thành công được trả về ở định dạng JSON.

Mỗi token bị giới hạn 60 yêu cầu mỗi giờ.

GET /api/v1/members

Trả về thành viên của nhóm gắn với token.

Tham số hỗ trợ:

  • status: all, active, inactive, left hoặc unbaned
  • admin: true hoặc false
  • is_bot: true hoặc false. Tham số này chỉ lọc các giá trị boolean; giá trị chưa biết (null) chỉ xuất hiện khi bạn không dùng bộ lọc này.
  • query: tìm theo Telegram ID, username hoặc tên
  • limit: mặc định 100, tối đa 500
  • page: mặc định 1
  • include_email: true hoặc false. Mặc định: false. Khi là true, Metricgram ưu tiên email của subscriber, sau đó dùng email lưu trong bản ghi thành viên của nhóm. Có thể là null.

Ví dụ:

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"

Ví dụ phản hồi 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": "Nhóm của tôi",
    "page": 1,
    "limit": 100,
    "count": 1,
    "has_more": false,
    "filters": {
      "status": "active"
    }
  }
}

Các trường phản hồi chính:

  • telegram_id: ID Telegram dạng văn bản. Có thể là null nếu Metricgram chưa lưu dữ liệu này.
  • username, first_name và language_code: dữ liệu công khai của Telegram. Có thể là null.
  • is_bot: true, false hoặc null nếu Telegram chưa cung cấp giá trị này.
  • status: active, inactive, left, unbaned hoặc null nếu chưa lưu trạng thái.
  • admin: true hoặc false.
  • joined_at: ngày tham gia theo định dạng ISO 8601, hoặc null.
  • email: chỉ được trả về khi include_email=true. Metricgram ưu tiên email của subscriber, sau đó dùng email lưu trong bản ghi thành viên của nhóm. Có thể là null.
  • meta: dữ liệu phân trang và bộ lọc của yêu cầu.

GET /api/v1/active_users

Trả về thành viên không phải quản trị viên có tin nhắn hoặc phản ứng được ghi nhận trong khoảng ngày đã chọn. Chủ sở hữu nhóm không nằm trong danh sách này. Kết quả được sắp xếp theo hoạt động giảm dần: trước tiên theo activity_count, sau đó theo last_activity_at.

Tham số hỗ trợ:

  • start_date: ngày bắt đầu theo định dạng YYYY-MM-DD. Mặc định: 30 ngày trước.
  • end_date: ngày kết thúc theo định dạng YYYY-MM-DD. Mặc định: hôm nay.
  • limit: mặc định 100, tối đa 500
  • page: mặc định 1
  • include_email: true hoặc false. Mặc định: false. Khi là true, Metricgram ưu tiên email của subscriber, sau đó dùng email lưu trong bản ghi thành viên của nhóm. Có thể là null.

Ví dụ:

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"

Ví dụ phản hồi 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": "Nhóm của tôi",
    "start_date": "2026-04-01",
    "end_date": "2026-04-30",
    "page": 1,
    "limit": 100,
    "count": 1,
    "has_more": false
  }
}

Các trường phản hồi chính:

  • telegram_id: ID Telegram dạng văn bản. Có thể là null nếu Metricgram chưa lưu dữ liệu này.
  • username, first_name và language_code: dữ liệu công khai của Telegram. Có thể là null.
  • is_bot: true, false hoặc null nếu Telegram chưa cung cấp giá trị này.
  • member_status: cùng giá trị văn bản với status trong /api/v1/members; có thể là null nếu chưa lưu trạng thái.
  • admin: true hoặc false; trong endpoint này thường là false vì quản trị viên bị loại trừ.
  • joined_at: ngày tham gia theo định dạng ISO 8601, hoặc null.
  • email: chỉ được trả về khi include_email=true. Metricgram ưu tiên email của subscriber, sau đó dùng email lưu trong bản ghi thành viên của nhóm. Có thể là null.
  • message_count, reaction_count và activity_count: bộ đếm số nguyên chỉ được tính trong khoảng ngày đã chọn, không phải toàn bộ lịch sử của người dùng. activity_count là message_count + reaction_count.
  • last_message_at và last_reaction_at: ngày theo định dạng ISO 8601, hoặc null nếu không có loại hoạt động đó.
  • last_activity_at: ngày của hoạt động gần nhất được ghi nhận theo định dạng ISO 8601.
  • meta: dữ liệu nhóm, khoảng ngày và phân trang của yêu cầu.

GET /api/v1/subscriber_health

Trả về cùng dữ liệu như bảng Sức khỏe người đăng ký: người đăng ký đang hoạt động đã liên kết, hoạt động gần đây, tín hiệu rủi ro, các lần gia hạn sắp tới và phân tích theo gói.

Theo mặc định, endpoint dùng cùng khoảng thời gian như bảng: 30 ngày cho hoạt động và 14 ngày cho các lần gia hạn sắp tới. Nếu thay đổi các tham số này, kết quả có thể không khớp hoàn toàn với bảng.

Tham số hỗ trợ:

  • activity_days: số ngày dùng cho hoạt động gần đây. Mặc định 30, tối đa 365; giá trị lớn hơn 365 sẽ được giới hạn về 365.
  • renewal_days: số ngày dùng cho các lần gia hạn sắp tới. Mặc định 14, tối đa 90; giá trị lớn hơn 90 sẽ được giới hạn về 90.
  • include_email: true hoặc false. Mặc định: false. Khi true, người đăng ký có rủi ro sẽ bao gồm email lưu trong subscription. Có thể là null.

Ví dụ:

curl -G "https://metricgram.com/api/v1/subscriber_health" \
  -H "Authorization: Bearer TOKEN_API_CUA_BAN" \
  --data-urlencode "activity_days=30" \
  --data-urlencode "renewal_days=14" \
  --data-urlencode "include_email=true"

Ví dụ phản hồi 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 hằng tháng", "29 EUR / tháng"],
        "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 hằng tháng", "29 EUR / tháng"],
        "active_count": 12,
        "engaged_count": 9,
        "at_risk_count": 2,
        "engaged_percentage": 75,
        "at_risk_percentage": 17
      }
    ]
  },
  "meta": {
    "group_id": 42,
    "group_title": "Nhóm của tôi"
  }
}

Trường chính:

  • total_subscribers: người đăng ký đang hoạt động đã liên kết được đưa vào phép tính.
  • activity_range / previous_activity_range: khoảng hoạt động hiện tại và trước đó.
  • metrics: các bộ đếm và tỷ lệ phần trăm tóm tắt.
  • at_risk_subscribers: người đăng ký có tín hiệu rủi ro; risk_indicators có thể là no_activity, activity_drop hoặc canceled; risk_level có thể là low, medium hoặc high.
  • plan_rows: người đăng ký đang hoạt động đã liên kết được nhóm theo gói subscription.
  • email: chỉ trả về trong at_risk_subscribers khi include_email=true.

Bài viết này có hữu ích không?

Thiết Lập Bot Tùy Chỉnh

Quản lý nhóm Telegram của bạn thông minh hơn

Dùng thử Metricgram miễn phí