Conta e Configurações

API somente leitura

API somente leitura

O Metricgram inclui uma API básica somente leitura para consultar dados de um grupo a partir de ferramentas externas sem acessar o painel.

Beta: A API está atualmente em fase de testes e disponível a partir do plano Pro.

Criar um token

Acesse Configurações, abra Tokens de API, escolha o grupo e clique em Criar token. Copie o token imediatamente: ele aparece apenas uma vez.

Cada token fica vinculado a um único grupo. Você pode ter um token ativo por grupo e revogá-lo a qualquer momento.

Autenticação

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

As respostas bem-sucedidas são retornadas em formato JSON.

Cada token é limitado a 60 requisições por hora.

GET /api/v1/members

Retorna os membros do grupo associado ao token.

Parâmetros disponíveis:

  • status: all, active, inactive, left ou unbaned
  • admin: true ou false
  • is_bot: true ou false. Este parâmetro filtra apenas valores booleanos; valores desconhecidos (null) aparecem apenas quando este filtro não é usado.
  • query: busca por ID do Telegram, username ou nome
  • limit: padrão 100, máximo 500
  • page: padrão 1
  • include_email: true ou false. Padrão: false. Quando true, a Metricgram usa primeiro o email da assinatura e depois o email salvo no registro do membro do grupo. Pode ser null.

Exemplo:

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"

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

Principais campos da resposta:

  • telegram_id: ID do Telegram como texto. Pode ser null se o Metricgram não tiver esse dado salvo.
  • username, first_name e language_code: dados públicos do Telegram. Podem ser null.
  • is_bot: true, false ou null quando o Telegram não informou esse valor.
  • status: active, inactive, left, unbaned ou null se nenhum status estiver salvo.
  • admin: true ou false.
  • joined_at: data de entrada em formato ISO 8601, ou null.
  • email: só é retornado quando include_email=true. A Metricgram usa primeiro o email da assinatura e depois o email salvo no registro do membro do grupo. Pode ser null.
  • meta: dados de paginação e filtros da requisição.

GET /api/v1/active_users

Retorna membros não administradores com mensagens ou reações registradas no intervalo de datas selecionado. O proprietário do grupo é excluído desta lista. Os resultados são ordenados por atividade decrescente: primeiro por activity_count e depois por last_activity_at.

Parâmetros disponíveis:

  • start_date: data inicial no formato YYYY-MM-DD. Padrão: 30 dias atrás.
  • end_date: data final no formato YYYY-MM-DD. Padrão: hoje.
  • limit: padrão 100, máximo 500
  • page: padrão 1
  • include_email: true ou false. Padrão: false. Quando true, a Metricgram usa primeiro o email da assinatura e depois o email salvo no registro do membro do grupo. Pode ser null.

Exemplo:

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"

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

Principais campos da resposta:

  • telegram_id: ID do Telegram como texto. Pode ser null se o Metricgram não tiver esse dado salvo.
  • username, first_name e language_code: dados públicos do Telegram. Podem ser null.
  • is_bot: true, false ou null quando o Telegram não informou esse valor.
  • member_status: mesmos valores de texto de status em /api/v1/members; pode ser null se nenhum status estiver salvo.
  • admin: true ou false; neste endpoint normalmente será false porque administradores são excluídos.
  • joined_at: data de entrada em formato ISO 8601, ou null.
  • email: só é retornado quando include_email=true. A Metricgram usa primeiro o email da assinatura e depois o email salvo no registro do membro do grupo. Pode ser null.
  • message_count, reaction_count e activity_count: contadores inteiros calculados apenas no intervalo de datas selecionado, não no histórico total do usuário. activity_count é message_count + reaction_count.
  • last_message_at e last_reaction_at: data em formato ISO 8601, ou null se não houve atividade desse tipo.
  • last_activity_at: data da última atividade registrada em formato ISO 8601.
  • meta: dados do grupo, intervalo de datas e paginação da requisição.

GET /api/v1/subscriber_health

Retorna os mesmos dados do painel Saúde dos assinantes: assinantes ativos vinculados, atividade recente, sinais de risco, próximas renovações e detalhamento por plano.

Por padrão, usa as mesmas janelas do painel: 30 dias para atividade e 14 dias para próximas renovações. Se alterar estes parâmetros, os resultados podem não coincidir exatamente com os do painel.

Parâmetros disponíveis:

  • activity_days: número de dias para atividade recente. Padrão 30, máximo 365; valores acima de 365 são limitados a 365.
  • renewal_days: número de dias para próximas renovações. Padrão 14, máximo 90; valores acima de 90 são limitados a 90.
  • include_email: true ou false. Padrão: false. Quando true, assinantes em risco incluem o email salvo na assinatura. Pode ser null.

Exemplo:

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

Exemplo de resposta 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 mensal", "29 EUR / mês"],
        "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 mensal", "29 EUR / mês"],
        "active_count": 12,
        "engaged_count": 9,
        "at_risk_count": 2,
        "engaged_percentage": 75,
        "at_risk_percentage": 17
      }
    ]
  },
  "meta": {
    "group_id": 42,
    "group_title": "Meu grupo"
  }
}

Campos principais:

  • total_subscribers: assinantes ativos vinculados incluídos no cálculo.
  • activity_range / previous_activity_range: janelas de atividade atual e anterior.
  • metrics: contadores e percentuais resumidos.
  • at_risk_subscribers: assinantes com sinais de risco; risk_indicators pode ser no_activity, activity_drop ou canceled; risk_level pode ser low, medium ou high.
  • plan_rows: assinantes ativos vinculados agrupados por plano de assinatura.
  • email: retornado apenas em at_risk_subscribers quando include_email=true.

Erros possíveis: 401 unauthorized, 403 forbidden, 400 invalid_date_range e 429 rate_limited.

Este artigo foi útil?

Bot personalizado

Gerencie seu grupo do Telegram de forma inteligente

Experimente o Metricgram grátis