뚜봇 로고
뚜봇설명서

시청자 정보 API

시청자의 활동 통계와 출석 정보를 조회하는 API입니다.

최종 수정:

이 API를 사용하려면 read.viewer_info 권한이 필요해요. 키는 한글이라 헤더에 넣기 전에 퍼센트 인코딩해야 해요. 인증 방법 →

시청자 정보 조회

GET/api/v1/user_info

시청자의 채팅 통계와 출석 정보를 조회해요.

Query Parameters

viewer_uidstring

조회할 시청자의 UID (쉼표로 구분하여 최대 20명)

viewer_nicknamestring

조회할 시청자 닉네임 (단일 닉네임만 지원, viewer_uid와 함께 사용할 수 없음)

viewer_uid 또는 viewer_nickname 중 하나는 반드시 필요하며, 두 파라미터를 함께 사용할 수 없어요.

파라미터 제약

viewer_uid

  • 쉼표(,)로 구분해 최대 20명까지 한 번에 조회
  • 32자리 소문자 영숫자여야 하며, 대문자로 넣어도 자동으로 소문자 처리돼요
  • 하나라도 형식이 틀리면 전체 요청이 실패해요 (잘못된 형식 UID가 있습니다.)

viewer_nickname

  • 한 명만 조회할 수 있어요 (쉼표로 여러 명 ❌)
  • 한글·영문·숫자·띄어쓰기만 허용, 최대 10글자

닉네임은 바뀔 수 있으니, 기록을 계속 추적할 목적이라면 viewer_uid 로 조회하시는 걸 권해요. 봇이 닉네임을 모르는 시청자는 viewer_nickname 이 (알 수 없음) 으로 나와요.

응답 필드

필드타입설명
dataarray시청자 정보 목록
data[].viewer_uidstring시청자 UID
data[].viewer_nicknamestring시청자 닉네임
data[].user_stats.chattingnumber총 채팅 수
data[].user_stats.temporary-restrictnumber임시 제한 횟수
data[].user_stats.restrictnumber활동 제한(벤) 횟수
data[].attendance.countnumber총 출석 횟수
data[].attendance.combonumber현재 연속 출석
data[].attendance.laststring|null마지막 출석 시간

시청자 UID

시청자 UID는 32자리 영숫자로 구성돼요. 치지직에서 사용자 프로필 URL이나 채팅 데이터에서 확인할 수 있어요.

예시: 4c3a50fe635854036b4dcf15c9a4d0a2
요청 - 단일 시청자
curl -X GET "https://chzzk-bot.ddutto.com/api/v1/user_info?viewer_uid=4c3a50fe635854036b4dcf15c9a4d0a2" \
-H "Authorization: DDUBOT_API %EB%AF%B8%EB%A6%AC-%EC%9D%B8%EC%BD%94%EB%94%A9%ED%95%9C-%ED%82%A4"
응답
{
  "success": true,
  "data": [
    {
      "viewer_uid": "4c3a50fe635854036b4dcf15c9a4d0a2",
      "viewer_nickname": "마지막남은뚜또",
      "user_stats": {
        "chatting": 5215,
        "temporary-restrict": 13,
        "restrict": 0
      },
      "attendance": {
        "count": 21,
        "combo": 2,
        "last": "2025-12-14 15:00:04"
      }
    }
  ]
}
응답
{
  "success": false,
  "data": {
    "error": "viewer_uid 또는 viewer_nickname 파라미터가 필요합니다."
  }
}

여러 시청자 조회

쉼표로 구분하여 최대 20명까지 한 번에 조회할 수 있어요.

GET/api/v1/user_info

여러 시청자의 정보를 한 번에 조회해요.

사용 예시

?viewer_uid=uid1,uid2,uid3

한 번에 최대 20명까지만 조회 가능해요.

요청 - 여러 시청자
curl -X GET "https://chzzk-bot.ddutto.com/api/v1/user_info?viewer_uid=4c3a50fe635854036b4dcf15c9a4d0a2,7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e" \
-H "Authorization: DDUBOT_API %EB%AF%B8%EB%A6%AC-%EC%9D%B8%EC%BD%94%EB%94%A9%ED%95%9C-%ED%82%A4"
응답
{
  "success": true,
  "data": [
    {
      "viewer_uid": "4c3a50fe635854036b4dcf15c9a4d0a2",
      "viewer_nickname": "마지막남은뚜또",
      "user_stats": {
        "chatting": 5215,
        "temporary-restrict": 13,
        "restrict": 0
      },
      "attendance": {
        "count": 21,
        "combo": 2,
        "last": "2025-12-14 15:00:04"
      }
    },
    {
      "viewer_uid": "7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e",
      "viewer_nickname": "(알 수 없음)",
      "user_stats": {
        "chatting": 1823,
        "temporary-restrict": 2,
        "restrict": 0
      },
      "attendance": {
        "count": 0,
        "combo": 0,
        "last": null
      }
    }
  ]
}
응답
{
  "success": false,
  "data": {
    "error": "한 번에 최대 20명까지 조회 가능합니다."
  }
}

닉네임으로 조회

닉네임으로 시청자를 조회할 수 있어요.

GET/api/v1/user_info

닉네임으로 시청자 정보를 조회해요.

사용 예시

?viewer_nickname=테스터

닉네임은 한 번에 하나만 조회할 수 있어요. 조건에 맞는 시청자가 없으면, 빈 배열이 반환될 수 있어요.

검색은 앞부분 일치라서 테스터 로 조회하면 테스터, 테스터123 처럼 그 글자로 시작하는 시청자가 검색돼요.

다만 전부 돌아오지는 않아요.

  • 닉네임이 최근에 바뀐 순서로 최대 10명까지만 후보가 돼요
  • 그중 내 채널에서 채팅한 적이 없는(채팅 수 0) 시청자는 결과에서 빠집니다

그래서 같은 글자로 시작하는 시청자가 많으면 일부가 안 나올 수 있어요.

요청 - 닉네임 조회
curl -X GET "https://chzzk-bot.ddutto.com/api/v1/user_info?viewer_nickname=테스터" \
-H "Authorization: DDUBOT_API %EB%AF%B8%EB%A6%AC-%EC%9D%B8%EC%BD%94%EB%94%A9%ED%95%9C-%ED%82%A4"
응답
{
  "success": true,
  "data": [
    {
      "viewer_uid": "9f21c7b40ad3e85612ff09c4d7b1a6e3",
      "viewer_nickname": "테스터",
      "user_stats": {
        "chatting": 412,
        "temporary-restrict": 0,
        "restrict": 0
      },
      "attendance": {
        "count": 7,
        "combo": 3,
        "last": "2025-12-14 15:00:04"
      }
    },
    {
      "viewer_uid": "1b83d5aa2c7f40e9b6d2185cf3907ee1",
      "viewer_nickname": "테스터123",
      "user_stats": {
        "chatting": 58,
        "temporary-restrict": 1,
        "restrict": 0
      },
      "attendance": {
        "count": 2,
        "combo": 0,
        "last": "2025-12-11 21:33:47"
      }
    }
  ]
}
응답 - 빈 배열
{
  "success": true,
  "data": []
}
응답
{
  "success": false,
  "data": {
    "error": "viewer_uid와 viewer_nickname은 함께 사용할 수 없습니다."
  }
}

오류 코드

오류 메시지는 모두 data.error 안에 들어가요.

data.errorHTTP 상태설명
viewer_uid 또는 viewer_nickname 파라미터가 필요합니다.400두 파라미터가 모두 누락됨
viewer_uid와 viewer_nickname은 함께 사용할 수 없습니다.400두 파라미터를 함께 전달함
잘못된 형식 UID가 있습니다.400UID 형식이 올바르지 않음 (32자리 소문자 영숫자)
유효한 viewer_uid가 없습니다.400파싱 후 유효한 UID 없음 (쉼표만 넣은 경우 등)
한 번에 최대 20명까지 조회 가능합니다.400조회 제한 초과
viewer_nickname은 단일 닉네임만 지원합니다.400닉네임에 쉼표를 넣어 여러 명을 요청함
viewer_nickname은 한글, 영문, 숫자, 띄어쓰기만 허용되며 최대 10글자입니다.400닉네임 형식/길이 위반
잘못된 접근입니다.400API 키 인증 실패
권한이 없습니다. 'read.viewer_info' scope가 필요합니다.403권한 없음
요청 횟수 제한을 초과했습니다. N초 후에 다시 시도해주세요.429분당 호출 제한 초과 (계정 15회/분 · IP 60회/분)
서버 오류가 발생했습니다.500서버 내부 오류