Account e Impostazioni

API di sola lettura

API di sola lettura

Metricgram include una API di base in sola lettura per permettere a strumenti esterni di consultare i dati di un gruppo senza accedere alla dashboard.

Beta: l'API è attualmente in fase di test ed è disponibile a partire dal piano Pro.

Creare un token

Vai su Impostazioni, apri Token API, scegli il gruppo e clicca su Crea token. Copia subito il token: viene mostrato una sola volta.

Ogni token è collegato a un solo gruppo. Per ora puoi avere un token attivo per gruppo e revocarlo in qualsiasi momento.

Autenticazione

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

Le risposte corrette vengono restituite in formato JSON.

Ogni token è limitato a 60 richieste all'ora.

GET /api/v1/members

Restituisce i membri del gruppo associato al token.

Parametri disponibili:

  • status: all, active, inactive, left o unbaned
  • admin: true o false
  • is_bot: true o false. Questo parametro filtra solo valori booleani; i valori sconosciuti (null) compaiono solo quando il filtro non viene usato.
  • query: ricerca per ID Telegram, username o nome
  • limit: predefinito 100, massimo 500
  • page: predefinito 1
  • include_email: true o false. Predefinito: false. Quando è true, Metricgram usa prima l’email dell’abbonamento e poi l’email salvata nella scheda del membro del gruppo. Può essere null.

Esempio:

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"

Esempio di risposta 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": "Il mio gruppo",
    "page": 1,
    "limit": 100,
    "count": 1,
    "has_more": false,
    "filters": {
      "status": "active"
    }
  }
}

Campi principali della risposta:

  • telegram_id: ID Telegram come testo. Può essere null se Metricgram non lo ha salvato.
  • username, first_name e language_code: dati pubblici di Telegram. Possono essere null.
  • is_bot: true, false o null se Telegram non ha fornito questo valore.
  • status: active, inactive, left, unbaned o null se non è stato salvato alcuno stato.
  • admin: true o false.
  • joined_at: data di ingresso in formato ISO 8601, oppure null.
  • email: viene restituito solo quando include_email=true. Metricgram usa prima l’email dell’abbonamento e poi l’email salvata nella scheda del membro del gruppo. Può essere null.
  • meta: dati di paginazione e filtri della richiesta.

GET /api/v1/active_users

Restituisce membri non amministratori con messaggi o reazioni registrati nell’intervallo di date selezionato. Il proprietario del gruppo è escluso da questo elenco. I risultati sono ordinati per attività decrescente: prima per activity_count, poi per last_activity_at.

Parametri disponibili:

  • start_date: data iniziale in formato YYYY-MM-DD. Predefinito: 30 giorni fa.
  • end_date: data finale in formato YYYY-MM-DD. Predefinito: oggi.
  • limit: predefinito 100, massimo 500
  • page: predefinito 1
  • include_email: true o false. Predefinito: false. Quando è true, Metricgram usa prima l’email dell’abbonamento e poi l’email salvata nella scheda del membro del gruppo. Può essere null.

Esempio:

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"

Esempio di risposta 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": "Il mio gruppo",
    "start_date": "2026-04-01",
    "end_date": "2026-04-30",
    "page": 1,
    "limit": 100,
    "count": 1,
    "has_more": false
  }
}

Campi principali della risposta:

  • telegram_id: ID Telegram come testo. Può essere null se Metricgram non lo ha salvato.
  • username, first_name e language_code: dati pubblici di Telegram. Possono essere null.
  • is_bot: true, false o null se Telegram non ha fornito questo valore.
  • member_status: stessi valori testuali di status in /api/v1/members; può essere null se non è stato salvato alcuno stato.
  • admin: true o false; in questo endpoint normalmente è false perché gli amministratori sono esclusi.
  • joined_at: data di ingresso in formato ISO 8601, oppure null.
  • email: viene restituito solo quando include_email=true. Metricgram usa prima l’email dell’abbonamento e poi l’email salvata nella scheda del membro del gruppo. Può essere null.
  • message_count, reaction_count e activity_count: contatori interi calcolati solo nell’intervallo di date selezionato, non sull’intero storico dell’utente. activity_count è message_count + reaction_count.
  • last_message_at e last_reaction_at: data in formato ISO 8601, oppure null se non c’è stata attività di quel tipo.
  • last_activity_at: data dell’ultima attività registrata in formato ISO 8601.
  • meta: dati del gruppo, dell’intervallo di date e della paginazione della richiesta.

GET /api/v1/subscriber_health

Restituisce gli stessi dati del pannello Salute degli abbonati: abbonati attivi collegati, attività recente, segnali di rischio, prossimi rinnovi e suddivisione per piano.

Per impostazione predefinita usa le stesse finestre del pannello: 30 giorni per l'attività e 14 giorni per i prossimi rinnovi. Se modifichi questi parametri, i risultati potrebbero non coincidere esattamente con il pannello.

Parametri disponibili:

  • activity_days: numero di giorni per l'attività recente. Predefinito 30, massimo 365; i valori superiori a 365 vengono limitati a 365.
  • renewal_days: numero di giorni per i prossimi rinnovi. Predefinito 14, massimo 90; i valori superiori a 90 vengono limitati a 90.
  • include_email: true o false. Predefinito: false. Quando è true, gli abbonati a rischio includono l'email salvata nell'abbonamento. Può essere null.

Esempio:

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

Esempio di risposta 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 mensile", "29 EUR / mese"],
        "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 mensile", "29 EUR / mese"],
        "active_count": 12,
        "engaged_count": 9,
        "at_risk_count": 2,
        "engaged_percentage": 75,
        "at_risk_percentage": 17
      }
    ]
  },
  "meta": {
    "group_id": 42,
    "group_title": "Il mio gruppo"
  }
}

Campi principali:

  • total_subscribers: abbonati attivi collegati inclusi nel calcolo.
  • activity_range / previous_activity_range: finestre di attività corrente e precedente.
  • metrics: contatori e percentuali riepilogati.
  • at_risk_subscribers: abbonati con segnali di rischio; risk_indicators può essere no_activity, activity_drop o canceled; risk_level può essere low, medium o high.
  • plan_rows: abbonati attivi collegati raggruppati per piano di abbonamento.
  • email: restituito solo in at_risk_subscribers quando include_email=true.

Errori possibili: 401 unauthorized, 403 forbidden, 400 invalid_date_range e 429 rate_limited.

Questo articolo ti è stato utile?

Configurare un Bot Personalizzato

Gestisci il tuo gruppo Telegram in modo più intelligente

Prova Metricgram gratis