Cuenta y Configuración

API de solo lectura

API de solo lectura

Metricgram incluye una API básica de solo lectura para que herramientas externas puedan consultar datos de un grupo sin acceder al panel.

Beta: La API está actualmente en fase de pruebas y está disponible a partir del plan Pro.

Crear un token de API

  1. Ve a Ajustes en el panel de Metricgram.
  2. Abre el apartado Tokens de API.
  3. Elige el grupo al que tendrá acceso el token.
  4. Haz clic en Crear token.
  5. Copia el token en ese momento. Solo se muestra una vez.

Cada token queda vinculado a un grupo. Por ahora puedes tener un token activo por grupo, y puedes revocarlo en cualquier momento.

Autenticación

Envía el token como Bearer token en la cabecera Authorization:

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

Las respuestas correctas se devuelven en formato JSON.

Límite de uso

Cada token está limitado a 60 peticiones por hora. Si se supera el límite, la API devuelve 429 rate_limited.

GET /api/v1/members

Devuelve los miembros del grupo asociado al token.

Parámetros disponibles:

  • status: all, active, inactive, left o unbaned
  • admin: true o false
  • is_bot: true o false. Este parámetro solo filtra valores booleanos; si el valor es desconocido (null), aparece solo cuando no aplicas este filtro.
  • query: búsqueda por ID de Telegram, username o nombre
  • limit: por defecto 100, máximo 500
  • page: por defecto 1
  • include_email: true o false. Por defecto: false. Cuando es true, Metricgram usa primero el email de la suscripción y, si no existe, el email guardado en la ficha del miembro del grupo. Puede ser null.

Ejemplo:

curl -G "https://metricgram.com/api/v1/members" \
  -H "Authorization: Bearer TU_TOKEN_API" \
  --data-urlencode "status=active" \
  --data-urlencode "limit=100" \
  --data-urlencode "include_email=true" \
  --data-urlencode "page=1"

Ejemplo de respuesta 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": "Mi grupo",
    "page": 1,
    "limit": 100,
    "count": 1,
    "has_more": false,
    "filters": {
      "status": "active"
    }
  }
}

Campos principales de respuesta:

  • telegram_id: ID de Telegram como texto. Puede ser null si Metricgram no lo tiene registrado.
  • username, first_name y language_code: datos públicos de Telegram. Pueden ser null.
  • is_bot: true, false o null si Telegram no ha informado ese dato.
  • status: active, inactive, left, unbaned o null si no hay estado registrado.
  • admin: true o false.
  • joined_at: fecha de entrada en formato ISO 8601, o null.
  • email: solo se devuelve cuando include_email=true. Metricgram usa primero el email de la suscripción y, si no existe, el email guardado en la ficha del miembro del grupo. Puede ser null.
  • meta: datos de paginación y filtros de la petición.

GET /api/v1/active_users

Devuelve miembros no administradores con mensajes o reacciones registradas dentro del rango de fechas seleccionado. El propietario del grupo queda excluido de esta lista. Los resultados se ordenan por actividad descendente: primero por activity_count y después por last_activity_at.

Parámetros disponibles:

  • start_date: fecha inicial en formato YYYY-MM-DD. Por defecto: hace 30 días.
  • end_date: fecha final en formato YYYY-MM-DD. Por defecto: hoy.
  • limit: por defecto 100, máximo 500
  • page: por defecto 1
  • include_email: true o false. Por defecto: false. Cuando es true, Metricgram usa primero el email de la suscripción y, si no existe, el email guardado en la ficha del miembro del grupo. Puede ser null.

Ejemplo:

curl -G "https://metricgram.com/api/v1/active_users" \
  -H "Authorization: Bearer TU_TOKEN_API" \
  --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"

Ejemplo de respuesta 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": "Mi grupo",
    "start_date": "2026-04-01",
    "end_date": "2026-04-30",
    "page": 1,
    "limit": 100,
    "count": 1,
    "has_more": false
  }
}

Campos principales de respuesta:

  • telegram_id: ID de Telegram como texto. Puede ser null si Metricgram no lo tiene registrado.
  • username, first_name y language_code: datos públicos de Telegram. Pueden ser null.
  • is_bot: true, false o null si Telegram no ha informado ese dato.
  • member_status: mismos valores de texto que status en /api/v1/members; puede ser null si no hay estado registrado.
  • admin: true o false; en este endpoint normalmente será false porque se excluyen administradores.
  • joined_at: fecha de entrada en formato ISO 8601, o null.
  • email: solo se devuelve cuando include_email=true. Metricgram usa primero el email de la suscripción y, si no existe, el email guardado en la ficha del miembro del grupo. Puede ser null.
  • message_count, reaction_count y activity_count: contadores enteros calculados solo dentro del rango de fechas seleccionado, no sobre el histórico total del usuario. activity_count es message_count + reaction_count.
  • last_message_at y last_reaction_at: fecha en formato ISO 8601, o null si no hubo actividad de ese tipo.
  • last_activity_at: fecha en formato ISO 8601 de la última actividad registrada.
  • meta: datos del grupo, rango de fechas y paginación de la petición.

GET /api/v1/subscriber_health

Devuelve los mismos datos que el panel de Salud de suscriptores: suscriptores activos vinculados, actividad reciente, señales de riesgo, próximas renovaciones y desglose por plan.

Por defecto usa las mismas ventanas que el panel: 30 días para actividad y 14 días para próximas renovaciones. Si cambias estos parámetros, los resultados pueden no coincidir exactamente con los del panel.

Parámetros disponibles:

  • activity_days: número de días para actividad reciente. Por defecto 30, máximo 365; si se supera, se limitará a 365.
  • renewal_days: número de días para próximas renovaciones. Por defecto 14, máximo 90; si se supera, se limitará a 90.
  • include_email: true o false. Por defecto: false. Cuando es true, los suscriptores en riesgo incluyen el email guardado en la suscripción. Puede ser null.

Ejemplo:

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

Ejemplo de respuesta 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 mensual", "29 EUR / mes"],
        "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 mensual", "29 EUR / mes"],
        "active_count": 12,
        "engaged_count": 9,
        "at_risk_count": 2,
        "engaged_percentage": 75,
        "at_risk_percentage": 17
      }
    ]
  },
  "meta": {
    "group_id": 42,
    "group_title": "Mi grupo"
  }
}

Campos principales:

  • total_subscribers: suscriptores activos vinculados incluidos en el cálculo.
  • activity_range / previous_activity_range: ventanas de actividad actual y anterior.
  • metrics: contadores y porcentajes resumidos.
  • at_risk_subscribers: suscriptores con señales de riesgo; risk_indicators puede ser no_activity, activity_drop o canceled; risk_level puede ser low, medium o high.
  • plan_rows: suscriptores activos vinculados agrupados por plan de suscripción.
  • email: solo se devuelve dentro de at_risk_subscribers cuando include_email=true.

Errores habituales

  • 401 unauthorized: falta el token o no es válido.
  • 403 forbidden: el token no tiene permiso o el grupo no está disponible para la cuenta.
  • 400 invalid_date_range: el rango de fechas no es válido.
  • 429 rate_limited: se ha alcanzado el límite por hora.

¿Te resultó útil este artículo?

Configurar un bot personalizado

Gestiona tu grupo de Telegram de forma inteligente

Prueba Metricgram gratis