계정 및 설정

읽기 전용 API

읽기 전용 API

Metricgram은 외부 도구가 대시보드에 접근하지 않고 그룹 데이터를 조회할 수 있도록 기본 읽기 전용 API를 제공합니다.

베타: API는 현재 테스트 단계이며 Pro 플랜 이상에서 사용할 수 있습니다.

토큰 만들기

설정으로 이동해 API 토큰 섹션을 열고 그룹을 선택한 뒤 토큰 만들기를 클릭하세요. 토큰은 한 번만 표시되므로 즉시 복사해야 합니다.

각 토큰은 하나의 그룹에 연결됩니다. 현재는 그룹당 하나의 활성 토큰을 만들 수 있으며 언제든지 취소할 수 있습니다.

인증

curl -H "Authorization: Bearer 내_API_토큰" \
  "https://metricgram.com/api/v1/members"

성공한 응답은 JSON 형식으로 반환됩니다.

각 토큰은 시간당 60개 요청으로 제한됩니다.

GET /api/v1/members

토큰에 연결된 그룹의 멤버를 반환합니다.

사용 가능한 파라미터:

  • status: all, active, inactive, left 또는 unbaned
  • admin: true 또는 false
  • is_bot: true 또는 false. 이 파라미터는 불리언 값만 필터링하며, 알 수 없는 값(null)은 이 필터를 사용하지 않을 때만 반환됩니다.
  • query: Telegram ID, 사용자 이름 또는 이름으로 검색
  • limit: 기본값 100, 최대 500
  • page: 기본값 1
  • include_email: true 또는 false. 기본값: false. true이면 Metricgram은 먼저 구독 이메일을 사용하고, 없으면 그룹 멤버 레코드에 저장된 이메일을 사용합니다. null일 수 있습니다.

예시:

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"

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

주요 응답 필드:

  • telegram_id: 문자열 형태의 Telegram ID입니다. Metricgram에 저장된 값이 없으면 null일 수 있습니다.
  • username, first_name, language_code: Telegram 공개 데이터이며 null일 수 있습니다.
  • is_bot: Telegram이 값을 제공하지 않은 경우 true, false 또는 null일 수 있습니다.
  • status: active, inactive, left, unbaned 또는 상태가 저장되지 않은 경우 null입니다.
  • admin: true 또는 false.
  • joined_at: ISO 8601 형식의 참여 날짜 또는 null.
  • email: include_email=true일 때만 반환됩니다. Metricgram은 먼저 구독 이메일을 사용하고, 없으면 그룹 멤버 레코드에 저장된 이메일을 사용합니다. null일 수 있습니다.
  • meta: 요청의 페이지네이션 및 필터 정보입니다.

GET /api/v1/active_users

선택한 날짜 범위에서 메시지 또는 반응이 기록된 비관리자 멤버를 반환합니다. 그룹 소유자는 이 목록에서 제외됩니다. 결과는 활동량 내림차순으로 정렬되며, 먼저 activity_count, 그다음 last_activity_at 기준입니다.

사용 가능한 파라미터:

  • start_date: 시작 날짜, 형식은 YYYY-MM-DD입니다. 기본값: 30일 전.
  • end_date: 종료 날짜, 형식은 YYYY-MM-DD입니다. 기본값: 오늘.
  • limit: 기본값 100, 최대 500
  • page: 기본값 1
  • include_email: true 또는 false. 기본값: false. true이면 Metricgram은 먼저 구독 이메일을 사용하고, 없으면 그룹 멤버 레코드에 저장된 이메일을 사용합니다. null일 수 있습니다.

예시:

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"

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

주요 응답 필드:

  • telegram_id: 문자열 형태의 Telegram ID입니다. Metricgram에 저장된 값이 없으면 null일 수 있습니다.
  • username, first_name, language_code: Telegram 공개 데이터이며 null일 수 있습니다.
  • is_bot: Telegram이 값을 제공하지 않은 경우 true, false 또는 null일 수 있습니다.
  • member_status: /api/v1/members의 status와 같은 텍스트 값을 사용하며, 상태가 저장되지 않은 경우 null일 수 있습니다.
  • admin: true 또는 false; 이 엔드포인트에서는 관리자가 제외되므로 일반적으로 false입니다.
  • joined_at: ISO 8601 형식의 참여 날짜 또는 null.
  • email: include_email=true일 때만 반환됩니다. Metricgram은 먼저 구독 이메일을 사용하고, 없으면 그룹 멤버 레코드에 저장된 이메일을 사용합니다. null일 수 있습니다.
  • message_count, reaction_count, activity_count: 사용자의 전체 기록이 아니라 선택한 날짜 범위 안에서만 계산되는 정수 카운터입니다. activity_count는 message_count + reaction_count입니다.
  • last_message_at, last_reaction_at: ISO 8601 형식의 날짜이거나 해당 유형의 활동이 없으면 null입니다.
  • last_activity_at: 마지막으로 기록된 활동의 ISO 8601 형식 날짜입니다.
  • meta: 요청의 그룹, 날짜 범위, 페이지네이션 정보입니다.

GET /api/v1/subscriber_health

구독자 상태 패널과 동일한 데이터를 반환합니다: 연결된 활성 구독자, 최근 활동, 위험 신호, 예정된 갱신, 플랜별 분류.

기본적으로 패널과 동일한 기간을 사용합니다. 활동은 30일, 예정된 갱신은 14일입니다. 이 매개변수를 변경하면 결과가 패널과 정확히 일치하지 않을 수 있습니다.

지원되는 매개변수:

  • activity_days: 최근 활동에 사용할 일수입니다. 기본값 30, 최대 365이며 365를 넘으면 365로 제한됩니다.
  • renewal_days: 예정된 갱신에 사용할 일수입니다. 기본값 14, 최대 90이며 90을 넘으면 90으로 제한됩니다.
  • include_email: true 또는 false. 기본값: false. true이면 위험 구독자에 구독에 저장된 이메일이 포함됩니다. null일 수 있습니다.

예시:

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

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 월간", "29 EUR / 월"],
        "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 월간", "29 EUR / 월"],
        "active_count": 12,
        "engaged_count": 9,
        "at_risk_count": 2,
        "engaged_percentage": 75,
        "at_risk_percentage": 17
      }
    ]
  },
  "meta": {
    "group_id": 42,
    "group_title": "내 그룹"
  }
}

주요 필드:

  • total_subscribers: 계산에 포함된 연결된 활성 구독자입니다.
  • activity_range / previous_activity_range: 현재 및 이전 활동 기간입니다.
  • metrics: 요약 카운터와 비율입니다.
  • at_risk_subscribers: 위험 신호가 있는 구독자입니다. risk_indicators는 no_activity, activity_drop, canceled일 수 있고 risk_level은 low, medium, high일 수 있습니다.
  • plan_rows: 구독 플랜별로 그룹화된 연결된 활성 구독자입니다.
  • email: include_email=true일 때만 at_risk_subscribers 안에 반환됩니다.

이 문서가 도움이 되었나요?

맞춤 봇 설정

Telegram 그룹을 더 스마트하게 관리하세요

Metricgram을 무료로 사용해 보세요