Konto & Einstellungen

Nur-Lese-API

Nur-Lese-API

Metricgram bietet eine einfache Nur-Lese-API, damit externe Tools Gruppendaten abfragen können, ohne Zugriff auf das Dashboard zu erhalten.

Beta: Die API befindet sich derzeit in der Testphase und ist ab dem Pro-Plan verfügbar.

Token erstellen

Öffnen Sie Einstellungen, gehen Sie zu API-Tokens, wählen Sie die Gruppe und klicken Sie auf Token erstellen. Kopieren Sie den Token sofort, da er nur einmal angezeigt wird.

Jeder Token ist mit genau einer Gruppe verknüpft. Aktuell können Sie einen aktiven Token pro Gruppe erstellen und ihn jederzeit widerrufen.

Authentifizierung

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

Erfolgreiche Antworten werden im JSON-Format zurückgegeben.

Jeder Token ist auf 60 Anfragen pro Stunde begrenzt.

GET /api/v1/members

Gibt die Mitglieder der mit dem Token verbundenen Gruppe zurück.

Verfügbare Parameter:

  • status: all, active, inactive, left oder unbaned
  • admin: true oder false
  • is_bot: true oder false. Dieser Parameter filtert nur boolesche Werte; unbekannte Werte (null) werden nur zurückgegeben, wenn dieser Filter nicht verwendet wird.
  • query: Suche nach Telegram-ID, Username oder Vorname
  • limit: Standard 100, maximal 500
  • page: Standard 1
  • include_email: true oder false. Standard: false. Wenn true, verwendet Metricgram zuerst die E-Mail der Subscription und danach die im Gruppenmitglied gespeicherte E-Mail. Kann null sein.

Beispiel:

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"

Beispiel für eine JSON-Antwort:

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

Wichtige Antwortfelder:

  • telegram_id: Telegram-ID als Text. Kann null sein, wenn Metricgram sie nicht gespeichert hat.
  • username, first_name und language_code: öffentliche Telegram-Daten. Sie können null sein.
  • is_bot: true, false oder null, wenn Telegram diesen Wert nicht geliefert hat.
  • status: active, inactive, left, unbaned oder null, wenn kein Status gespeichert ist.
  • admin: true oder false.
  • joined_at: Beitrittsdatum im ISO-8601-Format oder null.
  • email: wird nur zurückgegeben, wenn include_email=true ist. Metricgram verwendet zuerst die E-Mail der Subscription und danach die im Gruppenmitglied gespeicherte E-Mail. Kann null sein.
  • meta: Paginierungs- und Filterdaten der Anfrage.

GET /api/v1/active_users

Gibt Nicht-Administratoren mit Nachrichten oder Reaktionen im ausgewählten Datumsbereich zurück. Der Gruppeninhaber wird aus dieser Liste ausgeschlossen. Die Ergebnisse sind absteigend nach Aktivität sortiert: zuerst nach activity_count, dann nach last_activity_at.

Verfügbare Parameter:

  • start_date: Startdatum im Format YYYY-MM-DD. Standard: vor 30 Tagen.
  • end_date: Enddatum im Format YYYY-MM-DD. Standard: heute.
  • limit: Standard 100, maximal 500
  • page: Standard 1
  • include_email: true oder false. Standard: false. Wenn true, verwendet Metricgram zuerst die E-Mail der Subscription und danach die im Gruppenmitglied gespeicherte E-Mail. Kann null sein.

Beispiel:

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"

Beispiel für eine JSON-Antwort:

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

Wichtige Antwortfelder:

  • telegram_id: Telegram-ID als Text. Kann null sein, wenn Metricgram sie nicht gespeichert hat.
  • username, first_name und language_code: öffentliche Telegram-Daten. Sie können null sein.
  • is_bot: true, false oder null, wenn Telegram diesen Wert nicht geliefert hat.
  • member_status: gleiche Textwerte wie status in /api/v1/members; kann null sein, wenn kein Status gespeichert ist.
  • admin: true oder false; in diesem Endpoint normalerweise false, da Administratoren ausgeschlossen werden.
  • joined_at: Beitrittsdatum im ISO-8601-Format oder null.
  • email: wird nur zurückgegeben, wenn include_email=true ist. Metricgram verwendet zuerst die E-Mail der Subscription und danach die im Gruppenmitglied gespeicherte E-Mail. Kann null sein.
  • message_count, reaction_count und activity_count: Ganzzahl-Zähler, die nur im ausgewählten Datumsbereich berechnet werden, nicht über die gesamte Historie des Nutzers. activity_count ist message_count + reaction_count.
  • last_message_at und last_reaction_at: Datum im ISO-8601-Format oder null, wenn es keine Aktivität dieses Typs gab.
  • last_activity_at: Datum der letzten erfassten Aktivität im ISO-8601-Format.
  • meta: Gruppen-, Datumsbereichs- und Paginierungsdaten der Anfrage.

GET /api/v1/subscriber_health

Gibt dieselben Daten zurück wie der Bereich Abonnentengesundheit: verknüpfte aktive Abonnenten, aktuelle Aktivität, Risikosignale, anstehende Verlängerungen und Aufschlüsselung nach Plan.

Standardmäßig werden dieselben Zeitfenster wie im Panel verwendet: 30 Tage für Aktivität und 14 Tage für anstehende Verlängerungen. Wenn Sie diese Parameter ändern, stimmen die Ergebnisse möglicherweise nicht exakt mit dem Panel überein.

Unterstützte Parameter:

  • activity_days: Anzahl der Tage für aktuelle Aktivität. Standard 30, Maximum 365; Werte über 365 werden auf 365 begrenzt.
  • renewal_days: Anzahl der Tage für anstehende Verlängerungen. Standard 14, Maximum 90; Werte über 90 werden auf 90 begrenzt.
  • include_email: true oder false. Standard: false. Wenn true, enthalten gefährdete Abonnenten die in der Subscription gespeicherte E-Mail. Kann null sein.

Beispiel:

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

Beispiel für eine JSON-Antwort:

{
  "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 monatlich", "29 EUR / Monat"],
        "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 monatlich", "29 EUR / Monat"],
        "active_count": 12,
        "engaged_count": 9,
        "at_risk_count": 2,
        "engaged_percentage": 75,
        "at_risk_percentage": 17
      }
    ]
  },
  "meta": {
    "group_id": 42,
    "group_title": "Meine Gruppe"
  }
}

Wichtige Felder:

  • total_subscribers: verknüpfte aktive Abonnenten in der Berechnung.
  • activity_range / previous_activity_range: aktueller und vorheriger Aktivitätszeitraum.
  • metrics: zusammengefasste Zähler und Prozentwerte.
  • at_risk_subscribers: Abonnenten mit Risikosignalen; risk_indicators kann no_activity, activity_drop oder canceled sein; risk_level kann low, medium oder high sein.
  • plan_rows: verknüpfte aktive Abonnenten nach Subscription-Plan gruppiert.
  • email: nur in at_risk_subscribers, wenn include_email=true.

Mögliche Fehler: 401 unauthorized, 403 forbidden, 400 invalid_date_range und 429 rate_limited.

War dieser Artikel hilfreich?

Einen benutzerdefinierten Bot einrichten

Verwalten Sie Ihre Telegram-Gruppe intelligenter

Metricgram kostenlos testen