Salt okunur API

Salt okunur API

Metricgram, harici araçların panele erişmeden grup verilerini okuyabilmesi için temel bir salt okunur API sunar.

Beta: API şu anda test aşamasındadır ve Pro planından itibaren kullanılabilir.

Token oluşturma

Ayarlar bölümüne gidin, API tokenleri alanını açın, grubu seçin ve Token oluştur düğmesine tıklayın. Token yalnızca bir kez gösterilir, bu yüzden hemen kopyalayın.

Her token tek bir gruba bağlıdır. Şimdilik grup başına bir aktif token oluşturabilir ve istediğiniz zaman iptal edebilirsiniz.

Kimlik doğrulama

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

Başarılı yanıtlar JSON formatında döner.

Her token saatte 60 istek ile sınırlıdır.

GET /api/v1/members

Token ile ilişkili grubun üyelerini döndürür.

Kullanılabilir parametreler:

• status: all, active, inactive, left veya unbaned
• admin: true veya false
• is_bot: true veya false. Bu parametre yalnızca boolean değerleri filtreler; bilinmeyen değerler (null) sadece bu filtre kullanılmadığında döner.
• query: Telegram ID, kullanıcı adı veya ada göre arama
• limit: varsayılan 100, maksimum 500
• page: varsayılan 1
• include_email: true veya false. Varsayılan: false. true olduğunda Metricgram önce abonelik email adresini, yoksa grup üyesi kaydındaki email adresini kullanır. null olabilir.

Örnek:

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 yanıt örneği:

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

Başlıca yanıt alanları:

• telegram_id: Metin olarak Telegram ID’si. Metricgram’da kayıtlı değilse null olabilir.
• username, first_name ve language_code: herkese açık Telegram verileri. null olabilir.
• is_bot: Telegram bu değeri göndermediyse true, false veya null olabilir.
• status: active, inactive, left, unbaned veya kayıtlı durum yoksa null.
• admin: true veya false.
• joined_at: ISO 8601 formatında katılma tarihi veya null.
• email: yalnızca include_email=true olduğunda döner. Metricgram önce abonelik email adresini, yoksa grup üyesi kaydındaki email adresini kullanır. null olabilir.
• meta: isteğin sayfalama ve filtre bilgileri.

GET /api/v1/active_users

Seçilen tarih aralığında mesajı veya reaksiyonu kaydedilmiş yönetici olmayan üyeleri döndürür. Grup sahibi bu listeye dahil edilmez. Sonuçlar aktiviteye göre azalan sırada döner: önce activity_count, sonra last_activity_at.

Kullanılabilir parametreler:

• start_date: YYYY-MM-DD formatında başlangıç tarihi. Varsayılan: 30 gün önce.
• end_date: YYYY-MM-DD formatında bitiş tarihi. Varsayılan: bugün.
• limit: varsayılan 100, maksimum 500
• page: varsayılan 1
• include_email: true veya false. Varsayılan: false. true olduğunda Metricgram önce abonelik email adresini, yoksa grup üyesi kaydındaki email adresini kullanır. null olabilir.

Örnek:

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 yanıt örneği:

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

Başlıca yanıt alanları:

• telegram_id: Metin olarak Telegram ID’si. Metricgram’da kayıtlı değilse null olabilir.
• username, first_name ve language_code: herkese açık Telegram verileri. null olabilir.
• is_bot: Telegram bu değeri göndermediyse true, false veya null olabilir.
• member_status: /api/v1/members içindeki status ile aynı metin değerlerine sahiptir; kayıtlı durum yoksa null olabilir.
• admin: true veya false; bu endpoint’te yöneticiler hariç tutulduğu için normalde false olur.
• joined_at: ISO 8601 formatında katılma tarihi veya null.
• email: yalnızca include_email=true olduğunda döner. Metricgram önce abonelik email adresini, yoksa grup üyesi kaydındaki email adresini kullanır. null olabilir.
• message_count, reaction_count ve activity_count: kullanıcının toplam geçmişi değil, yalnızca seçilen tarih aralığı içinde hesaplanan tam sayı sayaçlarıdır. activity_count, message_count + reaction_count değeridir.
• last_message_at ve last_reaction_at: ISO 8601 formatında tarih veya bu tür aktivite yoksa null.
• last_activity_at: kaydedilen son aktivitenin ISO 8601 formatındaki tarihi.
• meta: isteğin grup, tarih aralığı ve sayfalama bilgileri.

GET /api/v1/subscriber_health

Abone sağlığı panelindeki aynı verileri döndürür: bağlı aktif aboneler, yakın aktivite, risk sinyalleri, yaklaşan yenilemeler ve plana göre dağılım.

Varsayılan olarak panelle aynı pencereleri kullanır: aktivite için 30 gün, yaklaşan yenilemeler için 14 gün. Bu parametreleri değiştirirseniz sonuçlar panelle tam olarak eşleşmeyebilir.

Desteklenen parametreler:

• activity_days: yakın aktivite için kullanılan gün sayısı. Varsayılan 30, maksimum 365; 365 üzerindeki değerler 365 ile sınırlandırılır.
• renewal_days: yaklaşan yenilemeler için kullanılan gün sayısı. Varsayılan 14, maksimum 90; 90 üzerindeki değerler 90 ile sınırlandırılır.
• include_email: true veya false. Varsayılan: false. true olduğunda risk altındaki aboneler abonelikte kayıtlı email adresini içerir. null olabilir.

Örnek:

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

Örnek JSON yanıtı:

{
  "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": ["Aylık Pro", "29 EUR / ay"],
        "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": ["Aylık Pro", "29 EUR / ay"],
        "active_count": 12,
        "engaged_count": 9,
        "at_risk_count": 2,
        "engaged_percentage": 75,
        "at_risk_percentage": 17
      }
    ]
  },
  "meta": {
    "group_id": 42,
    "group_title": "Grubum"
  }
}

Başlıca alanlar:

• total_subscribers: hesaplamaya dahil edilen bağlı aktif aboneler.
• activity_range / previous_activity_range: mevcut ve önceki aktivite pencereleri.
• metrics: özet sayaçlar ve yüzdeler.
• at_risk_subscribers: risk sinyali olan aboneler; risk_indicators değeri no_activity, activity_drop veya canceled; risk_level değeri low, medium veya high olabilir.
• plan_rows: abonelik planına göre gruplanmış bağlı aktif aboneler.
• email: yalnızca include_email=true olduğunda at_risk_subscribers içinde döner.

Olası hatalar: 401 unauthorized, 403 forbidden, 400 invalid_date_range ve 429 rate_limited.