Compte et facturation

API en lecture seule

API en lecture seule

Metricgram propose une API basique en lecture seule pour consulter les données d'un groupe depuis des outils externes sans accéder au tableau de bord.

Bêta : l'API est actuellement en phase de test et disponible à partir du plan Pro.

Créer un token

Allez dans Paramètres, ouvrez Jetons d'API, choisissez le groupe, puis cliquez sur Créer un token. Copiez le token immédiatement : il n'est affiché qu'une seule fois.

Chaque token est lié à un seul groupe. Vous pouvez créer un token actif par groupe et le révoquer à tout moment.

Authentification

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

Les réponses réussies sont renvoyées au format JSON.

Chaque token est limité à 60 requêtes par heure.

GET /api/v1/members

Renvoie les membres du groupe associé au token.

Paramètres disponibles :

  • status : all, active, inactive, left ou unbaned
  • admin : true ou false
  • is_bot : true ou false. Ce paramètre filtre uniquement les valeurs booléennes ; les valeurs inconnues (null) ne sont renvoyées que si ce filtre n’est pas utilisé.
  • query : recherche par ID Telegram, username ou prénom
  • limit : 100 par défaut, 500 maximum
  • page : 1 par défaut
  • include_email : true ou false. Par défaut : false. Quand la valeur est true, Metricgram utilise d’abord l’email de l’abonnement, puis l’email enregistré sur la fiche du membre du groupe. Peut être null.

Exemple :

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"

Exemple de réponse 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": "Mon groupe",
    "page": 1,
    "limit": 100,
    "count": 1,
    "has_more": false,
    "filters": {
      "status": "active"
    }
  }
}

Principaux champs de réponse :

  • telegram_id : ID Telegram sous forme de texte. Peut être null si Metricgram ne l’a pas enregistré.
  • username, first_name et language_code : données publiques Telegram. Elles peuvent être null.
  • is_bot : true, false ou null si Telegram n’a pas fourni cette valeur.
  • status : active, inactive, left, unbaned ou null si aucun statut n’est enregistré.
  • admin : true ou false.
  • joined_at : date d’entrée au format ISO 8601, ou null.
  • email : renvoyé uniquement lorsque include_email=true. Metricgram utilise d’abord l’email de l’abonnement, puis l’email enregistré sur la fiche du membre du groupe. Peut être null.
  • meta : données de pagination et de filtres de la requête.

GET /api/v1/active_users

Renvoie les membres non administrateurs avec des messages ou réactions enregistrés sur la période choisie. Le propriétaire du groupe est exclu de cette liste. Les résultats sont triés par activité décroissante : d’abord par activity_count, puis par last_activity_at.

Paramètres disponibles :

  • start_date : date de début au format YYYY-MM-DD. Par défaut : il y a 30 jours.
  • end_date : date de fin au format YYYY-MM-DD. Par défaut : aujourd’hui.
  • limit : 100 par défaut, 500 maximum
  • page : 1 par défaut
  • include_email : true ou false. Par défaut : false. Quand la valeur est true, Metricgram utilise d’abord l’email de l’abonnement, puis l’email enregistré sur la fiche du membre du groupe. Peut être null.

Exemple :

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"

Exemple de réponse 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": "Mon groupe",
    "start_date": "2026-04-01",
    "end_date": "2026-04-30",
    "page": 1,
    "limit": 100,
    "count": 1,
    "has_more": false
  }
}

Principaux champs de réponse :

  • telegram_id : ID Telegram sous forme de texte. Peut être null si Metricgram ne l’a pas enregistré.
  • username, first_name et language_code : données publiques Telegram. Elles peuvent être null.
  • is_bot : true, false ou null si Telegram n’a pas fourni cette valeur.
  • member_status : mêmes valeurs textuelles que status dans /api/v1/members ; peut être null si aucun statut n’est enregistré.
  • admin : true ou false ; dans cet endpoint, la valeur est normalement false car les administrateurs sont exclus.
  • joined_at : date d’entrée au format ISO 8601, ou null.
  • email : renvoyé uniquement lorsque include_email=true. Metricgram utilise d’abord l’email de l’abonnement, puis l’email enregistré sur la fiche du membre du groupe. Peut être null.
  • message_count, reaction_count et activity_count : compteurs entiers calculés uniquement sur la période sélectionnée, pas sur tout l’historique de l’utilisateur. activity_count correspond à message_count + reaction_count.
  • last_message_at et last_reaction_at : date au format ISO 8601, ou null s’il n’y a pas eu d’activité de ce type.
  • last_activity_at : date de la dernière activité enregistrée au format ISO 8601.
  • meta : données du groupe, de la période et de la pagination de la requête.

GET /api/v1/subscriber_health

Renvoie les mêmes données que le panneau Santé des abonnés : abonnés actifs liés, activité récente, signaux de risque, prochains renouvellements et répartition par plan.

Par défaut, il utilise les mêmes fenêtres que le panneau : 30 jours pour l'activité et 14 jours pour les prochains renouvellements. Si vous modifiez ces paramètres, les résultats peuvent ne pas correspondre exactement au panneau.

Paramètres pris en charge :

  • activity_days: nombre de jours pour l'activité récente. Par défaut 30, maximum 365 ; les valeurs supérieures à 365 sont limitées à 365.
  • renewal_days: nombre de jours pour les prochains renouvellements. Par défaut 14, maximum 90 ; les valeurs supérieures à 90 sont limitées à 90.
  • include_email: true ou false. Par défaut : false. Quand true, les abonnés à risque incluent l'email enregistré sur l'abonnement. Peut être null.

Exemple :

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

Exemple de réponse 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 mensuel", "29 EUR / mois"],
        "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 mensuel", "29 EUR / mois"],
        "active_count": 12,
        "engaged_count": 9,
        "at_risk_count": 2,
        "engaged_percentage": 75,
        "at_risk_percentage": 17
      }
    ]
  },
  "meta": {
    "group_id": 42,
    "group_title": "Mon groupe"
  }
}

Principaux champs :

  • total_subscribers: abonnés actifs liés inclus dans le calcul.
  • activity_range / previous_activity_range: fenêtres d'activité actuelle et précédente.
  • metrics: compteurs et pourcentages résumés.
  • at_risk_subscribers: abonnés avec signaux de risque ; risk_indicators peut être no_activity, activity_drop ou canceled ; risk_level peut être low, medium ou high.
  • plan_rows: abonnés actifs liés regroupés par plan d'abonnement.
  • email: renvoyé uniquement dans at_risk_subscribers quand include_email=true.

Erreurs possibles : 401 unauthorized, 403 forbidden, 400 invalid_date_range et 429 rate_limited.

Cet article vous a-t-il été utile ?

Bot personnalisé

Gérez votre groupe Telegram plus intelligemment

Essayez Metricgram gratuitement