시청자 정보 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 중 하나는 반드시 필요하며, 두 파라미터를 함께 사용할 수 없습니다.
응답 필드
| 필드 | 타입 | 설명 |
|---|---|---|
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은 함께 사용할 수 없습니다."
}
}오류 코드
| 오류 메시지 | HTTP 상태 | 설명 |
|---|---|---|
| viewer_uid 또는 viewer_nickname 파라미터가 필요합니다. | 400 | 두 파라미터가 모두 누락됨 |
| viewer_uid와 viewer_nickname은 함께 사용할 수 없습니다. | 400 | viewer_uid와 viewer_nickname을 함께 전달함 |
| 잘못된 형식 UID가 있습니다. | 400 | UID 형식이 올바르지 않음 (32자 영숫자) |
| 유효한 viewer_uid가 없습니다. | 400 | 파싱 후 유효한 UID 없음 |
| viewer_nickname은 단일 닉네임만 지원합니다. | 400 | viewer_nickname에 여러 값을 전달함 |
| 한 번에 최대 20명까지 조회 가능합니다. | 400 | 조회 제한 초과 |
| 인증에 실패했습니다. | 400 | API 키 인증 실패 |
| 권한이 없습니다. | 403 | read.viewer_info 권한 없음 |