Akun & Pengaturan

API hanya-baca

API hanya-baca

Metricgram menyediakan API dasar hanya-baca agar alat eksternal dapat membaca data grup tanpa mengakses dasbor.

Beta: API saat ini masih dalam tahap pengujian dan tersedia mulai dari paket Pro.

Membuat token

Buka Pengaturan, masuk ke Token API, pilih grup, lalu klik Buat token. Salin token segera karena hanya ditampilkan satu kali.

Setiap token terhubung ke satu grup. Saat ini Anda dapat memiliki satu token aktif per grup dan mencabutnya kapan saja.

Autentikasi

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

Respons yang berhasil dikembalikan dalam format JSON.

Setiap token dibatasi hingga 60 permintaan per jam.

GET /api/v1/members

Mengembalikan anggota grup yang terkait dengan token.

Parameter yang tersedia:

  • status: all, active, inactive, left, atau unbaned
  • admin: true atau false
  • is_bot: true atau false. Parameter ini hanya memfilter nilai boolean; nilai yang tidak diketahui (null) hanya muncul saat filter ini tidak digunakan.
  • query: cari berdasarkan ID Telegram, username, atau nama depan
  • limit: default 100, maksimum 500
  • page: default 1
  • include_email: true atau false. Default: false. Jika true, Metricgram memakai email subscriber terlebih dahulu, lalu email yang tersimpan pada data anggota grup. Nilainya bisa null.

Contoh:

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"

Contoh respons 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": "Grup saya",
    "page": 1,
    "limit": 100,
    "count": 1,
    "has_more": false,
    "filters": {
      "status": "active"
    }
  }
}

Field utama respons:

  • telegram_id: ID Telegram sebagai teks. Bisa null jika Metricgram tidak menyimpannya.
  • username, first_name, dan language_code: data publik Telegram. Bisa null.
  • is_bot: true, false, atau null jika Telegram tidak memberikan nilai tersebut.
  • status: active, inactive, left, unbaned, atau null jika status belum tersimpan.
  • admin: true atau false.
  • joined_at: tanggal bergabung dalam format ISO 8601, atau null.
  • email: hanya dikembalikan saat include_email=true. Metricgram memakai email subscriber terlebih dahulu, lalu email yang tersimpan pada data anggota grup. Nilainya bisa null.
  • meta: data pagination dan filter untuk request.

GET /api/v1/active_users

Mengembalikan anggota non-admin dengan pesan atau reaksi yang tercatat dalam rentang tanggal yang dipilih. Pemilik grup dikecualikan dari daftar ini. Hasil diurutkan berdasarkan aktivitas menurun: pertama activity_count, lalu last_activity_at.

Parameter yang tersedia:

  • start_date: tanggal mulai dalam format YYYY-MM-DD. Default: 30 hari lalu.
  • end_date: tanggal akhir dalam format YYYY-MM-DD. Default: hari ini.
  • limit: default 100, maksimum 500
  • page: default 1
  • include_email: true atau false. Default: false. Jika true, Metricgram memakai email subscriber terlebih dahulu, lalu email yang tersimpan pada data anggota grup. Nilainya bisa null.

Contoh:

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"

Contoh respons 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": "Grup saya",
    "start_date": "2026-04-01",
    "end_date": "2026-04-30",
    "page": 1,
    "limit": 100,
    "count": 1,
    "has_more": false
  }
}

Field utama respons:

  • telegram_id: ID Telegram sebagai teks. Bisa null jika Metricgram tidak menyimpannya.
  • username, first_name, dan language_code: data publik Telegram. Bisa null.
  • is_bot: true, false, atau null jika Telegram tidak memberikan nilai tersebut.
  • member_status: nilai teks yang sama seperti status di /api/v1/members; bisa null jika status belum tersimpan.
  • admin: true atau false; di endpoint ini biasanya false karena admin dikecualikan.
  • joined_at: tanggal bergabung dalam format ISO 8601, atau null.
  • email: hanya dikembalikan saat include_email=true. Metricgram memakai email subscriber terlebih dahulu, lalu email yang tersimpan pada data anggota grup. Nilainya bisa null.
  • message_count, reaction_count, dan activity_count: penghitung bilangan bulat yang dihitung hanya dalam rentang tanggal yang dipilih, bukan seluruh riwayat pengguna. activity_count adalah message_count + reaction_count.
  • last_message_at dan last_reaction_at: tanggal dalam format ISO 8601, atau null jika tidak ada aktivitas jenis tersebut.
  • last_activity_at: tanggal aktivitas terakhir yang tercatat dalam format ISO 8601.
  • meta: data grup, rentang tanggal, dan pagination untuk request.

GET /api/v1/subscriber_health

Mengembalikan data yang sama dengan panel Kesehatan pelanggan: subscriber aktif yang tertaut, aktivitas terbaru, sinyal risiko, perpanjangan mendatang, dan rincian per paket.

Secara default, endpoint ini memakai rentang yang sama seperti panel: 30 hari untuk aktivitas dan 14 hari untuk perpanjangan mendatang. Jika parameter ini diubah, hasilnya mungkin tidak sama persis dengan panel.

Parameter yang didukung:

  • activity_days: jumlah hari untuk aktivitas terbaru. Default 30, maksimum 365; nilai di atas 365 akan dibatasi menjadi 365.
  • renewal_days: jumlah hari untuk perpanjangan mendatang. Default 14, maksimum 90; nilai di atas 90 akan dibatasi menjadi 90.
  • include_email: true atau false. Default: false. Jika true, subscriber berisiko menyertakan email yang tersimpan pada langganan. Nilainya bisa null.

Contoh:

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

Contoh respons 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 bulanan", "29 EUR / bulan"],
        "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 bulanan", "29 EUR / bulan"],
        "active_count": 12,
        "engaged_count": 9,
        "at_risk_count": 2,
        "engaged_percentage": 75,
        "at_risk_percentage": 17
      }
    ]
  },
  "meta": {
    "group_id": 42,
    "group_title": "Grup saya"
  }
}

Field utama:

  • total_subscribers: subscriber aktif tertaut yang dihitung.
  • activity_range / previous_activity_range: rentang aktivitas saat ini dan sebelumnya.
  • metrics: ringkasan jumlah dan persentase.
  • at_risk_subscribers: subscriber dengan sinyal risiko; risk_indicators dapat berupa no_activity, activity_drop, atau canceled; risk_level dapat berupa low, medium, atau high.
  • plan_rows: subscriber aktif tertaut yang dikelompokkan berdasarkan paket langganan.
  • email: hanya dikembalikan di at_risk_subscribers saat include_email=true.

Error yang mungkin muncul: 401 unauthorized, 403 forbidden, 400 invalid_date_range, dan 429 rate_limited.

Apakah artikel ini membantu?

Menyiapkan Bot Kustom

Kelola grup Telegram Anda lebih cerdas

Coba Metricgram gratis