이 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자리 hex 형식이어야 하며, 대문자로 넣어도 자동으로 소문자 처리됩니다
- 하나라도 형식이 틀리면 전체 요청이 실패합니다 (
잘못된 형식 UID가 있습니다.)
viewer_nickname
- 한 명만 조회할 수 있습니다 (쉼표로 여러 명 ❌)
- 한글·영문·숫자·띄어쓰기만 허용, 최대 10글자
닉네임은 바뀔 수 있으니, 기록을 계속 추적할 목적이라면 viewer_uid 로 조회하시는 걸 권합니다.
봇이 닉네임을 모르는 시청자는 viewer_nickname 이 (알 수 없음) 으로 나옵니다.
응답 필드
| 필드 | 타입 | 설명 |
|---|---|---|
data | array | 시청자 정보 목록 |
data[].viewer_uid | string | 시청자 UID |
data[].viewer_nickname | string | 시청자 닉네임 |
data[].user_stats.chatting | number | 총 채팅 수 |
data[].user_stats.temporary-restrict | number | 임시 제한 횟수 |
data[].user_stats.restrict | number | 영구 제한 횟수 |
data[].attendance.count | number | 총 출석 횟수 |
data[].attendance.combo | number | 현재 연속 출석 |
data[].attendance.last | string|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 YOUR_API_KEY"응답
{
"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 YOUR_API_KEY"응답
{
"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=테스터
닉네임은 한 번에 하나만 조회할 수 있습니다. 조건에 맞는 시청자가 없으면, 빈 배열이 반환될 수 있습니다.
요청 - 닉네임 조회
curl -X GET "https://chzzk-bot.ddutto.com/api/v1/user_info?viewer_nickname=테스터" \
-H "Authorization: DDUBOT_API YOUR_API_KEY"응답
{
"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": true,
"data": []
}응답
{
"success": false,
"data": {
"error": "viewer_uid와 viewer_nickname은 함께 사용할 수 없습니다."
}
}오류 코드
오류 메시지는 모두 data.error 안에 들어옵니다.
data.error | HTTP 상태 | 설명 |
|---|---|---|
| viewer_uid 또는 viewer_nickname 파라미터가 필요합니다. | 400 | 두 파라미터가 모두 누락됨 |
| viewer_uid와 viewer_nickname은 함께 사용할 수 없습니다. | 400 | 두 파라미터를 함께 전달함 |
| 잘못된 형식 UID가 있습니다. | 400 | UID 형식이 올바르지 않음 (32자리 hex) |
| 유효한 viewer_uid가 없습니다. | 400 | 파싱 후 유효한 UID 없음 (쉼표만 넣은 경우 등) |
| 한 번에 최대 20명까지 조회 가능합니다. | 400 | 조회 제한 초과 |
| viewer_nickname은 단일 닉네임만 지원합니다. | 400 | 닉네임에 쉼표를 넣어 여러 명을 요청함 |
| viewer_nickname은 한글, 영문, 숫자, 띄어쓰기만 허용되며 최대 10글자입니다. | 400 | 닉네임 형식/길이 위반 |
| 잘못된 접근입니다. | 400 | API 키 인증 실패 |
| 권한이 없습니다. 'read.viewer_info' scope가 필요합니다. | 403 | 권한 없음 |
| 서버 오류가 발생했습니다. | 500 | 서버 내부 오류 |