# 뚜봇 (DduBot) — 전체 문서

> 치지직(CHZZK) 스트리머를 위한 채팅봇입니다. 2023년 12월 20일부터 운영 중이며,
> 설치 없이 웹 대시보드에서 설정합니다. 무료로 제공됩니다.

주요 규모:
- 방송 화면 오버레이 16종
- 명령어에서 쓰는 변수 99개
- 기본 명령어 43개
- 게임 전적 연동 6종 (리그 오브 레전드, TFT, 발로란트, 오버워치2, 배틀그라운드, 이터널 리턴)
- 공개 API 5종 (출석 · 노래방 · 룰렛 · 신청곡 · 시청자 정보)
- 사용 설명서 31페이지

채널 전용 이름의 봇으로 바꿔 운영할 수 있습니다(신청제).
예: 픽셀봇, 스텔라이브 봇, 악몽봇, 람군, 다람쥐 봇.

다른 채팅봇에서 쓰던 출석 기록·변수 이전은 자동으로 지원하지 않습니다. 디스코드로 문의해주세요.

요약본: https://chzzk-bot.ddutto.com/llms.txt
문서별 원문: https://chzzk-bot.ddutto.com/llms/<문서경로>.md

---

# 기능 전체 목록

출처: https://chzzk-bot.ddutto.com/docs/all-features
설명: 뚜봇이 제공하는 기능 전체. 오버레이 16종, 변수 99개, 명령어 43개, 게임 전적 6종, 공개 API 5종을 한 페이지에 정리했어요.

뚜봇이 지금 제공하는 기능을 한 페이지에 모았어요. 각 항목은 전용 문서로 연결돼요.

## 한눈에 보는 숫자

| 항목 | 수 |
|---|---:|
| 방송 화면 오버레이 | **16종** |
| 명령어에서 쓰는 변수 | **99개** |
| 기본 명령어 | **43개** |
| 게임 전적 연동 | **6종** |
| 공개 API | **5종** |
| 사용 설명서 | **31페이지** |

- 치지직 계정 연동만 하면 **설치 없이 웹에서** 전부 설정해요.
- 봇 이름을 **채널 전용으로 바꿔** 쓸 수도 있어요 (신청제).

---

## 오버레이 16종

OBS 브라우저 소스에 주소를 넣으면 동작해요. 배경은 투명이에요.

| 오버레이 | 하는 일 |
|---|---|
| 채팅 | 채팅을 화면에 표시. 폰트 117종 · TTS · 게임 티어 배지 |
| 룰렛 | 룰렛 회전과 당첨 결과 |
| 최근 룰렛 | 최근 당첨 내역 목록 |
| 룰렛 사용권 베타 | 시청자가 사용권을 썼을 때 뜨는 알림 |
| 팔로우 알림 | 새 팔로워 알림 (이미지·효과음 지정) |
| 후원 | 후원 알림 (표시 형식·TTS) |
| 그림 후원 베타 | 시청자가 그려 보낸 그림 |
| 이모티콘 뿌리기 | 채팅 이모티콘이 화면에 흩날림 |
| 신청곡 | 신청곡 재생 (플레이어) |
| 신청곡 목록 | 대기열만 따로 표시 |
| 노래방 | 노래방 대기열과 현재 곡 |
| 타이머 | 카운트다운 (원형·시계) |
| 카운터 | 숫자 세기 |
| 시청자 수 | 현재 시청자 수 |
| 승부예측 | 치지직 승부예측 현황 |
| 중간 광고 타이머 | 다음 중간 광고까지 남은 시간 |

[오버레이 문서 →](/docs/features/overlay)

---

## 시청자 참여 기능

| 기능 | 내용 |
|---|---|
| **신청곡** | 유튜브 검색·URL 로 신청. 대기열·1인 제한·길이 제한·중복 허용 설정 |
| **노래방** | 신청곡과 별도 대기열 |
| **노래책** | 부를 수 있는 곡 목록 공개 |
| **룰렛** | 후원 금액 연동 자동 회전, 연차, 확률, 사용권 발행 |
| **출석체크** | 누적·연속 출석 기록. 연속은 *직전 방송* 기준이라 매일 안 해도 유지 |
| **가위바위보** | 개인 전적·연승·승률. 하루 판수 제한 |
| **시청자 참여** | 시참 목록 관리, 추첨 |
| **마커** | 방송 중 구간 표시, 시청자 공개 |

[시청자 참여 →](/docs/features/viewer-participation) · [출석체크 →](/docs/features/attendance) · [룰렛 →](/docs/features/roulette)

---

## 게임 전적 연동 6종

닉네임 옆 티어 배지 표시와 채팅 명령어 조회를 지원해요.

| 게임 | 호출 키워드 |
|---|---|
| 리그 오브 레전드 | `롤` |
| TFT (전략적 팀 전투) | `TFT` `tft` |
| 발로란트 | `발로란트` `발로` |
| 오버워치2 | `오버워치2` `옵치` |
| 배틀그라운드 | `배그` |
| 이터널 리턴 | `이터널리턴` `이리` |

[게임 전적 →](/docs/features/game-tier)

---

## 방송 운영

| 기능 | 명령어 |
|---|---|
| 방송 제목 변경 | `!방제변경` |
| 카테고리 변경 | `!게임변경` |
| 태그 변경 | `!태그` |
| 연령 제한 | `!연령제한` |
| 채팅 참여 제한 | `!채팅모드` (팔로우 N분 경과자만 등) |
| 저속 모드 | `!저속모드` |
| 이모티콘 전용 모드 | `!이모티콘모드` |
| 클립 허용 여부 | `!클립설정` |
| 금칙어 | `!금칙어` — 제재 3단계(삭제·타임아웃·영구) |
| 매크로 | `!매크로` — 주기 메시지 |
| 고정 메시지 | `!고정메시지` |
| 팔로우 알림 | `!팔로우알림` |

[방송 설정 →](/docs/commands/broadcast)

---

## 명령어와 변수

- **커스텀 명령어** — 직접 만들어 쓰는 응답. 부분 포함 매칭, 후원 금액 조건, 자동 비활성화, 유저별 쿨타임 지원
- **변수 99개** — 사용자 정보 · 방송 정보 · 시간 · 카운트 · 메모 · 마커 · 주사위 · 제재 · 기능

[커스텀 명령어 →](/docs/commands/custom) · [변수 전체 →](/docs/commands/variables)

---

## 자동화

| 기능 | 내용 |
|---|---|
| **블루프린트** 베타 | 노드 기반 자동화. 방송 시작/종료·후원·채팅 등을 조건으로 동작 정의 |
| **커스텀 스크립트** 베타 | 직접 작성한 스크립트 실행 |
| **디자인 생성기** 베타 | 오버레이 디자인 생성 |
| **리모콘** 베타 | 방송 중 빠른 조작용 팝업 |
| **단축 링크** | `ddu.to` 짧은 주소 (채널당 10개) |

[단축 링크 →](/docs/features/short-link)

---

## 공개 API

외부 프로그램에서 채널 데이터를 조회할 수 있어요. API 키는 대시보드에서 발급해요.

**조회 가능한 API 5종** — 출석 · 노래방 · 룰렛 · 신청곡 · 시청자 정보

API 키를 발급할 때 12개 스코프를 고를 수 있지만, 실제로 조회 엔드포인트가 있는 건 위 5종이에요.
나머지(채팅·후원·명령어·매크로·금칙어·마커·가위바위보)는 예약된 스코프라 지금은 데이터를 받을 수 없어요.

- 인증: `Authorization: DDUBOT_API <key>`
- 제한: API 키 15회/분, IP 60회/분
- 키 만료: 3~365일 또는 영구, 채널당 5개

[API 문서 →](/docs/api/overview) · [인증 방법 →](/docs/api/authentication)

---

## 봇 이름 바꾸기

채널 전용 이름의 봇을 신청할 수 있어요. 픽셀봇 · 스텔라이브 봇 · 악몽봇 · 람군 · 다람쥐 봇 등이 이 방식으로 운영 중이에요.

[디스코드에서 신청](https://discord.com/invite/QftHRJCTPZ)

---

## 시작하기

[뚜봇 넣는 방법 →](/docs/getting-started/invite-bot) · [권한 부여 →](/docs/getting-started/permissions) · [설명서 전체 →](/docs)

---

# 출석 명단 API

출처: https://chzzk-bot.ddutto.com/docs/api/attendances
설명: 채널의 시청자 출석 집계를 조회하는 API입니다.

**참고**

이 API를 사용하려면 `read.attendance` 권한이 필요해요.
키는 한글이라 **헤더에 넣기 전에 퍼센트 인코딩**해야 해요. [인증 방법 →](/docs/api/authentication)

## 출석 명단 조회

**GET /api/v1/attendances**

시청자 UID를 키로 하는 출석 집계 객체를 반환해요.

### 요청 정보

이 엔드포인트는 별도의 Query Parameter나 Request Body를 사용하지 않아요.

### 응답 필드

| 필드 | 타입 | 설명 |
|------|------|------|
| `data` | object | 시청자 UID를 키로 갖는 출석 정보 맵 |
| `data.<viewer_uid>` | object | 특정 시청자의 출석 정보 |
| `data.<viewer_uid>.count` | number | 총 출석 횟수 |
| `data.<viewer_uid>.combo` | number | 현재 연속 출석 횟수 |
| `data.<viewer_uid>.last` | string | 마지막 출석 시각 |

### 응답 구조

`data`는 배열이 아니라 객체예요. 각 속성명은 시청자 UID이며, 값으로 해당 시청자의 출석 요약이 들어가요.

```json
{
  "success": true,
  "data": {
    "4c3a50fe635854036b4dcf15c9a4d0a2": {
      "count": 21,
      "combo": 2,
      "last": "2025-12-14 15:00:04"
    }
  }
}
```

**참고**

출석 데이터가 없는 경우 `data`는 빈 객체 `{}` 로 반환돼요.

**요청**

_cURL_
```bash
curl -X GET "https://chzzk-bot.ddutto.com/api/v1/attendances" \
  -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"
```
_JavaScript_
```javascript
const API_KEY = 'YOUR_API_KEY';   // 대시보드에서 복사한 한글 키
const response = await fetch(
  'https://chzzk-bot.ddutto.com/api/v1/attendances',
  {
    headers: {
      'Authorization': 'DDUBOT_API ' + encodeURIComponent(API_KEY)
    }
  }
);

const data = await response.json();
for (const [viewerUid, attendance] of Object.entries(data.data)) {
  console.log(viewerUid, attendance.count, attendance.combo, attendance.last);
}
```
_Python_
```python
import requests
from urllib.parse import quote

API_KEY = 'YOUR_API_KEY'   # 대시보드에서 복사한 한글 키

response = requests.get(
    'https://chzzk-bot.ddutto.com/api/v1/attendances',
    headers={'Authorization': 'DDUBOT_API ' + quote(API_KEY)}
)

data = response.json()
for viewer_uid, attendance in data['data'].items():
    print(viewer_uid, attendance['count'], attendance['combo'], attendance['last'])
```

**응답 200 — 성공**

  **응답**

```json
{
    "success": true,
    "data": {
      "4c3a50fe635854036b4dcf15c9a4d0a2": {
        "count": 21,
        "combo": 2,
        "last": "2025-12-14 15:00:04"
      },
      "7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e": {
        "count": 3,
        "combo": 1,
        "last": "2025-12-13 09:18:22"
      }
    }
}
```

**응답 403 — 권한 없음**

  **응답**

```json
{
    "success": false,
    "data": {
      "error": "권한이 없습니다. 'read.attendance' scope가 필요합니다."
    }
}
```

---

# 인증 방법

출처: https://chzzk-bot.ddutto.com/docs/api/authentication
설명: 뚜봇 API 인증 방법과 API 키 발급 방법을 안내해요.

## API 키 발급

  1. **대시보드 접속**

뚜봇 대시보드에 로그인해요.

- [대시보드 열기](https://chzzk-bot.ddutto.com/dashboard)

아직 가입 전이면 [대시보드 가입](/docs/getting-started/dashboard-signup) 부터 해주세요.

  2. **설정 페이지로 이동**

좌측 메뉴에서 **'설정'** 을 클릭하고, 페이지 아래쪽의 **'API 키 관리'** 를 찾아요.

채널 주인(스트리머) 계정으로 로그인해야 보여요. 매니저 권한으로는 `스트리머만 확인 및 변경이 가능합니다.` 만 뜹니다.

![대시보드 설정 페이지의 API 키 관리 — 이름과 만료일 목록](/static/docs/api/api-01-keys.png)

  3. **API 키 생성하기**

**'API 키 생성하기'** 버튼을 누르고 아래 세 가지를 정해요.

| 항목 | 선택지 |
|---|---|
| **API 키 이름** | 어디에 쓸 키인지 알아볼 이름 |
| **만료일** | 3 · 7 · 14 · 30 · 60 · 90 · 180 · 365일 또는 **영구**. 기본 선택이 **3일**이라 오래 쓸 키면 꼭 바꿔주세요 |
| **스코프** | 필요한 읽기 권한만 ([전체 목록](#권한-scope)). **최소 1개는 골라야 합니다** — 하나도 안 고르면 `잘못된 값이 입력되었습니다.` 가 나요 |

**만든 뒤에는 고칠 수 없어요**

이름 · 만료일 · 스코프 모두 **생성 이후 수정이 불가능**해요. 바꾸려면 삭제하고 다시 만들어야 해요.

  4. **키 복사해서 저장**

생성된 API 키를 안전한 곳에 저장해요.

**이 창을 닫으면 다시 볼 수 없어요**

새로고침하거나 창을 닫으면 키를 **다시 확인할 수 없어요.** 분실하면 삭제 후 새로 발급받아야 해요.

키는 **한글 256자**로 되어 있어요. 이상해 보여도 정상이에요.

**키는 채널당 5개까지**

목록 위의 `n 개 / 5 개` 가 현재 사용량이에요. 가득 차면 생성 버튼이 비활성화되니 안 쓰는 키를 지워주세요.
**만료된 키는 빨간 취소선**으로 표시돼요.

**키를 남에게 주지 마세요**

키가 있으면 채널의 룰렛 · 신청곡 · 노래방 · 출석 · 시청자 정보를 읽을 수 있어요.
지금은 읽기 전용이라 설정을 바꾸지는 못하지만, 시청자 개인정보가 들어 있어요.
신뢰할 수 없는 사람에게는 절대 전달하지 마세요.

## 인증 방법

### Authorization 헤더

모든 API 요청에 `Authorization` 헤더를 포함해요.

```
Authorization: DDUBOT_API <URL 인코딩한 api_key>
```

**키를 그대로 넣으면 안 돼요**

API 키는 **한글 256자**입니다. HTTP 헤더 값에는 한글을 그대로 실을 수 없어서,
**퍼센트 인코딩(URL 인코딩)** 해서 넣어야 해요. 서버가 받은 뒤 디코딩해서 검증해요.

그대로 넣으면 JavaScript·Python 라이브러리는 요청이 서버에 닿기도 전에 죽고, cURL 은 전송은 되지만 400 을 받아요.

| 언어 | 그대로 넣었을 때 |
|---|---|
| JavaScript `fetch` | `TypeError: Cannot convert argument to a ByteString` |
| Python `requests` | `UnicodeEncodeError: 'latin-1' codec can't encode...` |
| cURL | 전송은 되지만 서버에서 글자가 깨져 `400 잘못된 접근입니다.` |

### 예시

**cURL:** — 미리 인코딩한 키를 붙여넣으세요.
```bash
curl -X GET "https://chzzk-bot.ddutto.com/api/v1/roulette" \
  -H "Authorization: DDUBOT_API %EA%B0%80%EB%82%98%EB%8B%A4..."
```

**JavaScript (fetch):**
```javascript
const API_KEY = 'YOUR_API_KEY';   // 대시보드에서 복사한 한글 키

const response = await fetch('https://chzzk-bot.ddutto.com/api/v1/roulette', {
  method: 'GET',
  headers: {
    'Authorization': 'DDUBOT_API ' + encodeURIComponent(API_KEY)
  }
});

const data = await response.json();
```

**Python (requests):**
```python
import requests
from urllib.parse import quote

API_KEY = 'YOUR_API_KEY'   # 대시보드에서 복사한 한글 키

headers = {
    'Authorization': 'DDUBOT_API ' + quote(API_KEY)
}

response = requests.get(
    'https://chzzk-bot.ddutto.com/api/v1/roulette',
    headers=headers
)

data = response.json()
```

## 권한 (Scope)

API 키를 만들 때 필요한 권한을 골라야 해요. 지금은 **읽기 권한만** 제공하고, 쓰기 · 특수 권한은 선택할 수 있는 항목이 없어요.

**지금 조회 엔드포인트가 있는 스코프**

| Scope | 대시보드 체크박스 | 읽는 것 |
|-------|------|------|
| `read.song-request` | 신청곡 | 신청곡 대기열 |
| `read.karaoke` | 노래방 | 노래방 대기열/완료 목록 |
| `read.roulette` | 룰렛 | 룰렛 목록 및 로그 |
| `read.attendance` | 출석 | 출석 명단 |
| `read.viewer_info` | 시청자 정보 | 시청자 정보 |

**예약 스코프** — 발급 화면에서 고를 수는 있지만, 아직 이 스코프를 쓰는 API가 없어요.

| Scope | 예정 |
|-------|------|
| `read.chat` | 채팅 |
| `read.donation` | 후원 |
| `read.command` | 명령어 |
| `read.macro` | 매크로 |
| `read.banword` | 금칙어 |
| `read.marker` | 마커 |
| `read.rps` | 가위바위보 |

**필요한 권한이 목록에 없다면**

디스코드로 문의해주세요. 검토 후 추가하고 있어요.

## Rate Limit

모든 API는 분당 15회의 요청 제한이 있어요. 이 15회는 **키 하나가 아니라 계정 하나** 기준이라,
키를 여러 개 발급해도 나눠 쓰게 돼요.

응답 헤더에서 Rate Limit 정보를 확인할 수 있어요. 단 **200 · 403 · 429 에만 붙어요.**
400(인증 실패·파라미터 오류)과 500 에는 이 헤더가 없어요.

| 헤더 | 설명 |
|------|------|
| `X-RateLimit-Limit` | 분당 최대 요청 수. 보통 `15`(계정 기준). IP 제한(60회/분)에 걸린 429 에서는 `60` 이 와요 |
| `X-RateLimit-Remaining` | 남은 요청 수 |
| `X-RateLimit-Reset` | 제한 초기화 시각 (**밀리초** 단위 Unix 타임스탬프) |

**참고**

계정 제한(15회/분)과 별개로 **IP 주소 기준 60회/분** 제한도 함께 적용돼요.
[Rate Limiting 자세히 보기 →](/docs/api/overview)

## 오류 응답

인증 실패 시 다음과 같은 오류가 반환돼요.

```json
{
  "success": false,
  "data": {
    "error": "잘못된 접근입니다."
  }
}
```

**인증 실패는 401이 아니라 400입니다**

그리고 오류 메시지는 최상위가 아니라 **`data.error`** 안에 들어 있어요.
`response.error` 를 읽으면 `undefined` 가 나와요.

### 일반적인 오류 원인

| 원인 | 상태 | `data.error` |
|---|---|---|
| `Authorization` 헤더가 없거나 `DDUBOT_API ` 로 시작하지 않음 | 400 | `잘못된 접근입니다.` |
| API 키가 유효하지 않음 (오타·공백·삭제된 키·**만료된 키**) | 400 | `잘못된 접근입니다.` |
| 필요한 Scope 권한이 없음 | 403 | `권한이 없습니다. '...' scope가 필요합니다.` |
| Rate Limit 초과 | 429 | `요청 횟수 제한을 초과했습니다. N초 후에 다시 시도해주세요.` |

**400이 계속 나온다면**

헤더가 없는 경우와 키가 틀린 경우를 **일부러 구분해서 알려주지 않아요.**(키 추측 방지)

- **키를 URL 인코딩했는지** (한글 키를 그대로 넣으면 반드시 실패해요)
- 헤더 이름이 `Authorization` 이 맞는지
- 값이 `DDUBOT_API ` + 공백 한 칸 + 키 형태인지
- 키를 복사할 때 앞뒤 공백이나 줄바꿈이 섞이지 않았는지

이 네 가지를 순서대로 확인해보세요.

## API 키 관리

### 키 재발급

대시보드에서 언제든지 새 API 키를 발급받을 수 있어요.

**새로 만들어도 기존 키는 그대로 살아 있어요**

키는 서로 독립적이에요. 새 키를 만든다고 예전 키가 자동으로 무효화되지 **않아요.**
쓰지 않는 키는 **직접 삭제**해주세요. (5개 제한도 차지해요.)

**봇을 내보내면 키도 멈춰요**

`!퇴장` 으로 봇을 채널에서 내보내면 발급해둔 API 키도 함께 동작을 멈춰요. 다시 초대하면 그대로 다시 씁니다.

### 키 삭제

API 키가 유출된 경우 즉시 대시보드에서 삭제하고 새로 발급받아요. 목록의 **삭제** 버튼을 누르면 그 키만 즉시 무효화돼요.

**경고**

API 키를 공개 저장소나 클라이언트 코드에 노출하지 마세요.

---

## 다음 단계

| 하고 싶은 것 | 문서 |
|---|---|
| 룰렛 목록·기록 가져오기 | [룰렛 API →](/docs/api/roulette) |
| 신청곡 대기열 가져오기 | [신청곡 API →](/docs/api/song-requests) |
| 시청자 정보 조회 | [시청자 정보 API →](/docs/api/user-info) |
| 출석 명단 가져오기 | [출석 명단 API →](/docs/api/attendances) |
| 노래방 목록 가져오기 | [노래방 API →](/docs/api/karaoke) |

---

# 노래방 API

출처: https://chzzk-bot.ddutto.com/docs/api/karaoke
설명: 노래방 대기열/완료 목록 및 오늘 통계를 조회하는 API입니다.

**참고**

이 API를 사용하려면 `read.karaoke` 권한이 필요해요.
키는 한글이라 **헤더에 넣기 전에 퍼센트 인코딩**해야 해요. [인증 방법 →](/docs/api/authentication)

## 노래방 목록 조회

**GET /api/v1/karaoke**

대기열(queue)과 완료 목록(completed), 오늘 통계(stats)를 함께 조회해요.

### 응답 필드

| 필드 | 타입 | 설명 |
|------|------|------|
| `data.queue` | array | 현재 대기열 |
| `data.queue[].id` | number | 신청 고유 ID (2026-08 추가, completed 항목에도 동일하게 포함) |
| `data.queue[].requester.name` | string | 신청자 닉네임 (익명 신청이면 `"익명"` 고정) |
| `data.queue[].requester.uid` | string | 신청자 UID (익명 신청이면 `"anonymous"` 고정) |
| `data.queue[].requester.isAnonymous` | boolean | 익명 신청 여부 |
| `data.completed` | array | 완료된 곡 목록(최대 150개). requester 는 대기열과 똑같이 익명 마스킹돼요 |
| `data.stats` | object | 오늘 노래방 통계 |
| `data.stats.todayCompletedCount` | number | 오늘 완료된 곡 수 |
| `data.stats.currentSongOrderToday` | number\|null | 현재 곡의 오늘 순번(대기열 없으면 null) |
| `eventTimestamp` | number | 서버 이벤트 시각(ms) |

**요청**

_cURL_
```bash
curl -X GET "https://chzzk-bot.ddutto.com/api/v1/karaoke" \
  -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"
```
_JavaScript_
```javascript
const API_KEY = 'YOUR_API_KEY';   // 대시보드에서 복사한 한글 키
const response = await fetch(
    'https://chzzk-bot.ddutto.com/api/v1/karaoke',
    { headers: {
        'Authorization': 'DDUBOT_API ' + encodeURIComponent(API_KEY)
    } }
);

const data = await response.json();
console.log(data.data.queue);
console.log(data.data.completed);
console.log(data.data.stats);
```
_Python_
```python
import requests
from urllib.parse import quote

API_KEY = 'YOUR_API_KEY'   # 대시보드에서 복사한 한글 키

response = requests.get(
    'https://chzzk-bot.ddutto.com/api/v1/karaoke',
    headers={'Authorization': 'DDUBOT_API ' + quote(API_KEY)}
)

data = response.json()
print(data['data']['queue'])
print(data['data']['completed'])
print(data['data']['stats'])
```

**응답 200 — 성공**

  **응답**

```json
{
    "success": true,
    "data": {
      "queue": [
        {
          "id": 501234,
          "title": "대기 곡 A",
          "requester": {
            "name": "신청자1",
            "uid": "4c3a50fe635854036b4dcf15c9a4d0a2",
            "isAnonymous": false
          },
          "requestTime": 1769448705123,
          "sortOrder": 1000,
          "priority": 0,
          "status": "queued"
        }
      ],
      "completed": [
        {
          "id": 501201,
          "title": "완료 곡 Z",
          "requester": {
            "name": "신청자2",
            "uid": "7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e",
            "isAnonymous": false
          },
          "requestTime": 1769447600000,
          "completedTime": 1769448600000,
          "priority": 0,
          "status": "completed"
        }
      ],
      "stats": {
        "todayCompletedCount": 12,
        "currentSongOrderToday": 13
      }
    },
    "eventTimestamp": 1769448706000
}
```

**응답 403 — 권한 없음**

  **응답**

```json
{
    "success": false,
    "data": {
      "error": "권한이 없습니다. 'read.karaoke' scope가 필요합니다."
    }
}
```

---

# API 개요

출처: https://chzzk-bot.ddutto.com/docs/api/overview
설명: 뚜봇 API를 사용하여 외부에서 봇 기능을 연동하는 방법을 안내해요.

**참고**

API는 현재 베타 버전이에요. 일부 기능이 변경될 수 있어요.

## 기본 정보

### Base URL

```
https://chzzk-bot.ddutto.com/api/v1
```

### 요청 형식

- 모든 요청은 HTTPS를 사용해요.
- 인증이 필요한 요청은 `Authorization` 헤더에 API 키를 포함해야 해요.

```
Authorization: DDUBOT_API <URL 인코딩한 api_key>
```

**API 키는 한글이라 인코딩이 필요해요**

키가 **한글 256자**라서 HTTP 헤더에 그대로 실을 수 없어요. **퍼센트 인코딩** 해서 보내세요.

- JavaScript: `'DDUBOT_API ' + encodeURIComponent(apiKey)`
- Python: `'DDUBOT_API ' + urllib.parse.quote(api_key)`
- cURL: 미리 인코딩한 문자열을 붙여넣기

[인증 방법 자세히 →](/docs/api/authentication)

### 응답 형식

모든 응답은 JSON 형식으로 반환돼요.

**성공 응답 예시:**
```json
{
  "success": true,
  "data": { }
}
```

성공 응답의 본문 키는 엔드포인트마다 다릅니다. 대부분 `data` 지만 `/roulette` 만 `roulettes` 예요.

| 엔드포인트 | 본문 키 | 최상위에 함께 오는 것 |
|---|---|---|
| `/roulette` | `roulettes` | — |
| `/roulette/logs` | `data` | `pagination` |
| `/karaoke` · `/song-requests` | `data` | `eventTimestamp` |
| `/attendances` · `/user_info` | `data` | — |

**오류 응답 예시:**
```json
{
  "success": false,
  "data": {
    "error": "오류 메시지"
  }
}
```

**오류 메시지는 `data` 안에 있어요**

오류는 **항상** `data.error` 입니다. `response.error` 가 아니라 **`response.data.error`** 를 읽으셔야 해요.
(성공 응답의 본문 키는 위 표처럼 엔드포인트마다 다르지만, 오류만은 어디서나 `data.error` 로 통일돼 있어요.)

```js
const res = await fetch(url, { headers });
const json = await res.json();
if (!json.success) console.error(json.data.error);   // ← 여기
```

### 오류 코드

| 상태 | 의미 | `data.error` 메시지 |
|---|---|---|
| `400` | 인증 실패 **또는** 요청 파라미터 오류 | 인증 실패는 `잘못된 접근입니다.` · 파라미터 오류는 항목별 안내 |
| `403` | 해당 scope 권한이 없음 | `권한이 없습니다. 'read.roulette' scope가 필요합니다.` |
| `429` | 호출 제한 초과 | `요청 횟수 제한을 초과했습니다. N초 후에 다시 시도해주세요.` |
| `500` | 서버 오류 | `서버 오류가 발생했습니다.` |

**400이 나올 때 — 메시지부터 보세요**

**메시지가 `잘못된 접근입니다.` 인지 아닌지로 원인이 갈립니다.**

`잘못된 접근입니다.` 라면 인증 문제예요. 보안상 "헤더가 없음"과 "키가 틀림"을 구분해서 알려주지 않아요.

- **키를 URL 인코딩했는지** — 한글 키를 그대로 넣으면 반드시 실패해요
- `Authorization` 헤더가 `DDUBOT_API ` 로 시작하는지
- 키를 복사할 때 앞뒤 공백이 섞이지 않았는지

다른 메시지라면 **키는 정상**이고 요청 파라미터가 잘못된 거예요. 인증을 통과한 뒤의 검증 실패도 같은 400 을 씁니다.

| 메시지 | 원인 |
|---|---|
| `잘못된 룰렛 UUID 형식입니다.` | `uuid` 가 UUID 형식이 아님 |
| `page는 1 이상의 정수여야 합니다.` | `page` 값 오류 |
| `limit는 최대 50까지 가능합니다.` | `limit` 이 50 초과 |
| `page가 범위를 초과했습니다.` | 마지막 페이지를 넘김 |
| `viewer_uid와 viewer_nickname은 함께 사용할 수 없습니다.` | `/user_info` 에 두 조건을 동시 지정 |

## 사용 가능한 API

| 엔드포인트 | 메서드 | 설명 | 필요 권한 |
|-----------|--------|------|----------|
| `/roulette` | GET | 룰렛 목록 조회 | `read.roulette` |
| `/roulette/logs` | GET | 룰렛 로그 조회 | `read.roulette` |
| `/song-requests` | GET | 신청곡 대기열 조회 | `read.song-request` |
| `/karaoke` | GET | 노래방 대기열/완료 목록 조회 | `read.karaoke` |
| `/attendances` | GET | 시청자 출석 집계 조회 | `read.attendance` |
| `/user_info` | GET | 시청자 정보 조회 | `read.viewer_info` |

## Rate Limiting

제한은 **두 겹**으로 걸려 있어요. 둘 중 하나라도 걸리면 `429` 가 반환돼요.

| 기준 | 제한 | 설명 |
|---|---|---|
| **계정(채널)** | **분당 15회** | 실질적인 제한. 보통 이쪽에 먼저 걸려요. **같은 계정에서 키를 여러 개 발급해도 15회를 함께 나눠 씁니다** |
| **IP 주소** | 분당 60회 | 같은 IP에서 여러 계정의 키를 돌려 써도 이 상한을 넘을 수 없어요 |

응답 헤더에서 Rate Limit 정보를 확인할 수 있어요. 단 **200 · 403 · 429 에만 붙어요.**
400(인증 실패·파라미터 오류)과 500 에는 이 헤더가 없어요.

| 헤더 | 설명 |
|------|------|
| `X-RateLimit-Limit` | 분당 최대 요청 수. 보통 `15` 이지만, IP 제한에 걸린 429 에서는 `60` 이 와요 |
| `X-RateLimit-Remaining` | 남은 요청 수 |
| `X-RateLimit-Reset` | 제한 초기화 시각 (**밀리초** 단위 Unix 타임스탬프) |
| `Retry-After` | 429일 때만. 몇 **초** 뒤 재시도하면 되는지 |

**`X-RateLimit-Reset` 은 밀리초예요**

초 단위가 아니라 **밀리초**예요. JavaScript라면 `new Date(Number(reset))` 로 바로 쓸 수 있지만,
Python 등에서는 `1000` 으로 나눠야 해요.

**폴링 주기는 5초 이상으로**

분당 15회면 **평균 4초에 한 번**입니다. 여유를 두고 **5~10초 간격**으로 부르시는 걸 권해요.

429를 받으면 `Retry-After` 초만큼 기다렸다 다시 시도하도록 만들어두면 안전해요.

## 다음 단계

API를 사용하려면 먼저 인증 설정이 필요해요.

[인증 방법 →](/docs/api/authentication)

---

# 룰렛 API

출처: https://chzzk-bot.ddutto.com/docs/api/roulette
설명: 룰렛 목록과 결과 기록을 조회하는 API입니다.

**참고**

이 API를 사용하려면 `read.roulette` 권한이 필요해요.
키는 한글이라 **헤더에 넣기 전에 퍼센트 인코딩**해야 해요. [인증 방법 →](/docs/api/authentication)

## 룰렛 목록 조회

**GET /api/v1/roulette**

채널에 등록된 모든 룰렛 목록을 조회해요.

### 응답 필드

| 필드 | 타입 | 설명 |
|------|------|------|
| `roulettes` | array | 룰렛 목록 |
| `roulettes[].uuid` | string | 룰렛 고유 ID (UUID) |
| `roulettes[].name` | string | 룰렛 이름 |
| `roulettes[].price` | number | 룰렛 기본 가격 (치즈). 아래 조건을 만족할 때 이 금액을 후원하면 1회 돌아가요 |
| `roulettes[].items` | array | 룰렛 항목 목록 |
| `roulettes[].items[].name` | string | 항목 이름 |
| `roulettes[].items[].chance` | number | 당첨 확률 (%) |

**꺼진 룰렛도 함께 내려와요**

이 목록은 **삭제되지 않은 룰렛 전부**를 돌려줘요. 꺼놓은 룰렛도 섞여 있어요.

그런데 응답에 활성 여부 필드가 없어서 **켜짐/꺼짐을 구분할 방법이 없어요.**
목록에 있다고 해서 그 룰렛이 돌아가는 상태라고 볼 수 없어요.

`price` 만큼 후원했을 때 실제로 돌려면 이것들이 모두 맞아야 해요.
- **방송 중일 것** — 방송이 꺼져 있으면 후원 룰렛 자체가 돌지 않아요.
- 룰렛이 켜져 있을 것 (확률 합계가 100이 아니면 자동으로 꺼집니다)
- 그 룰렛의 **'룰렛 금액에 맞는 후원 감지시 즉발'** 이 켜져 있을 것 (기본 켜짐)
- 키워드 감지 · 참여 권한 · 참여 제한 조건을 통과할 것
- 후원 종류가 **채팅 후원**일 것 — 기본값이 채팅 후원만이라 영상·미션 후원은 무시돼요.
  매니저 이상이 `!설정 룰렛 후원감지 모두` 를 입력해야 전부 인식해요.

**요청**

_cURL_
```bash
curl -X GET "https://chzzk-bot.ddutto.com/api/v1/roulette" \
  -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"
```
_JavaScript_
```javascript
const API_KEY = 'YOUR_API_KEY';   // 대시보드에서 복사한 한글 키
const response = await fetch(
    'https://chzzk-bot.ddutto.com/api/v1/roulette',
    { headers: {
        'Authorization': 'DDUBOT_API ' + encodeURIComponent(API_KEY)
    } }
);

const data = await response.json();
console.log(data.roulettes);
```
_Python_
```python
import requests
from urllib.parse import quote

API_KEY = 'YOUR_API_KEY'   # 대시보드에서 복사한 한글 키

response = requests.get(
    'https://chzzk-bot.ddutto.com/api/v1/roulette',
    headers={'Authorization': 'DDUBOT_API ' + quote(API_KEY)}
)

data = response.json()
print(data['roulettes'])
```

**응답 200 — 성공**

  **응답**

```json
{
    "success": true,
    "roulettes": [
      {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "name": "일반 룰렛",
        "price": 1000,
        "items": [
          { "name": "1등 - 치킨", "chance": 5.0 },
          { "name": "2등 - 커피", "chance": 15.0 },
          { "name": "꽝", "chance": 80.0 }
        ]
      },
      {
        "uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
        "name": "VIP 룰렛",
        "price": 5000,
        "items": [
          { "name": "대박", "chance": 10.0 },
          { "name": "중박", "chance": 30.0 },
          { "name": "소박", "chance": 60.0 }
        ]
      }
    ]
}
```

**응답 400 — 인증 실패 (헤더 누락 또는 잘못된 API 키)**

  **응답**

```json
{
    "success": false,
    "data": {
        "error": "잘못된 접근입니다."
    }
}
```

---

## 룰렛 로그 조회

**GET /api/v1/roulette/logs**

특정 룰렛의 결과 기록을 페이지네이션으로 조회해요.

**쿼리 파라미터**

| 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| uuid | string | 필수 | 조회할 룰렛의 UUID |
| page | number | 선택 | 페이지 번호 (기본값: 1) |
| limit | number | 선택 | 페이지당 개수 (최대 50) (기본값: 50) |

### 응답 필드

| 필드 | 타입 | 설명 |
|------|------|------|
| `data` | array | 로그 목록 |
| `data[].user.name` | string | 참여자 닉네임 (익명 시 "익명의 후원자") |
| `data[].user.uid` | string | 참여자 UID (익명 시 "anonymous") |
| `data[].meta.isCompleted` | boolean | 사용 처리 완료 여부 (대시보드 룰렛 기록의 '사용 여부') |
| `data[].meta.isTest` | boolean | 테스트 여부 |
| `data[].meta.isAnonymous` | boolean | 익명 참여 여부 |
| `data[].result` | string | 룰렛 결과 |
| `pagination.page` | number | 현재 페이지 |
| `pagination.total` | number | 전체 로그 수 |
| `pagination.totalPages` | number | 전체 페이지 수 |

**요청**

_cURL_
```bash
curl -X GET "https://chzzk-bot.ddutto.com/api/v1/roulette/logs?uuid=550e8400-e29b-41d4-a716-446655440000&page=1&limit=20" \
  -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"
```
_JavaScript_
```javascript
const API_KEY = 'YOUR_API_KEY';   // 대시보드에서 복사한 한글 키
const uuid = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
    `https://chzzk-bot.ddutto.com/api/v1/roulette/logs?uuid=${uuid}&page=1&limit=20`,
    { headers: {
      'Authorization': 'DDUBOT_API ' + encodeURIComponent(API_KEY)
    } }
);

const data = await response.json();
console.log(data.data);       // 로그 목록
console.log(data.pagination); // 페이지네이션 정보
```
_Python_
```python
import requests
from urllib.parse import quote

API_KEY = 'YOUR_API_KEY'   # 대시보드에서 복사한 한글 키

uuid = '550e8400-e29b-41d4-a716-446655440000'
response = requests.get(
    f'https://chzzk-bot.ddutto.com/api/v1/roulette/logs',
    params={'uuid': uuid, 'page': 1, 'limit': 20},
    headers={'Authorization': 'DDUBOT_API ' + quote(API_KEY)}
)

data = response.json()
print(data['data'])        # 로그 목록
print(data['pagination'])  # 페이지네이션 정보
```

**응답 200 — 성공**

  **응답**

```json
{
    "success": true,
    "data": [
      {
        "user": {
          "name": "열혈시청자",
          "uid": "4c3a50fe635854036b4dcf15c9a4d0a2"
        },
        "meta": {
          "isCompleted": true,
          "isTest": false,
          "isAnonymous": false
        },
        "result": "2등 - 커피"
      },
      {
        "user": {
          "name": "익명의 후원자",
          "uid": "anonymous"
        },
        "meta": {
          "isCompleted": false,
          "isTest": false,
          "isAnonymous": true
        },
        "result": "꽝"
      }
    ],
    "pagination": {
      "page": 1,
      "total": 150,
      "totalPages": 8
    }
}
```

**응답 400 — 잘못된 요청**

  **응답**

```json
{
    "success": false,
    "data": {
        "error": "잘못된 룰렛 UUID 형식입니다."
    }
}
```

---

## 오류 코드

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

| `data.error` | HTTP 상태 | 설명 |
|------------|----------|------|
| 잘못된 룰렛 UUID 형식입니다. | 400 | `uuid` 가 없거나 UUID 형식이 아님 |
| page는 1 이상의 정수여야 합니다. | 400 | 페이지 번호 오류 |
| limit는 1 이상의 정수여야 합니다. | 400 | limit 값 오류 |
| limit는 최대 50까지 가능합니다. | 400 | limit 값 초과 |
| page가 범위를 초과했습니다. | 400 | 존재하지 않는 페이지 |
| 잘못된 접근입니다. | **400** | API 키 인증 실패 |
| 권한이 없습니다. 'read.roulette' scope가 필요합니다. | 403 | 권한 없음 |
| 요청 횟수 제한을 초과했습니다. N초 후에 다시 시도해주세요. | 429 | 분당 호출 제한 초과 (계정 15회/분 · IP 60회/분) |
| 서버 오류가 발생했습니다. | 500 | 서버 내부 오류 |

**`limit` 기본값은 50이에요**

`limit` 을 생략하면 한 번에 **50개**를 가져와요. 최대값도 50이에요.
결과가 하나도 없으면 오류가 아니라 `data: []` 와 `pagination.total: 0`, `pagination.totalPages: 0` 이 반환돼요.

---

# 신청곡 API

출처: https://chzzk-bot.ddutto.com/docs/api/song-requests
설명: 현재 신청곡 대기열을 조회하는 API입니다.

**참고**

이 API를 사용하려면 `read.song-request` 권한이 필요해요.
키는 한글이라 **헤더에 넣기 전에 퍼센트 인코딩**해야 해요. [인증 방법 →](/docs/api/authentication)

## 신청곡 대기열 조회

**GET /api/v1/song-requests**

완료되지 않은 신청곡 목록을 순서대로 조회해요.

### 응답 필드

| 필드 | 타입 | 설명 |
|------|------|------|
| `data` | array | 신청곡 목록 |
| `data[].id` | number | 신청곡 고유 ID (2026-08 추가) |
| `data[].title` | string | 곡 제목 |
| `data[].videoId` | string | 유튜브 영상 ID |
| `data[].duration` | number | 영상 길이(초) |
| `data[].requester.name` | string | 신청자 닉네임 (익명 신청이면 `"익명"` 고정) |
| `data[].requester.uid` | string | 신청자 UID (익명 신청이면 `"anonymous"` 고정) |
| `data[].requester.isAnonymous` | boolean | 익명 신청 여부 |
| `data[].requestTime` | number | 신청 시각(ms) |
| `data[].sortOrder` | number | 정렬 순서 값 |
| `data[].priority` | number | 우선순위 |
| `eventTimestamp` | number | 서버 이벤트 시각(ms) |

**요청**

_cURL_
```bash
curl -X GET "https://chzzk-bot.ddutto.com/api/v1/song-requests" \
  -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"
```
_JavaScript_
```javascript
const API_KEY = 'YOUR_API_KEY';   // 대시보드에서 복사한 한글 키
const response = await fetch(
    'https://chzzk-bot.ddutto.com/api/v1/song-requests',
    { headers: {
      'Authorization': 'DDUBOT_API ' + encodeURIComponent(API_KEY)
    } }
);

const data = await response.json();
console.log(data.data);
```
_Python_
```python
import requests
from urllib.parse import quote

API_KEY = 'YOUR_API_KEY'   # 대시보드에서 복사한 한글 키

response = requests.get(
    'https://chzzk-bot.ddutto.com/api/v1/song-requests',
    headers={'Authorization': 'DDUBOT_API ' + quote(API_KEY)}
)

data = response.json()
print(data['data'])
```

**응답 200 — 성공**

  **응답**

```json
{
    "success": true,
    "data": [
      {
        "id": 1243923,
        "title": "예시 곡",
        "videoId": "dQw4w9WgXcQ",
        "duration": 213,
        "requester": {
          "name": "테스트유저",
          "uid": "4c3a50fe635854036b4dcf15c9a4d0a2",
          "isAnonymous": false
        },
        "requestTime": 1769448705123,
        "sortOrder": 1000,
        "priority": 0
      }
    ],
    "eventTimestamp": 1769448706000
}
```

**응답 403 — 권한 없음**

  **응답**

```json
{
    "success": false,
    "data": {
      "error": "권한이 없습니다. 'read.song-request' scope가 필요합니다."
    }
}
```

---

# 시청자 정보 API

출처: https://chzzk-bot.ddutto.com/docs/api/user-info
설명: 시청자의 활동 통계와 출석 정보를 조회하는 API입니다.

**참고**

이 API를 사용하려면 `read.viewer_info` 권한이 필요해요.
키는 한글이라 **헤더에 넣기 전에 퍼센트 인코딩**해야 해요. [인증 방법 →](/docs/api/authentication)

## 시청자 정보 조회

**GET /api/v1/user_info**

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

**쿼리 파라미터**

| 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| viewer_uid | string | 선택 | 조회할 시청자의 UID (쉼표로 구분하여 최대 20명) |
| viewer_nickname | string | 선택 | 조회할 시청자 닉네임 (단일 닉네임만 지원, viewer_uid와 함께 사용할 수 없음) |

**참고**

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

**파라미터 제약**

**`viewer_uid`**
- 쉼표(`,`)로 구분해 **최대 20명**까지 한 번에 조회
- 32자리 소문자 영숫자여야 하며, **대문자로 넣어도 자동으로 소문자 처리**돼요
- 하나라도 형식이 틀리면 전체 요청이 실패해요 (`잘못된 형식 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_
```bash
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"
```
_JavaScript_
```javascript
const API_KEY = 'YOUR_API_KEY';   // 대시보드에서 복사한 한글 키
const viewerUid = '4c3a50fe635854036b4dcf15c9a4d0a2';
const response = await fetch(
    `https://chzzk-bot.ddutto.com/api/v1/user_info?viewer_uid=${viewerUid}`,
    { headers: {
      'Authorization': 'DDUBOT_API ' + encodeURIComponent(API_KEY)
    } }
);

const data = await response.json();
console.log(data.data[0]);
```
_Python_
```python
import requests
from urllib.parse import quote

API_KEY = 'YOUR_API_KEY'   # 대시보드에서 복사한 한글 키

viewer_uid = '4c3a50fe635854036b4dcf15c9a4d0a2'
response = requests.get(
    'https://chzzk-bot.ddutto.com/api/v1/user_info',
    params={'viewer_uid': viewer_uid},
    headers={'Authorization': 'DDUBOT_API ' + quote(API_KEY)}
)

data = response.json()
print(data['data'][0])
```

**응답 200 — 성공**

  **응답**

```json
{
    "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"
        }
      }
    ]
}
```

**응답 400 — 잘못된 요청**

  **응답**

```json
{
    "success": false,
    "data": {
      "error": "viewer_uid 또는 viewer_nickname 파라미터가 필요합니다."
    }
}
```

---

## 여러 시청자 조회

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

**GET /api/v1/user_info**

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

### 사용 예시

```
?viewer_uid=uid1,uid2,uid3
```

**참고**

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

**요청 - 여러 시청자**

_cURL_
```bash
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"
```
_JavaScript_
```javascript
const API_KEY = 'YOUR_API_KEY';   // 대시보드에서 복사한 한글 키
const viewerUids = [
    '4c3a50fe635854036b4dcf15c9a4d0a2',
    '7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e'
];

const response = await fetch(
    `https://chzzk-bot.ddutto.com/api/v1/user_info?viewer_uid=${viewerUids.join(',')}`,
    { headers: {
      'Authorization': 'DDUBOT_API ' + encodeURIComponent(API_KEY)
    } }
);

const data = await response.json();
data.data.forEach(viewer => {
    console.log(viewer.viewer_uid, viewer.user_stats.chatting);
});
```
_Python_
```python
import requests
from urllib.parse import quote

API_KEY = 'YOUR_API_KEY'   # 대시보드에서 복사한 한글 키

viewer_uids = [
    '4c3a50fe635854036b4dcf15c9a4d0a2',
    '7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e'
]

response = requests.get(
    'https://chzzk-bot.ddutto.com/api/v1/user_info',
    params={'viewer_uid': ','.join(viewer_uids)},
    headers={'Authorization': 'DDUBOT_API ' + quote(API_KEY)}
)

data = response.json()
for viewer in data['data']:
    print(viewer['viewer_uid'], viewer['user_stats']['chatting'])
```

**응답 200 — 성공**

  **응답**

```json
{
    "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
        }
      }
    ]
}
```

**응답 400 — 제한 초과**

  **응답**

```json
{
    "success": false,
    "data": {
      "error": "한 번에 최대 20명까지 조회 가능합니다."
    }
}
```

---

## 닉네임으로 조회

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

**GET /api/v1/user_info**

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

### 사용 예시

```
?viewer_nickname=테스터
```

**참고**

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

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

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

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

**요청 - 닉네임 조회**

_cURL_
```bash
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"
```
_JavaScript_
```javascript
const API_KEY = 'YOUR_API_KEY';   // 대시보드에서 복사한 한글 키
const viewerNickname = '테스터';
const response = await fetch(
    `https://chzzk-bot.ddutto.com/api/v1/user_info?viewer_nickname=${encodeURIComponent(viewerNickname)}`,
    { headers: {
      'Authorization': 'DDUBOT_API ' + encodeURIComponent(API_KEY)
    } }
);

const data = await response.json();
console.log(data.data);
```
_Python_
```python
import requests
from urllib.parse import quote

API_KEY = 'YOUR_API_KEY'   # 대시보드에서 복사한 한글 키

viewer_nickname = '테스터'
response = requests.get(
    'https://chzzk-bot.ddutto.com/api/v1/user_info',
    params={'viewer_nickname': viewer_nickname},
    headers={'Authorization': 'DDUBOT_API ' + quote(API_KEY)}
)

data = response.json()
print(data['data'])
```

**응답 200 — 성공**

  **응답**

```json
{
    "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"
        }
      }
    ]
}
```

**응답 200 — 검색 결과 없음**

  **응답 - 빈 배열**

```json
{
    "success": true,
    "data": []
}
```

**응답 400 — 잘못된 요청**

  **응답**

```json
{
    "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자리 소문자 영숫자) |
| 유효한 viewer_uid가 없습니다. | 400 | 파싱 후 유효한 UID 없음 (쉼표만 넣은 경우 등) |
| 한 번에 최대 20명까지 조회 가능합니다. | 400 | 조회 제한 초과 |
| viewer_nickname은 단일 닉네임만 지원합니다. | 400 | 닉네임에 쉼표를 넣어 여러 명을 요청함 |
| viewer_nickname은 한글, 영문, 숫자, 띄어쓰기만 허용되며 최대 10글자입니다. | 400 | 닉네임 형식/길이 위반 |
| 잘못된 접근입니다. | 400 | API 키 인증 실패 |
| 권한이 없습니다. 'read.viewer_info' scope가 필요합니다. | 403 | 권한 없음 |
| 요청 횟수 제한을 초과했습니다. N초 후에 다시 시도해주세요. | 429 | 분당 호출 제한 초과 (계정 15회/분 · IP 60회/분) |
| 서버 오류가 발생했습니다. | 500 | 서버 내부 오류 |

---

# 기본 명령어

출처: https://chzzk-bot.ddutto.com/docs/commands/basic
설명: 뚜봇의 기본 명령어와 권한 등급을 안내해요. 시청자용 명령어부터 스트리머 전용 명령어까지 정리했어요.

**모든 명령어는 채팅창에 입력해요**

기본 접두사는 `!` 예요. (예: `!업타임`)

명령어마다 쓸 수 있는 사람이 정해져 있어요. 아래에서 등급별로 설명해요.

---

## 명령어 권한 등급

| 등급 | 누가 쓸 수 있나 |
|---|---|
| **시청자** | 채팅에 참여하는 누구나 |
| **구독자** | 채널을 구독 중인 시청자 |
| **매니저** | 채널 관리자 · 채팅 관리자 + 스트리머 |
| **스트리머** | 채널 주인만 |

**참고**

`!명령어` 목록에서 **내장 명령어**는 내가 쓸 수 있는 것만 나와요. 스트리머와 시청자가 보는 목록이 다른 이유예요.
직접 만든 **커스텀 명령어**는 권한과 무관하게, `명령어 목록에 포함 여부` 가 켜져 있으면 전부 나와요.

### 전체 목록은 대시보드에서

대시보드의 **시스템 명령어** 페이지에서 목록에 공개된 내장 명령어를 한눈에 볼 수 있어요. 각 명령어의 필요 권한과 쿨타임도 함께 표시돼요.
`!추가` · `!임티모드` 같은 별칭과 일부 매니저 전용 명령어는 이 페이지에 나오지 않아요.

![대시보드 시스템 명령어 목록 — 명령어별 필요 권한과 쿨타임](/static/docs/system/sys-01-list.png)

**이 목록은 고칠 수 없어요**

시스템 명령어는 봇에 내장된 것이라 **삭제·수정할 수 없어요.** 내가 만든 명령어는 **유저 명령어** 페이지에서 관리해요.

특정 시스템 명령어를 쓰고 싶지 않다면 지우는 대신 `!설정 명령어 비활성화 <명령어>` 로 꺼두세요.
별칭은 따로 끌 수 없어요. `!등록` 을 꺼도 `!추가` 는 그대로 동작해요.
[시스템 설정에서 자세히 →](/docs/commands/system)

---

## 시청자가 쓰는 명령어

기본으로 제공되는 시청자용 명령어는 두 가지예요.

- !업타임 — 방송이 시작된 뒤 얼마나 지났는지 알려줘요. / 예: !업타임 / 봇 응답: 업타임: 2시간 30분 15초 / 쿨타임 10s

- !명령어 — 지금 내가 쓸 수 있는 명령어 목록을 보여줘요. / 예: !명령어 / 봇 응답: 명령어: !업타임, !명령어, !출석 ... / 쿨타임 10s

**시청자용 명령어를 더 만들고 싶다면**

`!인사`, `!디코`, `!사양` 같은 명령어는 **직접 만들어야** 해요. 만드는 방법은 [커스텀 명령어](/docs/commands/custom)를 봐주세요.

룰렛·출석·노래신청은 **전용 변수**를 제공해요. 그 변수를 넣은 커스텀 명령어를 직접 만들면 시청자용 명령어가 늘어나요. (기능을 켠다고 명령어가 저절로 생기지는 않아요)

---

## 매니저가 쓰는 명령어

방송 운영 중에 자주 쓰는 명령어들이에요.

### 명령어 관리

| 명령어 | 하는 일 |
|---|---|
| `!등록` (또는 `!추가`) | 새 명령어 만들기 |
| `!수정` | 등록한 명령어 고치기 |
| `!제거` (또는 `!삭제`) | 등록한 명령어 지우기 |

자세한 사용법은 [커스텀 명령어](/docs/commands/custom)를 봐주세요.

### 방송 설정

| 명령어 | 하는 일 |
|---|---|
| `!방제변경` | 방송 제목 바꾸기 |
| `!게임변경` | 방송 카테고리 바꾸기 |
| `!태그` | 태그 바꾸기 |
| `!연령제한` | 연령 제한 설정 |
| `!클립설정` | 클립 허용 여부 |

자세한 사용법은 [방송 설정](/docs/commands/broadcast)을 봐주세요.

### 채팅 관리

| 명령어 | 하는 일 |
|---|---|
| `!금칙어` | 금지 단어 관리 |
| `!이모티콘모드` | 이모티콘만 허용 |
| `!저속모드` | 채팅 속도 제한 |
| `!채팅모드` | 채팅 모드 변경 |
| `!매크로` | 반복 메시지 설정 |
| `!고정메세지` | 방송 시작 시 자동 공지 |

### 기능

| 명령어 | 하는 일 | 문서 |
|---|---|---|
| `!팔로우알림` | 팔로우 알림 켜기/끄기 | [보기](/docs/features/follow-alert) |
| `!타이머` | 카운트다운 타이머 | [보기](/docs/features/timer-counter) |
| `!카운터` | 숫자 세기 | [보기](/docs/features/timer-counter) |
| `!설정` | 봇 전반 설정 | [보기](/docs/commands/system) |
| `!재입장` | 봇 다시 부르기 |  |

---

## 스트리머만 쓰는 명령어

- !퇴장 — 봇을 채널에서 내보내요. 인증번호를 받은 뒤 한 번 더 입력해야 해요. 1차 입력 때 봇이 '모든 데이터가 제거됩니다' 라는 경고를 함께 보내요. / 예: !퇴장 / 쿨타임 1s / (`!퇴장` 을 치면 인증번호가 나와요. `!퇴장 1234567890` 처럼 그 번호를 붙여 다시 입력해야 실제로 나가요.)

- !도배 [메시지] — 입력한 메시지를 여러 번 반복해서 보내요. / 예: !도배 이벤트 시작합니다! / 쿨타임 3m / (스트리머만 사용할 수 있어요. 쿨타임이 3분이므로 중요한 공지일 때만 사용해요.)

**!도배는 필요할 때만**

쿨타임이 **3분**이에요. 채팅창을 순식간에 채우는 기능이라 자주 사용하면 시청자가 피로해해요. 이벤트 공지처럼 정말 필요할 때만 사용해요.

---

## 자주 묻는 것

### 명령어를 쳤는데 반응이 없어요

| 확인할 것 | 해결 |
|---|---|
| 권한이 맞나요? | 매니저·스트리머 전용 명령어일 수 있어요 |
| 쿨타임이 아닌가요? | `!업타임` 은 10초, `!도배` 는 3분 쿨타임이에요 |
| 봇이 채널에 있나요? | [봇 초대](/docs/getting-started/invite-bot)를 확인해보세요 |
| 방송이 꺼져 있나요? | 명령어 자체는 동작해요. 다만 `!업타임` 처럼 방송 정보를 쓰는 명령어는 `업타임: [방송중이 아님]` 으로 답해요 |

### 접두사 `!` 를 바꿀 수 있나요?

기본 명령어(`!업타임`, `!설정` 등)의 접두사는 바꿀 수 없어요.

다만 **직접 만드는 명령어는 이름을 자유롭게 정할 수 있어요.** `!` 가 아닌 다른 기호로
시작해도 되고, 기호 없이 만들어도 돼요.

```
!추가 ?인사 안녕하세요!
```

### 명령어 목록에 안 보이는 명령어가 있어요

일부 명령어는 **별칭**이라 목록에 표시되지 않아요. 예를 들어 `!추가` 는 `!등록` 의 별칭이고, `!삭제` 는 `!제거` 의 별칭이에요. 둘 다 똑같이 동작해요.

---

## 다음 단계

[커스텀 명령어 만들기 →](/docs/commands/custom) · [시스템 설정 →](/docs/commands/system) · [변수 →](/docs/commands/variables)

**더 궁금한 점이 있나요?**

  [디스코드](https://discord.com/invite/QftHRJCTPZ)에서 편하게 문의해주세요!

---

# 방송 설정

출처: https://chzzk-bot.ddutto.com/docs/commands/broadcast
설명: 방제·카테고리·태그 변경부터 채팅모드, 저속모드, 금칙어, 매크로, 타이머까지 방송 운영 명령어 전체를 안내해요.

방송 제목, 카테고리, 금칙어, 매크로까지 채팅 명령어로 바로 설정할 수 있어요.

**권한 용어 안내**

이 문서에서 사용하는 권한 용어를 구분해주세요:

- **매니저**: 명령어를 사용하는 **사람**에게 필요한 권한. 채널 매니저와 **스트리머 본인**이 해당돼요 (권한은 서열이라 스트리머는 매니저 명령어를 전부 쓸 수 있어요).
- **채팅 운영자 / 채널 관리자**: **봇**이 채널에서 가지고 있어야 하는 권한. 일부 기능(임시 차단, 팔로우 알림 등)을 실행하려면 봇에게 해당 권한이 부여되어 있어야 해요.

---

## 방송 제목 변경

채팅창에서 방송 제목을 바로 바꿀 수 있어요.

- !방제변경 [제목] — 방송 제목을 변경해요. / 예: !방제변경 [배그] 오늘도 치킨 먹으러 갑니다 / 봇 응답: 방송 제목이 변경되었습니다: [배그] 오늘도 치킨 먹으러 갑니다 / 쿨타임 1s

**참고**

`!방제변경`, `!방재변경`, `!방송제목변경`, `!제목변경` 모두 같은 명령어예요!
(`!방재변경` 은 오타로 자주 치는 걸 감안해 일부러 넣어두었어요.)

**명령어 사용 권한**

이 페이지의 명령어는 **매니저** 이상이면 쓸 수 있어요.
단, `!퇴장` 과 `!도배` 는 **스트리머 본인**만 쓸 수 있습니다.

**대시보드 연동으로 권한 없이 사용하기**

대시보드에서 치지직 계정을 연동하면, 봇에게 채널 관리자 권한을 부여하지 않아도 방송 제목을 변경할 수 있어요!
[권한 부여 방법 →](/docs/getting-started/permissions)

---

## 방송 카테고리 변경

방송 카테고리를 바꿀 수 있어요.

- !게임변경 [카테고리] — 방송 카테고리를 변경해요. / 예: !게임변경 리그 오브 레전드 / 봇 응답: 방송 게임이 변경되었습니다: 리그 오브 레전드 / 쿨타임 1s

**단축어 사용 가능**

- `롤` → 리그 오브 레전드
- `배그` → PUBG: 배틀그라운드
- `talk` (= `토크` · `저챗` · `수다` · `채팅`) → talk 카테고리

카테고리 앞에 `!`를 붙이면 네이버에 등록되지 않은 카테고리도 사용할 수 있어요!
(단, 시청자가 검색으로 찾을 수 없어요)

**참고**

`!게임변경`, `!카테고리변경`, `!카테고리` 모두 같은 명령어예요!

**대시보드 연동으로 권한 없이 사용하기**

대시보드에서 치지직 계정을 연동하면, 봇에게 채널 관리자 권한을 부여하지 않아도 방송 카테고리를 변경할 수 있어요!
[권한 부여 방법 →](/docs/getting-started/permissions)

---

## 연령 제한 설정

방송에 연령 제한을 걸 수 있어요.

- !연령제한 [켜기/끄기] — 방송의 연령 제한 여부를 설정해요. / 예: !연령제한 켜기 / 봇 응답: 시청자를 19세로 제한합니다. / 쿨타임 1s

**기본값**: 꺼짐

**참고**

뚜사봇, 뚜오봇, 뚜구봇은 실명 인증이 되지 않아서 연령 제한 방송에 접근할 수 없어요.
연령 제한 방송에서는 **뚜봇, 뚜이봇, 뚜삼봇, 뚜육봇, 뚜칠봇, 뚜팔봇** 중 하나를 사용해주세요.

**봇 권한 필요**

연령 제한 설정을 사용하려면 **봇**에 **채널 관리자** 권한이 부여되어 있어야 해요.
이 기능은 대시보드 연동으로는 사용할 수 없어요.
[권한 부여 방법 →](/docs/getting-started/permissions)

---

## 태그 변경

방송 태그를 추가하거나 뺄 수 있어요.

- !태그 추가 [태그] [태그2] ... — 방송 태그를 추가해요. 여러 개를 한 번에 넣을 수 있어요. / 예: !태그 추가 롤 솔랭 다이아 / 쿨타임 1s

- !태그 제거 [태그] — 방송 태그를 제거해요. / 예: !태그 제거 솔랭 / 쿨타임 1s

**태그는 최대 5개**

5개가 이미 차 있으면 `태그는 최대 5개까지만 추가할 수 있습니다.` 가 나와요.
같은 태그를 또 넣으면 `해당 태그가 이미 존재합니다.` 가 나와요.

**봇 권한 필요**

**봇**에 **채널 관리자** 권한이 있거나, 대시보드에서 **치지직 계정을 연동**해두어야 해요.
[권한 부여 방법 →](/docs/getting-started/permissions)

---

## 채팅 참여 제한 (채팅 모드)

채팅을 할 수 있는 시청자를 정할 수 있어요.

- !채팅모드 [모두/팔로워/구독/관리자] — 채팅을 칠 수 있는 시청자 범위를 설정해요. / 예: !채팅모드 팔로워 / 봇 응답: 이제, 팔로우 0분 이상인 시청자만 채팅이 가능합니다. / 쿨타임 1s

| 값 | 채팅 가능한 사람 |
|---|---|
| `모두` | 전체 시청자 |
| `팔로워` (`팔로우`) | 팔로워만 |
| `구독` (`구독자`) | 구독자만 |
| `관리자` | 스트리머와 매니저 전체 |

**팔로우한 지 N분 지난 사람만**

`팔로워` 뒤에 숫자를 붙이면 **팔로우 경과 시간**으로 거를 수 있어요. 팔로우 후 바로 도배하는 걸 막는 데 효과적이에요.

```
!채팅모드 팔로워 30
```
→ `이제, 팔로우 30분 이상인 시청자만 채팅이 가능합니다.`

숫자를 생략하면 0분(= 팔로우만 했으면 OK)으로 설정돼요.

**쓸 수 있는 숫자가 정해져 있어요**

대시보드에서 치지직 계정만 연동한 경우(봇에 채널 관리자 권한이 없는 경우)
쓸 수 있는 값은 **0, 5, 10, 30, 60, 1440(1일), 10080(7일), 43200(30일)** 뿐이에요.
그 외 숫자를 넣으면 `채팅 모드 변경에 실패했습니다: 데이터를 변경하지 못했습니다.` 만 나오고
이유는 따로 안내되지 않으니 주의하세요.

---

## 저속 모드

시청자가 채팅을 너무 자주 칠 수 없도록 간격을 정할 수 있어요.

- !저속모드 [초/끄기] — 채팅 간 최소 간격을 설정해요. / 예: !저속모드 10 / 봇 응답: 저속 모드를 설정하였습니다. / 쿨타임 1s

**정해진 값만 쓸 수 있어요**

치지직이 허용하는 값은 **0, 3, 5, 10, 30, 60, 120, 300** 뿐이에요.
그 외 숫자를 넣으면 `시간은 0, 3, 5, 10, 30, 60, 120, 300 중 하나여야 합니다.` 가 나와요.

끄려면 `!저속모드 끄기` 또는 `!저속모드 0` 입니다.

---

## 이모티콘 전용 모드

이모티콘만으로 채팅하도록 제한할 수 있어요.

- !이모티콘모드 [켜기/끄기] — 채팅을 이모티콘 전용 모드로 전환해요. / 예: !이모티콘모드 켜기 / 봇 응답: 채팅을 이모티콘 전용 모드로 변경하였습니다. / 쿨타임 1s

**참고**

`!임티모드` 로 입력해도 똑같이 동작해요.

**팁**

잠깐 자리를 비우거나, 스포일러가 걱정될 때 쓰면 좋아요.

---

## 클립 설정

방송 클립 생성을 허용할지 정할 수 있어요.

- !클립설정 [열기/닫기] — 클립 생성 허용 여부를 설정해요. / 예: !클립설정 닫기 / 쿨타임 1s / (명령어 사용 권한은 매니저예요.)

**봇 권한 필요**

연령 제한과 마찬가지로 **봇에게 채널 관리자 권한이 있어야** 해요.
대시보드 계정 연동만으로는 안 돼요.
[권한 부여 방법 →](/docs/getting-started/permissions)

---

## 금칙어 설정

특정 단어를 채팅에서 제한할 수 있어요.

**참고**

매니저 이상(스트리머 본인 포함)은 금칙어 검사 대상이 아니에요.
또 봇에 **채팅 운영자** 권한이나 대시보드 계정 연동이 없으면 `!금칙어` 명령어 자체가 거부돼요 — 추가·제거·목록·켜기/끄기 전부요.
방금 등록한 금칙어를 직접 쳐보면 아무 일도 일어나지 않으니, 시험은 일반 시청자 계정으로 하세요.

- !금칙어 추가 [단어] — 금칙어를 추가해요. 해당 단어를 입력한 시청자에게 제재가 적용돼요. / 예: !금칙어 추가 바보 / 봇 응답: 입력하신 키워드가 추가되었습니다. / 쿨타임 1s

- !금칙어 제거 [단어] — 금칙어를 제거해요. / 예: !금칙어 제거 바보 / 봇 응답: 입력하신 키워드가 제거되었습니다. / 쿨타임 1s

- !금칙어 목록 — 현재 켜져 있는 금칙어만 보여줘요. / 예: !금칙어 목록 / 쿨타임 1s / (`!금칙어 끄기` 로 꺼둔 단어는 목록에 나오지 않아요. 대시보드 금칙어 페이지에서 확인해보세요.)

- !금칙어 [켜기/끄기] [단어] — 금칙어를 지우지 않고 잠시 켜고 꺼요. / 예: !금칙어 끄기 바보 / 쿨타임 1s / (`온` / `오프` 로 입력해도 동일하게 동작해요.)

**지우지 말고 꺼두세요**

특정 방송에서만 잠깐 풀고 싶은 금칙어가 있다면, 제거하지 말고 `!금칙어 끄기 <단어>` 로 꺼두세요.
나중에 `!금칙어 켜기 <단어>` 로 되살릴 수 있어 다시 등록할 필요가 없어요.

### 금칙어 대시보드에서 관리하기

명령어로 추가한 금칙어는 대시보드 **금칙어** 페이지에 그대로 나와요.

다만 **이미 등록된 금칙어의 제재 타입은 바꿀 수 없어요.** 목록에서 할 수 있는 건 켜기/끄기와 삭제뿐이에요.
타입을 바꾸려면 지우고 원하는 타입으로 다시 추가하세요. (`!금칙어 추가` 로 등록하면 '유저 타임아웃' 으로 고정돼요)

![대시보드 금칙어 목록 — 단어별 제재 타입과 켜기/끄기 토글](/static/docs/broadcast/fw-01-list.png)

| 제재 타입 | 무슨 일이 일어나나 |
|---|---|
| **메세지 블라인드(삭제)** | 그 메시지만 지워져요 (기본값) |
| **유저 타임아웃(임시 제한)** | 일정 시간 채팅이 막힙니다 |
| **유저 활동제한(영구 벤)** | 채널에서 영구 차단돼요 |

오른쪽 **토글**이 `!금칙어 켜기/끄기` 와 같아요. 끈 금칙어는 목록에 남아 있지만 동작하지 않아요 (위 그림의 4번).

**추가** 버튼을 누르면 단어와 제재 타입을 함께 지정할 수 있어요.

![금칙어 추가 창 — 단어 입력과 제재 타입 선택](/static/docs/broadcast/fw-02-add.png)

**여러 개를 한 번에**

추가 창 오른쪽 위의 **'한번에 추가하기'** 를 켜면 여러 단어를 **쉼표(,)로 구분해** 한 번에 등록할 수 있어요.
공백으로 나열하면 통째로 금칙어 하나가 됩니다.

**봇 권한 필요**

**유저 타임아웃**, **유저 활동제한** 제재가 작동하려면 봇에 **채팅 운영자** 권한이 있거나,
대시보드에서 **치지직 계정을 연동**해두어야 해요. (메시지 삭제도 마찬가지예요.)
[권한 부여 방법 →](/docs/getting-started/permissions)

### 금칙어 모드

금칙어 감지 방식을 변경할 수 있어요.

- !설정 금칙어 모드 [일반/엄격] — 금칙어 감지 모드를 설정해요. / 예: !설정 금칙어 모드 엄격 / 봇 응답: 금칙어 모드가 엄격 모드로 설정되었습니다. / 쿨타임 1s

**엄격 모드**에서는 이렇게 우회해도 감지돼요:
- `24학점` 금칙어일 때 → `24👀학점`, `2 4 학점`, `12+12학점` 등도 감지
- 이모티콘 · 특수문자 · 공백으로 사이를 끊어도 감지하고, 숫자 계산식도 풀어서 봅니다

그래도 완벽하지는 않으니, 자주 쓰이는 변형은 금칙어로 함께 등록해두시는 걸 권해요.

---

## 고정 메시지 설정

방송이 시작될 때 자동으로 고정할 메시지를 설정할 수 있어요.
설정하면 그 자리에서 한 번 고정되고, 이후 방송이 시작될 때마다 다시 고정돼요.

- !고정메시지 [메시지] — 방송 시작 시 자동으로 고정될 메시지를 설정해요. / 예: !고정메시지 환영합니다! 채팅 규칙을 지켜주세요. / 봇 응답: 고정 메세지가 설정되었습니다. / 쿨타임 1s

- !고정메시지 제거 — 자동 고정 메시지를 비활성화해요. / 예: !고정메시지 제거 / 봇 응답: 고정 메세지가 제거되었습니다. / 쿨타임 1s

**해제는 채팅 운영자 권한이 필요해요**

고정 메시지 **설정**은 계정 연동만으로 되지만, **해제**는 봇에게 채팅 운영자 권한이 있어야 해요.

권한이 없으면 봇에 저장된 값만 지워지고 이렇게 답해요.

> 봇 데이터는 삭제하였지만, 치지직 공식 API에는 고정 해제가 없습니다.. ;ㅅ;

이때 치지직 채팅창 상단의 고정은 그대로 남으니, 치지직에서 직접 풀어주세요.

**팁**

고정 메시지 앞에 `!`를 붙이면 방송 시작 시 다시 고정하지 않고, 지금 딱 한 번만 고정돼요!

**참고**

`!고정메세지`, `!고정메시지`, `!고정` 모두 같은 명령어예요!

**대시보드 연동으로 권한 없이 사용하기**

대시보드에서 치지직 계정을 연동하면, 봇에게 채팅 운영자 권한을 부여하지 않아도 고정 메시지를 설정할 수 있어요!
[권한 부여 방법 →](/docs/getting-started/permissions)

---

## 팔로우 알림

새 팔로워가 생기면 채팅창에 알림을 보낼 수 있어요.

- !팔로우알림 메세지 [메시지] — 팔로우 알림 메시지를 설정해요. / 예: !팔로우알림 메세지 $nick님 팔로우 감사합니다! / 봇 응답: 팔로우 알림 메세지를 '$nick님 팔로우 감사합니다!'로 설정합니다. / 쿨타임 1s

- !팔로우알림 [켜기/끄기] — 팔로우 알림을 켜거나 꺼요. / 예: !팔로우알림 켜기 / 봇 응답: 팔로우 알림을 켭니다. / 쿨타임 1s

- !팔로우알림 테스트 — 설정한 알림 메시지가 어떻게 나오는지 바로 확인해요. / 예: !팔로우알림 테스트 / 쿨타임 1s / (알림이 꺼져 있으면 `팔로우알림이 꺼져있습니다.` 만 나와요. `!팔로우알림 켜기` 를 먼저 하세요.)

**팁**

메시지를 바꾼 뒤 **실제 팔로워를 기다리지 말고** `!팔로우알림 테스트` 로 바로 확인해보세요. (알림을 켜둔 상태여야 해요)
`!팔로우알림` 만 입력하면 켜짐/꺼짐 상태를, `!팔로우알림 메세지` 만 입력하면 지금 설정된 메시지를 알려줘요.

사용 가능한 변수:
- `$nick` - 팔로우한 사람의 닉네임
- `$followCount` - 총 팔로워 수

**기본값**: 꺼짐

**참고**

`!팔로우알람` 으로 입력해도 똑같이 동작해요.

**봇 권한 필요**

이 기능을 사용하려면 **봇**에 **채널 관리자** 권한이 부여되어 있어야 해요.
권한 슬롯이 부족하다면 지원 디스코드의 `#팔로우알림-우회-신청` 에 신청하세요. 운영자가 승인하면 권한 없이도 동작하도록 등록해줍니다.
[권한 부여 방법 →](/docs/getting-started/permissions)

**다른 봇이 함께 있으면 동작하지 않아요**

채널에 다른 채팅봇이 같이 들어와 있으면 팔로우 알림이 나가지 않아요.
[팔로우 알림 자세히 보기 →](/docs/features/follow-alert)

---

## 매크로 설정

일정 시간 간격으로 정한 메시지를 자동으로 보낼 수 있어요.

- !매크로 추가 [시간(초)] [메시지] — 매크로를 추가해요. 최소 60초(1분) 이상이어야 해요. / 예: !매크로 추가 300 5분마다 나오는 메시지입니다! / 봇 응답: 설정 완료. 300초, '5분마다 나오는 메시지입니다!' / 쿨타임 1s

**1분(60초) 미만은 등록되지 않아요**

`시간은 1분 이상으로 입력해주세요.` 라는 안내가 나타나요.
이미 등록된 것과 똑같은 메시지는 중복으로 추가되지 않아요.

- !매크로 목록 — 설정된 매크로 목록을 확인해요. / 예: !매크로 목록 / 봇 응답: [0번] 300초 | 5분마다 나오는 메시지입니다! / 쿨타임 1s

**번호는 0번부터 시작해요**

첫 번째 매크로가 **1번이 아니라 0번**이에요.
제거·켜기·끄기를 할 때 `!매크로 목록` 으로 번호를 먼저 확인해보세요.

- !매크로 제거 [번호] — 특정 번호의 매크로를 삭제해요. / 예: !매크로 제거 0 / 봇 응답: 0번 매크로가 제거되었습니다. / 쿨타임 1s

- !매크로 [켜기/끄기] [번호] — 매크로를 지우지 않고 잠시 멈추거나 다시 켜요. / 예: !매크로 끄기 0 / 쿨타임 1s / (`온` / `오프` 로 입력해도 동일하게 동작해요.)

- !설정 매크로 출력순서 [순서대로/랜덤] — 여러 매크로가 있을 때 출력 순서를 설정해요. / 예: !설정 매크로 출력순서 랜덤 / 쿨타임 1s

**출력 방식도 정할 수 있어요**

`!설정 매크로 출력방식 채팅감지` 로 바꾸면 **채팅이 있을 때만** 매크로가 나가요.
시청자가 없을 때 봇 혼자 떠드는 게 어색하다면 추천해요.

[시스템 설정에서 자세히 보기 →](/docs/commands/system)

**참고**

`!메크로` 로 입력해도 똑같이 동작해요.

### 매크로 대시보드에서 관리하기

대시보드 **매크로** 페이지에서 목록을 보고 수정할 수 있어요.

![대시보드 매크로 목록 — 메시지, 주기, 켜기/끄기 토글](/static/docs/broadcast/macro-01-list.png)

**🚨 번호가 명령어와 한 칸 다릅니다**

대시보드는 **1번부터**, 채팅 명령어는 **0번부터** 셉니다.
화면의 **1번** 매크로를 지우려면 `!매크로 제거 0` 입니다.

헷갈리면 `!매크로 목록` 으로 번호를 먼저 확인해보세요.

| 화면 | 하는 일 |
|---|---|
| **메세지** | 봇이 보낼 내용 |
| **시간(초)** | 몇 초마다 보낼지. 화면 안내는 최소 30초, 채팅 `!매크로 추가` 는 최소 60초 |
| **토글** | `!매크로 켜기/끄기` 와 같아요. 끄면 목록에는 남지만 나가지 않아요 |
| **수정 / 삭제** | 내용·주기 변경, 목록에서 제거 |

**동시에 나가지 않아요**

매크로는 **순서대로 하나씩** 돕니다. 1번이 나간 뒤에 2번, 그 다음 3번이에요.
그래서 주기를 10분 이상으로 잡으면 매크로가 멈춘 것처럼 보일 수 있어요.

---

## 타이머 · 카운터

방송 화면에 카운트다운 타이머나 숫자를 표시할 수 있어요.

- !타이머 추가 [시간] [타이머 이름] — 타이머를 생성해요. / 예: !타이머 추가 10분 휴식시간 / 봇 응답: '휴식시간' 타이머가 설정되었어요. 600초 뒤에 알려드릴게요! / 쿨타임 1s

- !카운터 추가 [목표 값] [카운터 이름] — 카운터를 생성해요. 목표가 없으면 0을 넣으세요. / 예: !카운터 추가 10 데스 / 봇 응답: '데스' 이름의 카운터가 추가되었습니다. 목표 값: 10 / 쿨타임 1s / (`-1` 은 입력은 되지만 목표 없음으로 취급되지 않아 목록에 `/ -1` 이 그대로 붙어요.)

**시간은 한글로 적으면 편해요**

`30분`, `2시간`, `1시간30분45초` 처럼 적으면 돼요.
`600`(초) 이나 `10:00`(분:초), `1:30:00`(시:분:초) 형식도 그대로 동작해요.

**수정할 때는 값이 먼저, 이름이 나중**

- ✅ `!타이머 수정 시간추가 10분 휴식시간`
- ✅ `!카운터 더하기 1 데스`
- ❌ `!타이머 수정 시간추가 휴식시간 10분`
- ❌ `!카운터 더하기 데스 1`

전체 하위 명령어와 오버레이 연결 방법은 전용 문서에서 안내해요.

[타이머 · 카운터 자세히 보기 →](/docs/features/timer-counter)

---

## 봇 관리

- !재입장 — 봇을 채널에서 나갔다가 다시 들어오게 해요. / 예: !재입장 / 쿨타임 10s

**봇이 반응이 없을 때 제일 먼저**

채팅에 반응이 없거나 설정이 반영되지 않을 때 `!재입장` 을 한 번 해보세요.
대부분의 일시적인 문제가 해결돼요.

- !퇴장 — 봇을 채널에서 내보내요. 인증번호를 받은 뒤 한 번 더 입력해야 해요. / 예: !퇴장 / 봇 응답: (주의!) 이 명령어는 봇을 영구히 퇴장시키는 명령어입니다. 모든 데이터가 제거됩니다. 봇을 퇴장시키시려면, `!퇴장 1234567890` 를 입력해주세요. / 쿨타임 1s / (스트리머 본인만 사용할 수 있어요. 안내받은 번호로 `!퇴장 1234567890` 을 다시 입력해야 실제로 나가요.)

- !도배 [메시지] — 같은 메시지를 여러 번 연속으로 보내요. / 예: !도배 축하합니다 / 쿨타임 3m / (스트리머 전용 · 쿨타임 3분. 주의해서 사용하세요.)

**`!도배`는 신중하게**

쿨타임이 **3분**입니다. 채팅창이 순식간에 채워지므로 정말 필요할 때만 사용해요.

---

## 다른 채널과 연결하기

합방할 때 두 채널의 채팅을 연결할 수 있어요.

- !연결 [만들기/접속/허용/나가기] — 다른 채널과 연결방을 만들거나 참여해요. / 예: !연결 만들기 / 쿨타임 1s

| 입력 | 하는 일 |
|---|---|
| `!연결 만들기` | 연결방을 새로 만들어요 |
| `!연결 접속 [방 ID]` | 만들어진 방에 들어가요 |
| `!연결 허용 [허용 코드]` | 들어오려는 채널을 승인해요 |
| `!연결 나가기` | 연결을 끊습니다 |

**참고**

합방 상대 채널에도 뚜봇이 들어와 있어야 해요.

---

## 다음 단계

방송 설정을 마쳤다면, 커스텀 명령어를 만들어보세요!

[커스텀 명령어 →](/docs/commands/custom) · [시스템 설정 →](/docs/commands/system)

---

# 커스텀 명령어

출처: https://chzzk-bot.ddutto.com/docs/commands/custom
설명: 나만의 명령어를 만들고 관리하는 방법을 안내해요.

내가 원하는 명령어를 만들 수 있어요. 채팅창에서 바로 추가하거나 대시보드에서 관리하세요.

---

## 명령어 추가하기

새로운 명령어를 만들어보세요.

**참고**

`!추가` · `!수정` · `!제거` 는 **매니저 이상**만 쓸 수 있어요.
권한이 없으면 봇이 오류 없이 그냥 무시해요. [권한 부여 방법 →](/docs/getting-started/permissions)

- !추가 [명령어] [응답 메시지] — 새로운 커스텀 명령어를 추가해요. / 예: !추가 !인사 안녕하세요! 반갑습니다 :> / 봇 응답: '!인사' 명령어가 추가되었습니다. / 쿨타임 1s

이제 누군가 `!인사`를 입력하면 "안녕하세요! 반갑습니다 :>" 가 그대로 출력돼요!

**팁**

`!추가` 대신 `!등록`을 써도 똑같이 동작해요!

### 기존 명령어에 다른 이름 붙이기

이미 있는 명령어를 다른 이름으로도 부를 수 있어요.

- !추가 [새 명령어] &[기존 명령어] — 기존 명령어를 가리키는 별칭을 만들어요. / 예: !추가 !하이 &!인사 / 봇 응답: '!하이' 명령어가 추가되었습니다. / 쿨타임 1s

**복사본이 아니라 바로가기예요**

`!하이` 는 내용을 베껴 가는 게 아니라 **호출될 때마다 `!인사` 를 찾아서** 그 응답을 써요.

- `!인사` 를 수정하면 `!하이` 도 같이 바뀌어요.
- `!인사` 를 **제거하면** `!하이` 는 대상을 못 찾아 `&!인사` 라는 글자를 그대로 채팅에 뱉어요.
- `!인사` 를 **비활성화만 하면** `!하이` 는 여전히 `!인사` 의 응답을 내요. 별칭까지 막으려면
  `!하이` 도 따로 비활성화하세요.
- 권한은 **둘 다** 통과해야 해요 — 별칭 `!하이` 자신의 권한과 대상 `!인사` 의 권한.
- `!추가` · `!수정` · `!제거` · `!설정` 처럼 **명령어·봇 관리용 기본 제공 명령어는 가리킬 수 없어요.**
  `!팔로우알림` · `!도배` · `!재입장` · `!퇴장` · `!연결` 도 안 돼요.
  (`!업타임` · `!타이머` 처럼 그 밖의 기본 제공 명령어는 가리킬 수 있어요)

---

## 명령어 수정하기

만든 명령어의 내용을 바꿀 수 있어요.

- !수정 [명령어] [새 응답 메시지] — 기존 명령어의 응답을 수정해요. / 예: !수정 !인사 $nick님 안녕하세요! / 봇 응답: '!인사' 명령어가 수정되었습니다. / 쿨타임 1s

**팁**

`!수정` 대신 `!편집`, `!변경`을 써도 똑같이 동작해요!

---

## 명령어 삭제하기

더 이상 필요 없는 명령어를 삭제할 수 있어요.

- !제거 [명령어] — 커스텀 명령어를 삭제해요. / 예: !제거 !인사 / 봇 응답: '!인사' 명령어가 제거되었습니다. / 쿨타임 1s

**팁**

`!제거` 대신 `!삭제`를 써도 똑같이 동작해요!

---

## 랜덤 출력 만들기

여러 응답 중 하나를 무작위로 선택해서 보낼 수 있어요.

- !추가 [명령어] [응답1]||[응답2]||[응답3] — 여러 응답 중 하나를 랜덤으로 출력해요. / 예: !추가 !운세 대길||중길||소길||흉 / 봇 응답: '!운세' 명령어가 추가되었습니다. / 쿨타임 1s

이제 `!운세`를 입력하면 대길, 중길, 소길, 흉 중 하나가 랜덤으로 나와요!

### 랜덤 출력 활용 예시

**인사 명령어**
```
!추가 !인사 안녕하세요!||반갑습니다!||어서오세요!||환영합니다!
```

**음식 추천**
```
!추가 !뭐먹지 치킨 어때요?||피자 추천!||햄버거 고고!||한식으로 가시죠!
```

**확률 게임**
```
!추가 !복권 $nick님이 당첨!||$nick님 꽝이에요...
```

---

## 조건부 출력 (삼항 연산자)

특정 조건에 따라 다른 메시지를 보낼 수 있어요.

**삼항 연산자란?**

"만약 ~이면 A, 아니면 B"처럼 조건에 따라 결과가 달라지는 방식이에요.

예를 들어, "비가 오면 우산을 챙기고, 안 오면 안 챙긴다"를
`비가 오나요? → 네(우산 챙김) / 아니오(안 챙김)` 처럼 표현해요.

### 사용 방법

```
#ternary:[조건]?[조건이 맞을 때]:[조건이 틀릴 때]
```

조건은 `A==B` 형태의 문자열 일치 비교만 돼요. `!=` · `>` 같은 다른 기호를 쓰면 조건식이 그대로 채팅에 나가요.

**응답 맨 앞에 와야 해요**

`#ternary:` 는 응답의 **첫 글자부터** 시작해야 동작해요.
`안녕하세요 #ternary:...` 처럼 앞에 다른 글자가 있으면 그냥 글자로 출력돼요.

### 예시 1: 팔로우 확인

```
!추가 !팔체 #ternary:$follow_check==True?$nick님은 팔로우 O:$nick님은 팔로우 X
```

팔로우를 했으면 "팔로우 O", 안 했으면 "팔로우 X"가 출력돼요!

### 예시 2: 출석 중복 방지

```
!추가 !출석 #ternary:$att_check==True?$nick님 $att_add번 출석!:$nick님 오늘은 이미 출석했어요!
```

`$att_check`가 `True`면 출석 가능(아직 안 함) 상태예요. 그래서 출석 처리가 되고, `False`면 이미 출석했기 때문에 안내 메시지가 나와요!

**콜론(:) 사용 주의**

`#ternary:`는 콜론(`:`)을 기준으로 조건, 참일 때 메시지, 거짓일 때 메시지를 구분해요.

**참일 때 메시지 부분에 콜론이 들어가면 문법이 깨져요!**

❌ `#ternary:$follow_check==True?$nick님: 환영합니다!:팔로우 해주세요` (콜론 때문에 오류)

✅ `#ternary:$follow_check==True?$nick님 환영합니다!:팔로우 해주세요` (콜론 제거)

---

## 대시보드에서 세밀하게 설정하기

채팅으로 만든 명령어는 기본값으로 설정돼요.

| 항목 | 기본값 |
|---|---|
| 필요 권한 | **시청자 (누구나)** |
| 전체 쿨타임 | **3초** |
| 유저 쿨타임 | **3초** |
| 명령어 목록에 포함 여부 | 표시함 |

더 세밀하게 조정하려면 **대시보드 → 유저 명령어**에서 설정하세요.

![대시보드 유저 명령어 목록 화면](/static/docs/commands/cmd-01-list.png)

등록된 명령어가 한눈에 보이고, 오른쪽 스위치로 **지우지 않고 잠시 끌 수** 있어요.
`추가` 또는 `수정` 을 누르면 아래 설정 창이 열려요.

![명령어 추가·수정 창의 세부 설정](/static/docs/commands/cmd-02-settings.png)

### 대시보드에서 조정하는 설정

| 설정 | 설명 |
|---|---|
| **필요 권한** | 시청자 / 구독자 / 매니저 / 스트리머 중 선택 |
| **전체 쿨타임** | 모두가 함께 쓰는 쿨타임 (초) |
| **유저 쿨타임** | 한 사람이 다시 쓸 수 있기까지의 시간 |
| **일부 포함시 작동** | 명령어가 채팅 **맨 앞**에 와야 하는 기본 동작과 달리, 채팅 아무 위치에 들어가도 반응. 변수를 쓰는 명령어에는 켜지 마세요(화면에도 같은 경고가 떠요) |
| **치즈 감지시에만 작동** | 특정 금액대의 후원일 때만 반응 (= 후원 금액 조건). 최소·최대를 둘 다 0 으로 두면 조건이 꺼져요 |
| **N번 사용한 이후에 비활성화** | 지정한 횟수만큼 쓰이면 자동으로 꺼짐 |
| **명령어 목록에 포함 여부** | `!명령어` 목록과 시청자 페이지에 보일지 여부 |
| **설명** | 시청자 페이지·대시보드 목록에 보여줄 설명 (채팅 `!명령어` 응답에는 안 나와요) |
| **활성 / 비활성** | 지우지 않고 잠시 꺼두기. 채팅 `!명령어 끄기 <명령어>` 로도 돼요 |

**이렇게 쓰면 좋아요**

- **부분 포함 매칭** — `ㅋㅋ` 로 설정해두면 시청자가 `ㅋㅋㅋㅋ` 라고만 쳐도 반응해요
- **후원 금액 조건** — 특정 금액 후원에만 반응하는 특별 메시지
- **자동 비활성화** — 선착순 이벤트 ("10명까지만!")
- **유저별 쿨타임** — 한 사람이 도배하는 것만 막고 다른 사람은 바로 쓸 수 있게
- **목록에 표시 끄기** — 숨겨진 이스터에그 명령어

**부분 포함 매칭은 신중하게**

너무 짧은 단어(`ㅇ`, `아` 등)로 설정하면 봇이 채팅마다 반응해서 도배가 돼요. **쿨타임을 함께 넉넉히** 잡아주세요.

---

## 변수와 함께 사용하기

[변수](/docs/commands/variables)를 넣으면 더 다양한 기능을 만들 수 있어요.

**예시: 채널 소개**
```
!추가 !채널소개 $channelName님의 방송에 오신 것을 환영합니다! 현재 $viewers명이 시청 중이에요.
```

**예시: 팔로우 기간**
```
!추가 !팔로우 $nick님은 팔로우한 지 $followDate 되셨어요!
```

---

## 자주 겪는 문제

### "이미 존재하는 명령어입니다"

같은 이름의 명령어가 이미 있어요. `!수정` 으로 내용을 변경하거나 다른 이름으로 만들어보세요.

### "수정, 삭제할 수 없는 명령어입니다"

봇 운영자가 잠가둔 명령어예요. **스트리머·매니저는 잠금을 걸거나 풀 수 없어요.**

문구는 어디서 건드렸느냐에 따라 달라요 — 대시보드는 `수정, 삭제할 수 없는 명령어입니다.`,
채팅은 `수정할 수 없는 명령어입니다.` / `삭제할 수 없는 명령어입니다.` 입니다.

`!업타임` 같은 **기본 제공 명령어**를 수정·삭제하려 하면 이 메시지가 아니라 **"존재하지 않는 명령어입니다"** 가 나와요.
`!수정` · `!제거` 는 직접 만든 명령어 목록만 뒤지기 때문에, 기본 제공 명령어는 아예 찾지 못해요.

### "명령어에 공백이 포함되어 있습니다"

대시보드에서 만들 때 나오는 문구예요. 채팅 `!추가` 는 첫 띄어쓰기까지만 명령어 이름으로 잡아서, `!추가 !내 정보 안녕` 은 오류 없이 `!내` 라는 명령어로 등록돼요.

명령어 이름에는 띄어쓰기를 넣을 수 없어요. `!내 정보` ❌ → `!내정보` ✅

### 명령어를 만들었는데 반응이 없어요

| 확인할 것 | 해결 |
|---|---|
| 쿨타임 중인가요? | 기본 3초예요. 잠시 기다렸다 다시 쳐보세요 |
| 권한이 맞나요? | 대시보드에서 필요 권한을 확인해보세요 |
| 비활성 상태인가요? | 대시보드에서 활성 스위치를 확인해보세요 |
| 자동 비활성화에 걸렸나요? | 사용 횟수 제한이 걸려 있을 수 있어요 |

---

## 다음 단계

커스텀 명령어에서 사용할 수 있는 변수들을 알아보세요!

[변수 →](/docs/commands/variables) · [기본 명령어 →](/docs/commands/basic)

---

# 시스템 설정

출처: https://chzzk-bot.ddutto.com/docs/commands/system
설명: 뚜봇 !설정 명령어 전체 안내. 입장안내, 채팅 제한, 룰렛 후원 감지, 매크로 출력 방식, 광고 필터 등을 다룹니다.

뚜봇의 동작 방식을 내 방송에 맞게 조정할 수 있어요. 대부분의 설정은 `!설정` 명령어로 시작해요.

**명령어 사용 권한**

이 페이지의 모든 설정 명령어는 **매니저** 권한이 필요해요.

---

## 입장 안내 메시지

**방송이 시작될 때** 봇이 붙으면서 보내는 인사 메시지를 켜고 끌 수 있어요.
(방송 시작 후 60초 안에 붙었을 때만 나가요. 방송 중간에 재접속하거나 방송이 꺼져 있으면 나가지 않아요)

- !설정 입장안내 [켜기/끄기] — 봇 입장 시 안내 메시지 표시 여부를 설정해요. / 예: !설정 입장안내 끄기 / 봇 응답: 입장 안내가 꺼졌습니다. / 쿨타임 1s

**기본값**: 켜짐

---

## 명령어 활성화/비활성화

봇 **기본 명령어**를 잠시 끄거나 다시 켤 수 있어요.
`!설정 명령어` 를 값 없이 입력하면 끌 수 있는 명령어 목록이 그대로 나와요.
(`!명령어` 목록과는 달라요 — 이미 꺼둔 명령어는 `!명령어` 에서 빠지기 때문에 거기서는 다시 켤 대상을 찾을 수 없어요.)
직접 만든 커스텀 명령어는 `!명령어 끄기 <명령어>` 로 따로 꺼요.

- !설정 명령어 [활성화/비활성화] [명령어] — 특정 명령어의 활성화 여부를 설정해요. / 예: !설정 명령어 비활성화 !업타임 / 봇 응답: '!업타임' 명령어가 비활성화되었습니다. / 쿨타임 1s

**팁**

시청자들이 너무 많이 쓰는 명령어가 있다면, 일시적으로 비활성화할 수 있어요!

---

## 다시보기 알림

방송 시간이 33시간 50분에 도달하면 알려줘요.
(치지직에서 **루키·프로** 등급은 34시간을 넘으면 다시보기가 사라져요. **파트너** 등급은 해당하지 않아요.)

치지직 **인증 배지가 있는 채널에는 발송되지 않아요.**

- !설정 다시보기알림 [켜기/끄기] — 다시보기가 남지 않는 시간이 되기 전에, 미리 알려줄지 여부를 설정해요. / 예: !설정 다시보기알림 켜기 / 봇 응답: 다시보기 알림이 켜졌습니다. 방송을 시작한지 33시간 50분이 지났을 때 알려드릴게요. / 쿨타임 1s

**기본값**: 꺼짐 — 알림을 받으려면 `!설정 다시보기알림 켜기` 를 먼저 실행해야 해요.

---

## 채팅 자동 열기/닫기

방송이 시작될 때 채팅을 자동으로 열고, 종료될 때 닫을 수 있어요.
다시 여는 건 봇이 **방송 시작 후 2분 안에** 붙었을 때만 실행돼요. 방송 중간에 봇이 재접속하면 저장해 둔 모드로 남습니다.

- !설정 채팅설정 자동열기 [켜기/끄기] — 방송 시작/종료 시 채팅 자동 열기/닫기를 설정해요. / 예: !설정 채팅설정 자동열기 켜기 / 봇 응답: 채팅 제한이 활성화되었어요. 이제 방종시 자동으로 채팅이 닫히고, 방송 시작시 자동으로 열려요. / 쿨타임 1s

**기본값**: 꺼짐

**봇 권한 필요**

켜려면 **봇**에 **채널 관리자** 권한이 있어야 해요. 없으면 설정이 저장되지 않고
`저에게 '채널 관리자'를 추가해주세요 :>` 가 나가요. (다른 항목과 달리 채팅 운영자로는 부족해요)

대시보드에서 **채널 주인이 치지직 계정을 연동**해 두었다면 이 권한 없이도 켜져요.
[권한 부여 방법 →](/docs/getting-started/permissions)

---

## 이모티콘 개수 제한

한 번에 보낼 수 있는 이모티콘 개수를 제한할 수 있어요.
설정한 개수에 **도달하면** 임시 차단이 적용돼요. 5로 두면 5개째부터 걸리니, 실제 허용치는 4개예요.
매니저 이상(스트리머 본인 포함)은 대상이 아니라, 직접 시험해 보면 걸리지 않아요. 구독자는 대상이에요.

- !설정 채팅설정 이모티콘제한 [개수] — 한 메시지에 들어간 이모티콘 총 개수를 제한해요. 0으로 설정하면 비활성화돼요. / 예: !설정 채팅설정 이모티콘제한 5 / 봇 응답: 이모티콘 제한이 5개로 설정되었습니다. / 쿨타임 1s / (연속으로 붙어 있지 않아도 돼요. 글자 사이에 흩어 놓아도 전부 합산돼요. 치지직 이모티콘뿐 아니라 😀 같은 일반 이모지도 함께 계산해요.)

**기본값**: 비활성화 (0)

**봇 권한 필요**

이모티콘 제한으로 인한 **임시 차단**이 작동하려면 **봇**에 **채팅 운영자** 권한이 부여되어 있어야 해요.
대시보드에서 **채널 주인이 치지직 계정을 연동**해 두었다면 이 권한 없이도 작동해요.
[권한 부여 방법 →](/docs/getting-started/permissions)

---

## 타 스트리머 이모티콘 제한

다른 스트리머의 이모티콘을 쓰면 그 메시지를 삭제(블라인드)할 수 있어요.

- !설정 채팅설정 타스이모티콘제한 [켜기/끄기] — 타 스트리머 이모티콘 사용 시 해당 메시지를 삭제해요. / 예: !설정 채팅설정 타스이모티콘제한 켜기 / 봇 응답: 타스 이모티콘 제한이 활성화되었어요. 이제 타 스트리머의 이모티콘을 사용할 시, 메세지가 삭제됩니다. / 쿨타임 1s

**기본값**: 꺼짐

**봇 권한 필요**

이 설정을 **켜려면** 봇에 **채팅 운영자** 권한이 있어야 해요. 권한이 없으면 켜기 명령이 거부되고
설정 자체가 저장되지 않아요 (`저에게 '채팅 운영자'를 추가해주세요 :>`).
대시보드에서 **채널 주인이 치지직 계정을 연동**해 두었다면 이 권한 없이도 켜져요.
[권한 부여 방법 →](/docs/getting-started/permissions)

---

## 룰렛 관련 설정

- !설정 룰렛 후원감지 [채팅/모두] — 룰렛이 어떤 후원에 반응할지 정해요. / 예: !설정 룰렛 후원감지 모두 / 봇 응답: 지금부터, 모든 후원으로 룰렛이 돌아갑니다. / 쿨타임 1s

| 값 | 동작 |
|---|---|
| **채팅** (기본값) | **채팅창에 올라온 후원**만 인식해요 |
| **모두** | 모든 후원을 인식해요 |

**룰렛이 안 돌아간다면 이걸 먼저 확인해보세요**

기본값이 **채팅**이라, 채팅창에 표시되지 않는 후원은 룰렛을 돌리지 않아요.

`!설정 룰렛 후원감지 모두` 로 바꾸면 더 폭넓게 인식해요. 다만 정확한 인식을 위해서는 뚜봇에게 **채널 관리자 권한**을 주시는 게 가장 확실해요.

- !설정 룰렛 공개 [켜기/끄기] — 시청자 페이지에서 룰렛 구성을 볼 수 있게 할지 정해요. / 예: !설정 룰렛 공개 켜기 / 쿨타임 1s

- !설정 룰렛 타이머자동일시정지 [켜기/끄기] — 룰렛 결과로 **새로 만들어지는** 타이머를 일시정지 상태로 생성해요. / 예: !설정 룰렛 타이머자동일시정지 켜기 / 쿨타임 1s / (기본값 꺼짐. 룰렛이 도는 동안 멈추는 게 아니에요. 이미 있는 타이머에 시간을 더하거나 뺄 때는 영향이 없고, 룰렛이 끝나도 자동으로 재개되지 않아요. 시작하려면 `!타이머 재개 <이름>` 을 직접 입력해야 해요.)

- !설정 룰렛 테스트 [횟수] [룰렛 이름] — 실제 후원 없이 룰렛을 원하는 횟수만큼 돌려봐요. / 예: !설정 룰렛 테스트 5 벌칙룰렛 / 쿨타임 1s / (횟수는 1~3000 회만 돼요. 벗어난 값을 넣으면 '룰렛 테스트를 보냈습니다.' 라고만 답하고 실제로는 돌지 않아요.)

[룰렛 자세히 보기 →](/docs/features/roulette)

---

## 매크로 출력 방식

- !설정 매크로 출력순서 [순서대로/랜덤] — 여러 매크로 메시지를 어떤 순서로 보낼지 정해요. / 예: !설정 매크로 출력순서 랜덤 / 쿨타임 1s

- !설정 매크로 출력방식 [항상/채팅감지] — 매크로를 언제 보낼지 정해요. / 예: !설정 매크로 출력방식 채팅감지 / 쿨타임 1s

| 값 | 동작 |
|---|---|
| **항상** | 시간이 되면 무조건 보내요 |
| **채팅감지** | 채팅이 있을 때만 보내요 |

**팁**

시청자가 없을 때 봇 혼자 떠드는 게 어색하다면 **채팅감지**로 바꿔보세요.

---

## 광고 필터

일반 시청자 채팅에서 광고가 감지되면 자동으로 제재해요. 후원 메시지만이 아니라 **일반 채팅 전체**가 대상이에요.
**구독자·매니저·스트리머는 광고 필터 대상이 아니에요.**

감지되면 문구만 잘라내는 게 아니라 **메시지 가리기 · 임시 제한 · 계정 벤** 중 하나가 실행돼요.
어느 쪽이 될지는 걸린 광고 종류에 따라 정해져요.

- !설정 광고필터 [기본/엄격] — 다른 방송에서 광고를 친 이력이 있는 계정을 어떻게 다룰지 정해요. / 예: !설정 광고필터 엄격 / 쿨타임 1s

기본/엄격은 **이번 메시지를 얼마나 세게 자르냐가 아니에요.** 이미 다른 방송에서 광고 계정으로
기록된 사람이 내 채널에 채팅했을 때의 처리를 바꿔요.

| 모드 | 광고 이력 계정이 채팅하면 |
|---|---|
| **기본** | 내부에 '광고 의심' 으로 기록만 남아요. 시청자에게는 아무 일도 없어요 단 **공유벤으로 분류된 악질 광고 계정은 모드와 상관없이 즉시 벤**돼요 |
| **엄격** | 보낸 메시지가 **광고가 아니어도** 그 계정을 즉시 벤해요 |

**엄격 모드는 사람을 벤해요**

메시지가 잘리는 정도가 아니에요. 타 방송에서 광고를 친 적 있는 계정이 내 방송에서
평범한 인사를 해도 **영구 벤**돼요.

억울한 제재가 생길 수 있으니, 광고 도배가 실제로 심한 게 아니라면 기본 모드를 권해요.

---

## 시청자 참여 · 가위바위보

- !설정 시참 자동초기화 [켜기/끄기] — 추첨을 한 직후 참여자 목록을 자동으로 비워요. / 예: !설정 시참 자동초기화 켜기 / 봇 응답: 시참 자동 초기화가 켜졌습니다. / 쿨타임 1s / (기본값은 꺼짐이에요. 꺼져 있으면 추첨을 해도 목록이 그대로 남아, 같은 사람이 또 뽑힐 수 있어요.)

[시청자 참여 자세히 보기 →](/docs/features/viewer-participation)

- !설정 가위바위보 하루판수 [숫자] — 시청자 한 명이 하루에 가위바위보를 할 수 있는 횟수를 정해요. 최대 100판까지 지정할 수 있어요. / 예: !설정 가위바위보 하루판수 3 / 쿨타임 1s

---

## 치지직 경고 알림 받기

치지직의 경고 알림을 채팅창에서 바로 확인할 수 있어요.

- !설정 경고알림 [켜기/끄기] — 치지직에서 전송되는 경고 알림을 채팅창으로 받을지 설정해요. / 예: !설정 경고알림 켜기 / 쿨타임 1s

**팁**

방송 중에는 알림 팝업을 놓치기 쉬워요. 켜두면 채팅창에서 바로 확인할 수 있어요.

---

## 타이머 종료 알림 횟수

타이머가 끝났을 때 몇 번 알려줄지 설정할 수 있어요.

- !설정 타이머 종료알림횟수 [횟수] — 타이머 종료 시 알림을 보낼 횟수를 정해요. / 예: !설정 타이머 종료알림횟수 1 / 봇 응답: 타이머 종료 알림을 1회로 설정합니다. / 쿨타임 1s / (기본값 3회, 1~5회까지 설정할 수 있어요.)

**참고**

값을 빼고 `!설정 타이머 종료알림횟수` 만 치면 현재 설정된 횟수를 알려줘요.
범위를 벗어나면 `0회 이상, 5회 이하로 설정해주세요.` 가 나와요.
(문구는 '0회 이상' 이라고 하지만 **0은 거부돼요.** 1~5 만 돼요)

[타이머 자세히 보기 →](/docs/features/timer-counter)

---

## 마커 공개

- !설정 마커공개 [켜기/끄기] — 시청자 페이지에서 마커를 볼 수 있도록 설정해요. / 예: !설정 마커공개 켜기 / 쿨타임 1s

---

## 그 외

| 명령어 | 문서 |
|---|---|
| `!설정 신청곡 <유저제한/길이제한/전체갯수제한/중복제한>` | [신청곡](/docs/features/song-request) |
| `!설정 게임연동 <게임명> <닉네임>` | [게임 전적·티어](/docs/features/game-tier) |

**사용법이 기억나지 않을 때**

`!설정` 만 입력하면 사용할 수 있는 하위 항목 목록이 나와요. 각 항목도 값을 빼고 입력하면 사용법을 알려줘요.
현재 설정값까지 같이 보여주는 건 입장안내 · 다시보기알림 · 시참 자동초기화 · 타이머 종료알림횟수 · 신청곡 4종 · 금칙어 모드 · 게임연동이에요.

예: `!설정 룰렛` → 사용 가능한 룰렛 설정 목록 표시

## `!설정` 하위 항목 전체

| 항목 | 하는 일 |
|---|---|
| `입장안내` | 봇 입장 시 인사 메시지 |
| `명령어` | 특정 명령어 켜고 끄기 |
| `다시보기알림` | 33시간 50분 경과 알림 |
| `채팅설정` | 이모티콘 제한 · 타 스트리머 이모티콘 · 자동 열기 |
| `룰렛` | 후원감지 · 공개 · 타이머자동일시정지 · 테스트 |
| `매크로` | 출력순서 · 출력방식 |
| `타이머` | 종료 알림 횟수 |
| `시참` | 추첨 후 자동 초기화 |
| `가위바위보` | 하루 판수 |
| `신청곡` | 유저제한 · 길이제한 · 전체갯수제한 · 중복제한 |
| `게임연동` | 게임별 계정 연결 |
| `금칙어` | 감지 모드 (일반/엄격) |
| `광고필터` | 광고 이력 계정 처리 방식 (기본/엄격) |
| `경고알림` | 치지직 경고 알림 채팅 수신 |
| `마커공개` | 시청자 페이지 마커 노출 |

---

## 다음 단계

시스템 설정을 마쳤다면, 방송 설정 명령어를 알아보세요!

[방송 설정 →](/docs/commands/broadcast)

---

# 변수

출처: https://chzzk-bot.ddutto.com/docs/commands/variables
설명: 뚜봇 명령어에서 사용할 수 있는 변수를 안내해요.

변수를 사용하면 명령어 응답에 동적인 정보를 넣을 수 있어요!
변수는 `$변수명` 형태로 사용하고, 실행 시 실제 값으로 바뀌어요.

**권한 용어 안내**

일부 변수는 **봇**에게 특정 권한이 부여되어 있어야 작동해요.

- **채팅 운영자**: 임시 차단, 채팅 횟수 조회 등 채팅 관리 기능
- **채널 관리자**: 팔로워 정보, 구독자 정보 조회 등 채널 관리 기능

권한 부여 방법은 [권한 부여 방법](/docs/getting-started/permissions)을 참고해보세요.

---

## 대시보드에서 찾아보기

변수 목록은 이 문서뿐만 아니라 대시보드 **시스템 변수** 페이지에서도 볼 수 있어요.

![대시보드 시스템 변수 목록 — 변수명과 설명](/static/docs/variables/var-01-list.png)

오른쪽 **'예시 / 설명 보기'** 를 누르면 그 변수의 상세 설명과 **실제 채팅창 예시**가 나타나요.
옵션이 붙는 변수(`$countdown:` 같은)는 여기서 확인하는 게 빨라요.

![$countdown: 변수의 예시 창 — 설명과 채팅 예시](/static/docs/variables/var-02-example.png)

**`:` 이 들어간 변수는 띄어쓰기에 주의**

`$countdown:0000-03-04` 처럼 **`:` 이 들어간 변수는 값 뒤에 띄어쓰기가 한 칸 필요해요.**
붙여 쓰면 다음 띄어쓰기 전까지가 통째로 값으로 들어가서 `서식 잘못됨` 이 출력돼요.

---

## 사용자 정보 변수

### 닉네임

- $nick / $name — 명령어를 사용한 사람의 닉네임을 출력해요. / 예: !추가 뚜하 $nick님 안녕하세요! / 입력: 마지막남은뚜또: 뚜하 / 출력: 마지막남은뚜또님 안녕하세요!

**참고**

`$nick`과 `$name`은 똑같이 동작해요. 편한 걸로 쓰세요.
익명 사용자(후원 익명처럼)의 경우 `익명`이 출력돼요.

---

### 입력값 인식

- $args — 명령어 뒤에 입력된 텍스트를 출력해요. / 예: !추가 !테스트 내용: $args / 입력: 마지막남은뚜또: !테스트 뚜바또보 / 출력: 내용: 뚜바또보

**시청자가 입력한 변수는 작동하지 않아요**

`$args` 로 들어온 값 안에 `$nick` 같은 변수가 있어도 **치환되지 않고 글자 그대로** 나와요.

**예시**: `!테스트 $nick님 안녕하세요!` → `내용: $nick님 안녕하세요!`

시청자가 채팅으로 변수를 넣어 남의 정보를 뽑아내지 못하게 막아둔 거예요.
`$nick` · `$name` 으로 들어온 값도 마찬가지예요.

---

### 팔로우 여부

- $follow_check — 팔로우 여부를 출력해요. 팔로우했으면 True, 안 했으면 False / 예: !추가 !팔체 팔로우 여부: $follow_check / 입력: 마지막남은뚜또: !팔체 / 출력: 팔로우 여부: True

---

### 팔로우 기간

- $followDate — 팔로우한 기간을 자세히 출력해요. (예: 8개월 14일 2초) / 예: !추가 !팔로우 $nick 연구원은 $followDate 동안 연구실 청소중이야~! / 입력: 마지막남은뚜또: !팔로우 / 출력: 마지막남은뚜또 연구원은 8개월 14일 2초 동안 연구실 청소중이야~!

**에러 응답**

팔로우하지 않은 사용자는 `[팔로우하지 않음]`이 출력돼요.

---

### 팔로우 일수

- $followDay — 팔로우한 일수만 출력해요. (예: 262일) / 예: !추가 !몇일 팔로우한 지 $followDay! / 입력: 마지막남은뚜또: !몇일 / 출력: 팔로우한 지 262일!

**에러 응답**

팔로우하지 않은 사용자는 `[팔로우하지 않음]`이 출력돼요.

---

### 팔로우 순서

- $followOrder — 몇 번째 팔로워인지 출력해요. / 예: !추가 !순서 $nick님은 $followOrder번째로 팔로우해주셨어요! / 입력: 마지막남은뚜또: !순서 / 출력: 마지막남은뚜또님은 430번째로 팔로우해주셨어요!

**봇 권한 필요**

**봇**에 **채널 관리자** 권한 또는 **대시보드 연동**이 필요해요.
권한이 없으면 `[오류, 봇 권한 필요]`가 출력돼요.

---

### 구독 순서

- $subscriberOrder — 몇 번째 구독자인지 출력해요. / 예: !추가 !구독순서 $nick님은 $subscriberOrder번째로 구독해주셨어요! / 입력: 채링: !구독순서 / 출력: 채링님은 42번째로 구독해주셨어요!

**봇 권한 필요**

**봇**에 **채널 관리자** 권한 또는 **대시보드 연동**이 필요해요.
권한이 없으면 `[오류, 봇 권한 필요]`가 출력돼요.
구독자가 아니거나 정보를 찾을 수 없으면 `[파악 불가]`가 출력돼요.

---

### 구독 날짜

- $subscriberDate — 구독한 날짜를 출력해요. / 예: !추가 !구독날짜 $nick님의 구독 날짜: $subscriberDate / 입력: 채링: !구독날짜 / 출력: 채링님의 구독 날짜: 2024-03-06 20:26:11

**봇 권한 필요**

**봇**에 **채널 관리자** 권한이 필요해요.
권한이 없으면 `[오류, 봇 권한 필요]`가 출력돼요.
구독자가 아니거나 정보를 찾을 수 없으면 `[파악 불가]`가 출력돼요.

---

### 채팅 횟수

- $chatMessageCount — 이 채널에서의 총 채팅 횟수를 출력해요. / 예: !추가 !채팅횟수 $nick님의 채팅 횟수는 $chatMessageCount회에요! / 입력: 마지막남은뚜또: !채팅횟수 / 출력: 마지막남은뚜또님의 채팅 횟수는 1004회에요!

**참고**

치지직이 집계한 값을 우선 써요. 권한이 없거나 값이 9999 로 막혔을 때만 뚜봇이 직접 센 채팅 수와 비교해 큰 쪽을 보여줘요.
중간에 봇을 추가한 경우, 횟수가 9999에서 멈출 수 있어요.

**권한이 없으면 값이 달라져요**

봇에 **채팅 운영자** 권한이 있으면 치지직이 집계한 값이 나와요.
권한이 없어도 동작은 하지만, **뚜봇이 직접 감지한 채팅 수**만 세어 보여줘요.

(같은 권한을 쓰는 `$temporaryRestrictCount` · `$restrictCount` 는 폴백이 없어
권한이 없으면 `봇에게 권한이 없습니다.` 가 나와요)

---

### 임시 차단 횟수

- $temporaryRestrictCount — 사용자가 받은 임시 차단 횟수를 출력해요. / 예: !추가 !임차 $nick님은 $temporaryRestrictCount번의 임시 차단을 받았어요! / 입력: 마지막남은뚜또: !임차 / 출력: 마지막남은뚜또님은 1번의 임시 차단을 받았어요!

**봇 권한 필요**

**봇**에 **채팅 운영자** 권한이 필요해요.

---

### 활동 제한 횟수

- $restrictCount — 사용자가 받은 활동 제한 횟수를 출력해요. / 예: !추가 !활제 $nick님은 $restrictCount번의 활동 제한을 받았어요.. / 입력: 채링: !활제 / 출력: 채링님은 1번의 활동 제한을 받았어요..

**봇 권한 필요**

**봇**에 **채팅 운영자** 권한이 필요해요.

---

## 방송 정보 변수

### 스트리머 닉네임

- $channelName — 해당 채널의 스트리머 닉네임을 출력해요. / 예: !추가 뚜봇하이 🖐️ 스트리머 $channelName님! 반가워요 :> / 입력: 마지막남은뚜또: 뚜봇하이 / 출력: 🖐️ 스트리머 마지막남은뚜또님! 반가워요 :>

---

### 스트리머 UID

- $channelUID — 해당 채널의 스트리머 UID를 출력해요. / 예: !추가 !uid 스트리머 UID: $channelUID / 입력: 마지막남은뚜또: !uid / 출력: 스트리머 UID: 3c9f1a2b8d4e5f6071829a3b4c5d6e7f

---

### 스트리머 아바타 URL

- $channelAvatarUrl — 해당 채널의 스트리머 프로필 이미지 URL을 출력해요. / 예: !추가 !아바타 프로필: $channelAvatarUrl / 입력: 마지막남은뚜또: !아바타 / 출력: 프로필: https://nng-phinf.pstatic.net/...

---

### 채널 프리뷰 URL

- $channelPreviewUrl — 현재 방송의 미리보기 이미지 URL을 출력해요. / 예: !추가 !미리보기 썸네일: $channelPreviewUrl / 입력: 마지막남은뚜또: !미리보기 / 출력: 썸네일: https://livecloud-thumb.akamaized.net/...

---

### 방송 여부

- $isLive — 현재 방송 중인지 여부를 출력해요. (True/False) / 예: !추가 !방송중 방송 상태: $isLive / 입력: 마지막남은뚜또: !방송중 / 출력: 방송 상태: True

---

### 방송 제목

- $title — 현재 방송 제목을 출력해요. / 예: !추가 !방제 🎥 방송 제목: $title / 입력: 마지막남은뚜또: !방제 / 출력: 🎥 방송 제목: 반갑습니다

---

### 방송 카테고리

- $game / $category — 현재 방송 카테고리(게임)를 출력해요. / 예: !추가 !게임 🎮 플레이중인 게임: $game / 입력: 마지막남은뚜또: !게임 / 출력: 🎮 플레이중인 게임: 마인크래프트

**참고**

일부 카테고리는 영어로 표시될 수 있어요. (예: talk)

---

### 시청자 수

- $viewers — 현재 시청자 수를 출력해요. / 예: !추가 !시청자수 시청자: $viewers명 / 입력: 마지막남은뚜또: !시청자수 / 출력: 시청자: 39명

---

### 누적 시청자 수

- $views — 이번 방송의 누적 시청자 수를 출력해요. / 예: !추가 !뷰 뷰어: $views명 / 입력: 마지막남은뚜또: !뷰 / 출력: 뷰어: 390명

---

### 팔로워 수

- $followCount — 채널의 총 팔로워 수를 출력해요. / 예: !추가 !팔로워 팔로워: $followCount명 / 입력: 마지막남은뚜또: !팔로워 / 출력: 팔로워: 633명

---

### 구독자 수

- $subscriberCount — 채널의 총 구독자 수를 출력해요. / 예: !추가 !구독자 구독자: $subscriberCount명 / 입력: 마지막남은뚜또: !구독자 / 출력: 구독자: 500명

**봇 권한 필요**

**봇**에 **채널 관리자** 권한 또는 **대시보드 연동**이 필요해요.

---

### 업타임

- $uptime — 방송 진행 시간을 출력해요. / 예: !추가 !업타임 $uptime / 입력: 마지막남은뚜또: !업타임 / 출력: 2시간 1분 3초

**참고**

방송 중이 아닐 때는 `[방송중이 아님]`이 출력돼요.

---

## 시간 관련 변수

### 현재 시간

- $time — 한국 시간을 출력해요. / 예: !추가 !지금시간 $time / 입력: 마지막남은뚜또: !지금시간 / 출력: 2024-11-20 01:29:23

---

### 타임스탬프

- $timestamp — 현재 시간을 Unix 타임스탬프로 출력해요. / 예: !추가 !타임스탬프 현재 타임스탬프: $timestamp / 입력: 마지막남은뚜또: !타임스탬프 / 출력: 현재 타임스탬프: 1732034963

---

### 오늘 날짜

- $today — 오늘 날짜를 출력해요. / 예: !추가 !오늘 오늘은 $today입니다. / 입력: 마지막남은뚜또: !오늘 / 출력: 오늘은 2024-11-20입니다.

---

### 카운트다운

- $countdown:날짜 — 특정 날짜까지 남은 기간을 출력해요. / 예: !추가 !생일 생일까지 $countdown:0000-03-04 / 입력: 마지막남은뚜또: !생일 / 출력: 생일까지 3개월 13일 남음.

**날짜 형식:**
- `YYYY-MM-DD` (예: 2025-12-25)
- `YYYY-MM-DD_HH:MM:SS` (예: 2025-12-25_00:00:00)
- 연도를 `0000`으로 하면 매년 반복

**옵션:**
변수에 `|옵션`을 붙일 수 있어요.

| 옵션 | 설명 |
|------|------|
| `with_time` | 시간 단위까지 표시 (시, 분, 초) |
| `hide` | "남음/지남" 문구 숨김 |

**옵션 사용 예시:**
```
!추가 !생일 생일까지 $countdown:0000-03-04|hide,with_time
```
→ 결과: `생일까지 3개월 13일 23시간 29분 1초`

---

### 카운트다운 (일수만)

- $countdownOnlyDay:날짜 — 특정 날짜까지 남은 일수만 출력해요. / 예: !추가 !생일 생일까지 $countdownOnlyDay:0000-03-04 남음. / 입력: 마지막남은뚜또: !생일 / 출력: 생일까지 104일 남음.

**주의**

`:` 이 들어간 변수는 **값 뒤에 띄어쓰기 한 개가 필요해요.**

✅ `$countdown:0000-03-04 남은 시간` (띄어쓰기 있음)
❌ `$countdown:0000-03-04남은 시간` (띄어쓰기 없음)

---

## 카운트 변수

### 공용 변수

- $var — 이 명령어가 채널에서 사용된 총 횟수를 출력해요. 누구든 사용하면 올라가요! / 예: !추가 ? 갈고리 $var개 수집! / 입력: 마지막남은뚜또: ? / 출력: 갈고리 4개 수집!

**다른 명령어와 변수 공유하기:**

`$var:변수명` 형태로 다른 명령어의 카운트를 공유할 수 있어요!

```
!추가 ?? 갈고리 $var:? 개 수집!
```

이렇게 하면 `?` 명령어와 `??` 명령어가 같은 카운트를 공유해요.

---

### 개인 변수

- $uservar — 이 사용자가 이 명령어를 사용한 횟수를 출력해요. 사람마다 따로 카운트돼요! / 예: !추가 바보 $nick님이 $uservar번이나 바보라고 했어..! / 입력: 마지막남은뚜또: 바보 / 출력: 마지막남은뚜또님이 3번이나 바보라고 했어..!

**다른 명령어와 변수 공유하기:**

`$uservar:변수명` 형태로 다른 명령어와 개인 카운트를 공유할 수 있어요!

```
!추가 뚜바뚜보 $nick님이 $uservar:바보 번이나 바보라고 했어..!
```

---

### 임시 공용 변수

- $tempvar — $var와 동일하지만, 봇이 재입장하면 초기화돼요. / 예: !추가 !오늘데스 오늘 데스: $tempvar회 / 입력: 마지막남은뚜또: !오늘데스 / 출력: 오늘 데스: 5회

- $tempvar:변수명 — 다른 명령어와 임시 카운트를 공유해요. / 예: !추가 !임시카운트 오늘 카운트: $tempvar:today / 입력: 마지막남은뚜또: !임시카운트 / 출력: 오늘 카운트: 5

**참고**

방송마다 초기화되는 하루 카운트가 필요할 때 유용해요.

---

### 임시 개인 변수

- $tempuservar — $uservar와 동일하지만, 봇이 재입장하면 초기화돼요. / 예: !추가 !오늘참여 $nick님은 오늘 $tempuservar번 참여했어요 / 입력: 마지막남은뚜또: !오늘참여 / 출력: 마지막남은뚜또님은 오늘 3번 참여했어요

- $tempuservar:변수명 — 다른 명령어와 임시 개인 카운트를 공유해요. / 예: !추가 !오늘참여2 $nick님의 오늘 참여 횟수: $tempuservar:참여 / 입력: 마지막남은뚜또: !오늘참여2 / 출력: 마지막남은뚜또님의 오늘 참여 횟수: 3

**콜론을 붙이고 안 붙이고의 차이**

- **`$tempvar`** — 그 명령어 **자기 것만** 세요
- **`$tempvar:이름`** — 같은 `이름` 을 쓰는 **여러 명령어가 함께** 셉니다

`$var` · `$uservar` 도 똑같은 규칙이에요.

---

## 메모 변수

- $memo — 명령어에 메모를 저장하고 출력해요. / 예: !추가 !멤버 멤버: $memo / 입력: 마지막남은뚜또: !멤버 / 출력: 멤버: 마지막남은뚜또, 마지막남은뚜또, 후로기, 채링

**사용 방법:**
1. 일반 시청자가 `!멤버`를 입력하면 저장된 내용이 출력돼요.
2. **매니저 이상**이 `!멤버 새로운 내용`을 입력하면 내용이 저장돼요.
3. `!멤버 삭제`(또는 `!멤버 제거`)를 입력하면 내용이 지워져요.

**참고**

`!멤버 <내용>` 처럼 명령어 뒤에 내용을 붙여 고치는 건 매니저 이상만 할 수 있어요.
(`제거` 와 `삭제` 만 예약어예요. 그 밖의 말은 전부 메모 내용으로 저장돼요.)
저장된 내용이 없으면 `[내용 없음]`이 출력돼요.

**메모는 명령어마다 따로 저장돼요**

`!멤버` 에 저장한 메모와 `!공지` 에 저장한 메모는 **서로 다른 메모**예요.
명령어 하나당 메모 하나라고 생각하시면 돼요.

---

### 개인 메모

- $userMemo — 사람마다 다르게 저장되는 메모예요. / 예: !추가 !내메모 $nick님의 메모: $userMemo / 입력: 마지막남은뚜또: !내메모 오늘 목표는 다이아 / 출력: 마지막남은뚜또님의 메모: 오늘 목표는 다이아

**팁**

시청자마다 자기만의 메모를 남길 수 있어요. 같은 명령어를 쳐도 사람마다 다른 내용이 나와요.

---

### 임시 메모 (봇 재입장 시 초기화)

- $tempMemo — $memo와 같지만, 봇이 재입장하면 지워져요. / 예: !추가 !오늘공지 오늘 공지: $tempMemo / 입력: 마지막남은뚜또: !오늘공지 6시에 합방! / 출력: 오늘 공지: 6시에 합방!

- $tempUserMemo — $userMemo와 같지만, 봇이 재입장하면 지워져요. / 예: !추가 !오늘메모 $nick님의 오늘 메모: $tempUserMemo / 입력: 마지막남은뚜또: !오늘메모 3판만 하기 / 출력: 마지막남은뚜또님의 오늘 메모: 3판만 하기

**참고**

그날 방송에서만 쓰는 공지·목표를 적어둘 때 좋아요. 다음 방송이면 자동으로 지워져요.

---

### 조회 전용 메모

메모를 **읽기만** 하고 싶을 때 써요. 매니저가 뒤에 내용을 붙여도 저장되지 않아요.

| 변수 | 대응하는 저장용 변수 |
|---|---|
| `$viewMemo` | `$memo` |
| `$viewUserMemo` | `$userMemo` |
| `$viewTempMemo` | `$tempMemo` |
| `$viewTempUserMemo` | `$tempUserMemo` |

**메모는 명령어마다 따로 저장돼요**

`$viewMemo` 는 `$memo` 와 **같은 저장소**를 보지만, 저장 위치가 명령어 이름으로 나뉘어요.
`!공지` 의 메모와 `!공지확인` 의 메모는 서로 다른 칸이에요.

그래서 아래처럼 쓰면 `!공지확인` 은 **자기 메모(비어 있음)** 만 보여줘요.

```
!추가 !공지 공지사항: $memo
!추가 !공지확인 공지사항: $viewMemo   ← !공지 의 메모가 안 나와요
```

`$viewMemo` 는 **같은 명령어 안에서** 덮어쓰기를 막고 싶을 때 써요.
다른 명령어로 메모를 나눠 보는 건 불가능해요.

---

### 조용한 메모 저장

- $memo: — 뒤에 붙인 값으로 메모를 바꿔요. 아무것도 출력하지 않아요. / 예: !추가 !공지설정 $memo:8시시작 / 입력: 마지막남은뚜또: !공지설정 / 출력: (아무것도 출력되지 않음) / (값에 띄어쓰기를 넣을 수 없어요. `$memo:오늘은 8시 시작` 이라고 쓰면 `오늘은` 까지만 저장돼요.)

**참고**

`$userMemo:` · `$tempMemo:` · `$tempUserMemo:` 도 비슷하게 동작해요.
`$userMemo:` 와 `$tempUserMemo:` 는 값 뒤에 `|<시청자 UID>` 를 붙여 다른 사람 메모를 지정할 수 있고, UID 형식이 틀리면 `오류: UID가 올바르지 않습니다.` 가 채팅에 나와요.
커스텀 스크립트와 함께 쓰라고 만든 기능이라, 직접 쓸 일은 드물어요.

**메모 변수에는 권한 검사가 없어요**

이 변수들 자체는 권한을 보지 않아요. 시청자 권한 명령어에 `$memo:` 를 넣어 두면
아무나 그 명령어를 쳐서 메모를 덮어쓸 수 있으니, 명령어의 필요 권한을 매니저로 올려두세요.

---

## 마커 변수

### 마커 생성

- $marker — 명령어 입력 시점을 저장해요. 저장된 마커는 대시보드에서 확인할 수 있어요! / 예: !추가 !마커 $marker / 입력: 마지막남은뚜또: !마커 링피트 2시간 당첨 / 출력: 마커가 생성되었습니다.

---

### 조용한 마커

- $silentMarker — 아무것도 출력하지 않고 시점만 저장해요. / 예: !추가 !마커 $silentMarker / 입력: 마지막남은뚜또: !마커 댕청미 / 출력: (아무것도 출력되지 않음)

**팁**

명령어 뒤에 설명을 붙이면 그 설명도 같이 저장돼요.
나중에 편집할 때 편해요.

**방송 중에만 가능**

마커는 방송 중에만 생성할 수 있어요!

- `$marker` — 방송이 꺼져 있으면 `방송중이 아닙니다.` 가 출력돼요.
- `$silentMarker` — **아무 메시지도 없이** 마커 저장만 건너뛰어요.

---

## 주사위 변수

- $rolldice — TRPG 스타일로 주사위를 굴려요. (예: 1d20, 3d6) / 예: !추가 !roll $rolldice / 입력: 마지막남은뚜또: !roll 1d20 / 출력: 마지막남은뚜또님의 결과: 16

**사용 형식:** `{개수}d{면}` (예: 1d20 = 20면체 주사위 1개)

개수는 20, 면수는 500 이 상한이에요. 넘으면 `오류: 20d500 까지만 지원합니다. 그 이내에서 입력해주세요.` 가 나와요.

**참고**

여러 개를 굴리면 결과가 쉼표로 구분되어 나와요.
다만 봇이 공식 API로 보내는 채팅은 95자에서 잘리니, 너무 많이 굴리면 뒤가 날아갈 수 있어요.

---

## 제재 변수

### 임시 제한

- $temporaryRestrictUser — 명령어를 사용한 사람에게 30초 동안 임시 제한을 부여해요. / 예: !추가 !임시제한 $nick님이 스스로 임시제한을 선택하셨어요. $temporaryRestrictUser / 입력: 마지막남은뚜또: !임시제한 / 출력: 마지막남은뚜또님이 스스로 임시제한을 선택하셨어요.

**임시 제한이란?**

일정 시간 채팅이 불가능해지고, 시간이 지나면 자동으로 풀려요.
지속 시간은 뚜봇이 정하는 게 아니라 치지직이 정합니다 — 같은 사람이 반복해서 걸리면 30초 → 60초 → 180초 → 300초 순으로 늘어나요.

**봇 권한 필요**

**봇**에 **채팅 운영자** 권한이 필요해요.

**참고**

검(매니저 배지)을 달고 있는 사용자에게는 작동하지 않아요.

---

### 활동 제한

- $restrictUser — 명령어를 사용한 사람에게 영구 활동 제한을 부여해요. / 예: !추가 !활동제한 $nick님이 스스로 활동제한을 선택하셨어요. $restrictUser / 입력: 채링: !활동제한 / 출력: 채링님이 스스로 활동제한을 선택하셨어요.

**주의: 기본값은 영구 제한**

`$restrictUser`만 사용하면 **영구 활동 제한**이 부여돼요.
기간을 지정하려면 반드시 `$restrictUser:일수` 형태로 사용하세요.

**기한 설정하기:**

`$restrictUser:일수` 형태로 제한 기간을 설정할 수 있어요.

| 변수 | 제한 기간 |
|------|----------|
| `$restrictUser` | **영구** (해제 전까지 계속) |
| `$restrictUser:1` | 1일 |
| `$restrictUser:7` | 7일 |
| `$restrictUser:30` | 30일 |

**사용 가능한 기간:** 1, 3, 7, 15, 30, 90일

`$restrictUser:-1` 은 안 돼요. 숫자 서식 검사에서 걸려 `오류: 제한 기간을 입력해주세요. (예시: $restrictUser:7)` 가 나와요. 영구 제한은 기간 없이 `$restrictUser` 만 쓰세요.

**봇 권한 필요**

**봇**에 **채팅 운영자** 권한이 필요해요.

**참고**

검(매니저 배지)을 달고 있는 사용자에게는 작동하지 않아요.

---

## 기능 변수

기능 변수는 특정 기능을 작동시키는 변수예요.
자세한 내용은 각 기능 페이지를 참고해보세요!

### 출석 체크

- $attendance — 출석 체크 완전판. 출석 처리 + 횟수 + 연속일을 출력해요. / 예: !추가 !출석 $attendance / 입력: 마지막남은뚜또: !출석 / 출력: 마지막남은뚜또님, 이 채널의 42번째 출석입니다! (연속 7일) / (명령어에 $nick이나 $name이 없으면 자동으로 닉네임을 포함해요. $att_combo가 없고 연속 출석이 2일 이상이면 자동으로 연속 일수를 포함해요.)

**$attendance 응답 형식**

- 출석 성공: `닉네임님, 이 채널의 42번째 출석입니다! (연속 7일)`
- 이미 출석: `닉네임님은 이미 출석하셨습니다! (42회 출석)`
- 방송 꺼짐: `방송중이 아닙니다. 방송중에만 출석체크가 가능합니다!`

- $att_add — 출석 횟수를 1 올리고 횟수(숫자만)를 출력해요. / 예: !추가 !출석 $nick님 $att_add번째 출석! / 입력: 마지막남은뚜또: !출석 / 출력: 마지막남은뚜또님 42번째 출석!

**방송 중에만 가능**

방송 중이 아니면 `[방송이 꺼져있습니다.]`가 출력돼요.

- $att_silent — 출석 처리만 하고 아무것도 출력하지 않아요. 다른 텍스트와 조합할 때 유용해요. / 예: !추가 !출석 $att_silent 출석 완료~ / 입력: 마지막남은뚜또: !출석 / 출력: 출석 완료~

- $att_count — 현재 출석 횟수(숫자만)를 출력해요. 출석 처리는 하지 않아요! / 예: !추가 !출석횟수 $nick님의 출석 횟수: $att_count회 / 입력: 마지막남은뚜또: !출석횟수 / 출력: 마지막남은뚜또님의 출석 횟수: 42회

**$att_count는 횟수를 올리지 않아요**

`$att_count`는 횟수를 **조회만** 해요. 출석 처리를 하려면 `$att_add`나 `$attendance`를 사용하세요.

- $att_combo — 연속 출석 수(숫자만)를 출력해요. / 예: !추가 !연속 $nick님 연속 $att_combo일째 출석 중! / 입력: 마지막남은뚜또: !연속 / 출력: 마지막남은뚜또님 연속 7일째 출석 중! / (달력상 연속일이 아니에요. 직전 방송에 출석했거나 최근 이틀 안에 출석했으면 이어져요. 하루 걸러 출석해도 유지돼요.)

- $att_last — 마지막 출석 날짜(YYYY-MM-DD)를 출력해요. / 예: !추가 !마지막출석 마지막 출석: $att_last / 입력: 마지막남은뚜또: !마지막출석 / 출력: 마지막 출석: 2026-01-30

- $att_time — 마지막 출석 날짜와 시간(YYYY-MM-DD HH:MM:SS)을 출력해요. / 예: !추가 !출석시간 마지막 출석: $att_time / 입력: 마지막남은뚜또: !출석시간 / 출력: 마지막 출석: 2026-01-30 14:23:45

- $att_check — 오늘 출석 가능 여부를 출력해요. (True/False) / 예: !추가 !출석가능 오늘 출석 가능: $att_check / 입력: 마지막남은뚜또: !출석가능 / 출력: 오늘 출석 가능: True

- $att_count_month — 이번 달 출석 횟수(숫자만)를 출력해요. / 예: !추가 !이번달 이번 달 출석: $att_count_month 회 / 입력: 마지막남은뚜또: !이번달 / 출력: 이번 달 출석: 15 회 / (변수 뒤에 글자를 바로 붙이지 마세요. `$att_count_month회` 처럼 붙이면 `$att_count` 가 먼저 걸려 값이 깨질 수 있어요.)

- $att_count_month:N — N개월 전 출석 횟수(숫자만)를 출력해요. N 은 1~12 만 돼요. / 예: !추가 !지난달 지난달 출석: $att_count_month:1 회 / 입력: 마지막남은뚜또: !지난달 / 출력: 지난달 출석: 28 회

- $att_count_period:시작~끝 — 특정 기간 동안의 출석 횟수(숫자만)를 출력해요. / 예: !추가 !2024출석 2024년 출석: $att_count_period:2024-01-01~2024-12-31 회 / 입력: 마지막남은뚜또: !2024출석 / 출력: 2024년 출석: 156 회

**출석 변수 에러 응답**

- `$att_count_month:N` 서식이 잘못되면 `[오류, 월 서식이 잘못되었습니다.]`가 출력돼요.
- `$att_count_period` 에 `~` 가 없거나 조각이 2개가 아니면 `[오류, 기간 서식이 잘못되었습니다.]`
- `~` 는 있는데 날짜 형식이 틀리면 `[오류, 시작 날짜 파싱 실패]` 또는 `[오류, 종료 날짜 파싱 실패]`
- 날짜 형식은 반드시 `YYYY-MM-DD`로 입력해주세요!

[출석 체크 자세히 보기 →](/docs/features/attendance)

---

### 신청곡

- $song-requests — 신청곡 기능을 활성화해요. 시청자가 노래를 신청할 수 있어요. / 예: !추가 !노래신청 $song-requests / 입력: 마지막남은뚜또: !노래신청 Ditto / 출력: 신청이 완료되었습니다: Ditto

- $song-requests-nolimit — 노래를 신청해요. 유저제한·길이제한·전체갯수제한·중복제한을 모두 무시해요. / 예: !추가 !구독자신청 $song-requests-nolimit / 입력: 마지막남은뚜또: !구독자신청 Ditto / 출력: 신청이 완료되었습니다: Ditto / (유저제한만 푸는 게 아니에요. 구독자에게 열어줄 때 긴 영상·중복 신청도 막히지 않는다는 점을 감안하세요.)

**구독자·매니저 전용 신청 명령어 만들기**

`!설정 신청곡 유저제한 2` 로 일반 신청은 2곡까지 막아두고,
`$song-requests-nolimit` 으로 만든 명령어는 **대시보드에서 필요 권한을 '구독자'** 로 지정하세요.
구독자도 제한 없이 신청할 수 있는 구조가 돼요. (매니저 이상은 원래부터 신청곡 제한을 받지 않아요.)

- $song-requests-priority:N — 대기열 앞쪽에 끼워 넣어 신청해요. 숫자가 **클수록** 먼저 재생돼요. / 예: !추가 !우선신청 $song-requests-priority:100 / 입력: 마지막남은뚜또: !우선신청 Ditto / 출력: 신청이 완료되었습니다: Ditto / (같은 숫자끼리는 신청한 순서대로 뒤에 붙어요. 등급을 나눈다면 위쪽 등급에 큰 수를 주세요.)

**우선순위 숫자 범위**

`1` 이상 `200000000` 이하만 돼요. 벗어나면 `오류: 올바른 우선순위 숫자를 입력해주세요.` 가 나와요.

- $karaoke-requests — 노래방(가라오케) 신청을 받아요. / 예: !추가 !노래방 $karaoke-requests / 입력: 마지막남은뚜또: !노래방 밤편지 / 출력: 신청이 완료되었습니다: 밤편지

**참고**

신청곡(유튜브 재생)과 **노래방은 대기열이 서로 달라요.** 대시보드에서도 각각 관리해요.

- $song-current — 현재 재생 중인 곡 제목(제목만)을 출력해요. / 예: !추가 !지금곡 🎵 지금 재생 중: $song-current / 입력: 마지막남은뚜또: !지금곡 / 출력: 🎵 지금 재생 중: Ditto / (조회 계열이라 방송 중에만 동작해요. 방송이 꺼져 있으면 `방송중이 아닙니다. 조회는 방송 중에만 가능합니다.` 가 나와요.)

**참고**

재생 중인 곡이 없으면 `재생중인 노래가 없습니다.`가 출력돼요.

- $song-next — 다음에 재생될 곡 제목(제목만)을 출력해요. / 예: !추가 !다음곡 ⏭️ 다음 곡: $song-next / 입력: 마지막남은뚜또: !다음곡 / 출력: ⏭️ 다음 곡: Supernova / (조회 계열이라 방송 중에만 동작해요. 방송이 꺼져 있으면 `방송중이 아닙니다. 조회는 방송 중에만 가능합니다.` 가 나와요.)

**참고**

다음 곡이 없으면 `다음곡이 없습니다.`가 출력돼요.

- $song-count — 재생 중인 곡을 포함한 남은 곡 수를 출력해요. 값에 `개` 가 붙어 나와요. / 예: !추가 !대기열 📋 대기 중인 곡: $song-count / 입력: 마지막남은뚜또: !대기열 / 출력: 📋 대기 중인 곡: 5개 / (숫자만 나오는 게 아니에요. 한 칸 띄어 `$song-count 개` 라고 쓰면 `5개 개` 가 돼요. 조회 계열이라 방송 중에만 동작하고, 방송이 꺼져 있으면 `방송중이 아닙니다. 조회는 방송 중에만 가능합니다.` 가 나와요.)

- $song-link — 현재 재생 중인 곡의 유튜브 링크를 출력해요. / 예: !추가 !곡링크 🔗 $song-link / 입력: 마지막남은뚜또: !곡링크 / 출력: 🔗 https://youtu.be/pSUydWEqKwE / (조회 계열이라 방송 중에만 동작해요. 방송이 꺼져 있으면 `방송중이 아닙니다. 조회는 방송 중에만 가능합니다.` 가 나와요.)

- $song-time — 현재 곡의 길이(MM:SS 또는 HH:MM:SS)를 출력해요. / 예: !추가 !곡길이 곡 길이: $song-time / 입력: 마지막남은뚜또: !곡길이 / 출력: 곡 길이: 03:28 / (조회 계열이라 방송 중에만 동작해요. 방송이 꺼져 있으면 `방송중이 아닙니다. 조회는 방송 중에만 가능합니다.` 가 나와요.)

- $song-total-time — 재생 중인 곡을 포함한 전체 신청곡의 길이 합계(MM:SS 또는 HH:MM:SS)를 출력해요. 재생 중인 곡도 원곡 전체 길이로 더해지니 남은 시간과는 달라요. / 예: !추가 !총길이 전체 대기 시간: $song-total-time / 입력: 마지막남은뚜또: !총길이 / 출력: 전체 대기 시간: 18:45 / (조회 계열이라 방송 중에만 동작해요. 방송이 꺼져 있으면 `방송중이 아닙니다. 조회는 방송 중에만 가능합니다.` 가 나와요.)

- $song-skip — 현재 재생 중인 곡을 스킵해요. / 예: !추가 !스킵 $song-skip / 입력: 마지막남은뚜또: !스킵 / 출력: 'Ditto' 노래를 스킵했습니다.

**권한은 직접 걸어야 해요**

`$song-skip` 변수 자체에는 권한 제한이 **없어요.** 명령어를 시청자 등급으로 만들어두면 아무나 스킵할 수 있어요.
대시보드에서 해당 명령어의 **필요 권한**을 **매니저**로 지정하세요.

방송 중에만 동작하며, 꺼져 있으면 `방송중이 아닙니다. 스킵은 방송 중에만 가능합니다.` 가 나와요.

- $song-remaining-limit-per-user — 내가 추가로 신청할 수 있는 곡 수(숫자만)를 출력해요. / 예: !추가 !내신청 남은 신청 가능 횟수: $song-remaining-limit-per-user 회 / 입력: 마지막남은뚜또: !내신청 / 출력: 남은 신청 가능 횟수: 2 회 / (유저제한을 설정하지 않았거나 무제한(-1)이면 곡 수 대신 `-1` 이 나와요.)

- $song-remaining-limit-total — 전체 대기열에 추가 가능한 곡 수를 출력해요. / 예: !추가 !신청가능 전체 신청 가능: $song-remaining-limit-total 곡 / 입력: 마지막남은뚜또: !신청가능 / 출력: 전체 신청 가능: 15 곡 / (전체갯수제한을 설정하지 않았거나 무제한(-1)이면 곡 수 대신 `-1` 이 나와요.)

[신청곡 자세히 보기 →](/docs/features/song-request)

---

### 가위바위보

- $rock-paper-scissors — 가위바위보를 진행해요. 명령어 뒤에 가위/바위/보를 입력해야 해요. / 예: !추가 !가위바위보 $rock-paper-scissors / 입력: 마지막남은뚜또: !가위바위보 가위 / 출력: (마지막남은뚜또) [가위] VS [보] - 승리 | 1W 0D 0L | 연속 1번 승리

- $rock-paper-scissors:가위 — 사용자의 선택을 가위로 고정해요. 봇은 여전히 랜덤이에요. 빠른 입력에 유용해요! / 예: !추가 !가위 $rock-paper-scissors:가위 / 입력: 마지막남은뚜또: !가위 / 출력: (마지막남은뚜또) [가위] VS [바위] - 패배 | 0W 0D 1L | 연속 0번 승리

**빠른 가위바위보**

`$rock-paper-scissors:가위`를 사용하면 `!가위바위보 가위` 대신 `!가위`만 입력해서 빠르게 게임할 수 있어요!

- $rock-paper-scissors:바위 — 사용자의 선택을 바위로 고정해요. 봇은 여전히 랜덤이에요. / 예: !추가 !바위 $rock-paper-scissors:바위 / 입력: 마지막남은뚜또: !바위 / 출력: (마지막남은뚜또) [바위] VS [바위] - 무승부 | 0W 1D 0L | 연속 0번 승리

- $rock-paper-scissors:보 — 사용자의 선택을 보로 고정해요. 봇은 여전히 랜덤이에요. / 예: !추가 !보 $rock-paper-scissors:보 / 입력: 마지막남은뚜또: !보 / 출력: (마지막남은뚜또) [보] VS [가위] - 패배 | 0W 0D 1L | 연속 0번 승리

- $rps-winrate — 가위바위보 승률(퍼센트만)을 출력해요. / 예: !추가 !승률 $nick님의 가위바위보 승률: $rps-winrate / 입력: 마지막남은뚜또: !승률 / 출력: 마지막남은뚜또님의 가위바위보 승률: 47.00%

**방송 중에만 가능**

가위바위보는 방송 중에만 할 수 있어요.
방송 중이 아니면 `방송중이 아닙니다.`가 출력돼요.

**기본값은 하루 1판이에요**

설정을 바꾸지 않으면 시청자 한 명이 **하루에 한 판**만 할 수 있어요.
`!설정 가위바위보 하루판수 -1` 로 무제한으로 바꿀 수 있어요.

[가위바위보 자세히 보기 →](/docs/features/rock-paper-scissors)

---

### 영상 후원 대기열

시청자가 보낸 영상 후원이 얼마나 밀려 있는지 알려주는 변수예요.

- $videoQueueCount — 대기 중인 영상 후원 개수를 출력해요. / 예: !추가 !영상대기 대기 중인 영상: $videoQueueCount개 / 입력: 마지막남은뚜또: !영상대기 / 출력: 대기 중인 영상: 3개

- $videoQueueRemainingTime — 대기열이 전부 끝날 때까지 남은 시간을 사람이 읽기 좋게 출력해요. / 예: !추가 !영상대기시간 전부 끝나기까지 $videoQueueRemainingTime 남았어요 / 입력: 마지막남은뚜또: !영상대기시간 / 출력: 전부 끝나기까지 12분 30초 남았어요

- $videoRemainingTime — 지금 재생 중인 영상 후원의 남은 시간을 출력해요. / 예: !추가 !지금영상 이 영상 $videoRemainingTime 남음 / 입력: 마지막남은뚜또: !지금영상 / 출력: 이 영상 42초 남음

**초 단위 숫자만 필요하다면**

`$videoQueueRemainingSec` · `$videoRemainingSec` 를 쓰면 `750` 처럼 **숫자만** 나와요.
계산이나 조건 분기에 쓰기 좋아요.

**봇 권한 필요**

영상 후원 정보를 읽으려면 **봇에게 채널 관리자 권한**이 있어야 해요.
권한이 없으면 `[오류, 봇 권한 필요]` 가 출력돼요.
[권한 부여 방법 →](/docs/getting-started/permissions)

**팁**

`!영상대기` 같은 명령어를 만들어두면 시청자가 직접 순번을 확인할 수 있어요.

---

### 시청자 참여

- $viewer_participation — 시청자 참여 기능을 활성화해요. 시청자가 참여하고, 추첨을 진행할 수 있어요. / 예: !추가 !참여 $viewer_participation / 입력: 마지막남은뚜또: !참여 참여 / 출력: 마지막남은뚜또님의 참여가 완료되었습니다. 현재 참여자 수: 5명

**사용 방법:**
- `!참여 참여` - 참여 등록
- `!참여 취소` - 참여 취소
- `!참여 추첨 N` - N명 추첨 (매니저 이상)

**방송 중에만 가능**

시청자 참여는 방송 중에만 할 수 있어요.
방송 중이 아니면 `방송중이 아닙니다.`가 출력돼요.

---

### 룰렛

- $roulette:룰렛ID — 대시보드에서 만든 룰렛을 실행해요. / 예: !추가 !룰렛 $roulette:3f9a1c2e-5b7d-4e10-9a3c-2f8b6d4e1a70 / 입력: 마지막남은뚜또: !룰렛 / 출력: (룰렛 결과에 따라 다름) / (룰렛ID 는 직접 정하는 이름이 아니라 자동 발급되는 UUID 예요. 대시보드 룰렛 목록에서 각 카드 오른쪽 아래 작은 글씨의 괄호 안 값을 복사해 쓰세요.)

**옵션:**
`$roulette:룰렛ID|횟수` 형태로 여러 번 돌릴 수 있어요.
```
!추가 !10연차 $roulette:3f9a1c2e-5b7d-4e10-9a3c-2f8b6d4e1a70|10
```

---

### 커스텀 스크립트

- $custom_script:스크립트ID — 대시보드에서 작성한 커스텀 스크립트를 실행해요. / 예: !추가 !스크립트 $custom_script:3f9a1c2e-5b7d-4e10-9a3c-2f8b6d4e1a70 / 입력: 마지막남은뚜또: !스크립트 / 출력: (스크립트 결과에 따라 다름) / (스크립트ID 는 직접 정하는 이름이 아니라 자동 발급되는 UUID 예요. 대시보드 커스텀 스크립트 목록의 '스크립트 UUID' 열 값을 복사해 쓰세요.)

**참고**

커스텀 스크립트는 대시보드에서 **Python 3.9** 로 작성해요.
언어는 만들 때 한 번 고르면 바꿀 수 없고(바꾸려면 삭제 후 다시 생성), 실행 제한은 메모리 128M · 1초예요.

---

### 게임 연동

게임 계정을 연동하면 티어와 닉네임을 조회할 수 있어요.

**지원 게임** (아래 이름만 인식해요. 다른 이름을 쓰면 `[잘못된 게임이 입력되었습니다.]` 가 나와요):
- `롤` - 리그 오브 레전드
- `TFT` / `tft` - 전략적 팀 전투
- `발로란트` / `발로` / `발로란트한국` / `발로란트한섭` / `발로한국` / `발로한섭` - 발로란트 (한국)
- `발로란트아시아` / `발로란트아섭` / `발로아시아` / `발로아섭` - 발로란트 (아시아)
- `오버워치` / `오버워치2` / `옵치` - 오버워치 2
- `배그` / `배틀그라운드` - 배틀그라운드
- `이터널리턴` / `이리` - 이터널 리턴

- $game_tier:롤 — 리그 오브 레전드 티어 정보를 출력해요. 솔랭/자랭 옵션 가능. / 예: !추가 !롤티어 $game_tier:롤 / 입력: 마지막남은뚜또: !롤티어 / 출력: 개인/2인 랭크 | 다이아몬드 IV 45 LP | 120 승 | 100 패 (승률: 54.55%) / (큐 이름은 입력한 별칭(솔랭)이 아니라 `개인/2인 랭크` · `자유 랭크` 로 표시돼요. 큐를 지정하지 않으면 조회된 랭크가 쉼표로 이어져 여러 개 나와요.)

**큐 타입 필터**

`$game_tier:롤|솔랭` 또는 `$game_tier:롤|자랭`으로 특정 큐만 조회할 수 있어요.

- $game_tier:tft — 전략적 팀 전투(TFT) 티어 정보를 출력해요. / 예: !추가 !tft티어 $game_tier:tft / 입력: 마지막남은뚜또: !tft티어 / 출력: TFT 랭크 | 다이아몬드 IV 45 LP | 120 승 | 100 패 (승률: 54.55%)

- $game_tier:발로란트 — 발로란트 티어 정보를 출력해요. 최근 5경기 경쟁전 기준. / 예: !추가 !발로티어 $game_tier:발로란트 / 입력: 마지막남은뚜또: !발로티어 / 출력: [한국 서버] | 다이아 2 (60.0% | KDA 1.50:1 | ADR 156) 승패승승패

- $game_tier:오버워치 — 오버워치 2 티어 정보를 출력해요. / 예: !추가 !오버워치티어 $game_tier:오버워치 / 입력: 마지막남은뚜또: !오버워치티어 / 출력: 탱커: 골드 | 딜러: 플래티넘 | 힐러: 다이아몬드

- $game_tier:배그 — 배틀그라운드 티어 정보를 출력해요. / 예: !추가 !배그티어 $game_tier:배그 / 입력: 마지막남은뚜또: !배그티어 / 출력: 경쟁전: 플래티넘(3500점) | 경쟁전 솔로: 골드(2800점)

- $game_tier:이터널리턴 — 이터널 리턴 티어 정보를 출력해요. / 예: !추가 !이터널티어 $game_tier:이터널리턴 / 입력: 마지막남은뚜또: !이터널티어 / 출력: 다이아몬드 1 (MMR 6200) | 우승 횟수 50번 | 평균 킬 3.50 | 평균 어시 2.30 | 평균 사냥 4.20 / (순위(`324위`)는 이터니티·데미갓·미스릴 티어에서만 붙어요.)

- $game_nick:롤 — 연동된 게임 계정의 닉네임을 출력해요. / 예: !추가 !롤닉 $game_nick:롤 / 입력: 마지막남은뚜또: !롤닉 / 출력: Hide on bush#KR1

**참고**

롤 · TFT · 오버워치2 · 배그 · 이터널리턴은 채팅창에서 `!설정 게임연동 [게임명] [닉네임]` 으로 연동해요.
**발로란트만** 대시보드에서 연동해요. [게임 전적 문서 →](/docs/features/game-tier)

**게임 연동 에러 응답**

- 연동된 계정이 없으면 `[연결된 계정이 없습니다.]`가 출력돼요.
- 잘못된 게임 이름을 입력하면 `[잘못된 게임이 입력되었습니다.]`가 출력돼요.
- 데이터가 없을 때 나오는 문구는 게임마다 달라요.
  - 롤 · TFT — `[데이터가 없습니다. 배치중에는 표시되지 않습니다.]`
  - 배그 — `[데이터가 없습니다.]`
  - 발로란트 — `[오류: 랭크 정보를 불러올 수 없습니다.]`
  - 오버워치 — `탱커: 없음 | 딜러: 없음 | 힐러: 없음`

---

### 스포티파이 연동

스포티파이를 연동하면 현재 재생 중인 음악 정보를 조회하고 제어할 수 있어요.

- $spotify-name — 현재 재생 중인 노래 제목을 출력해요. / 예: !추가 !지금노래 🎵 $spotify-name / 입력: 마지막남은뚜또: !지금노래 / 출력: 🎵 Ditto

**참고**

재생 중인 곡이 없으면 `재생중인 노래가 없습니다.`가 출력돼요.

- $spotify-artists — 현재 재생 중인 노래 아티스트를 출력해요. / 예: !추가 !아티스트 🎤 $spotify-artists / 입력: 마지막남은뚜또: !아티스트 / 출력: 🎤 NewJeans

- $spotify-link — 현재 재생 중인 노래의 스포티파이 링크를 출력해요. / 예: !추가 !노래링크 $spotify-link / 입력: 마지막남은뚜또: !노래링크 / 출력: https://open.spotify.com/track/...

- $spotify-song-requests — 스포티파이에 노래를 신청해요. 검색어로만 신청할 수 있어요. / 예: !추가 !스포신청 $spotify-song-requests / 입력: 마지막남은뚜또: !스포신청 Ditto / 출력: 신청이 완료되었습니다: Ditto / (유튜브 신청곡과 달리 링크로는 신청할 수 없어요. 곡 제목이나 아티스트로 검색해주세요.)

**스포티파이 신청곡 제어**

- `!스포신청 열기` / `!스포신청 닫기` - 신청곡 열기/닫기 (매니저 이상)
- `!스포신청 재생` / `!스포신청 정지` - 재생/일시정지 (매니저 이상)

- $spotify-skip — 현재 재생 중인 노래를 스킵해요. / 예: !추가 !스포스킵 $spotify-skip / 입력: 마지막남은뚜또: !스포스킵 / 출력: 노래 스킵 신호를 전송하였습니다. / (변수 자체에는 권한 제한이 없어요. 대시보드에서 명령어 필요 권한을 매니저로 지정하세요.)

**참고**

스포티파이 연동은 대시보드에서 설정할 수 있어요.
프리미엄 계정은 필요 없지만, **연동 전에 지원 디스코드로 스포티파이 계정 이메일을 알려주셔야 해요.**
스포티파이 정책상 테스트 인원으로 등록해야 연동이 열립니다.

**방송 중에만 가능**

스포티파이 관련 변수는 방송 중에만 동작해요. 방송이 꺼져 있으면 변수마다 다른 문구가 나와요.

| 변수 | 방송이 꺼져 있을 때 |
|---|---|
| `$spotify-name` · `$spotify-artists` · `$spotify-link` | `방송중이 아닙니다. 조회는 방송 중에만 가능합니다.` |
| `$spotify-song-requests` | `방송중이 아닙니다. 신청은 방송 중에만 가능합니다.` |
| `$spotify-skip` | `방송중이 아닙니다. 수정은 방송 중에만 가능합니다.` |

---

## 다음 단계

변수를 익혔다면, 출석 체크 등 다른 기능도 살펴보세요.

[출석 체크 →](/docs/features/attendance)

---

# 자주 묻는 질문

출처: https://chzzk-bot.ddutto.com/docs/faq
설명: 뚜봇 사용 중 자주 묻는 질문과 답변이에요. 봇 초대, 권한, 룰렛이 안 돌아갈 때, 오버레이가 안 보일 때 해결법을 모았어요.

뚜봇 사용 중 자주 묻는 질문과 답변을 모았어요.
원하는 답변을 못 찾으셨다면 디스코드에서 질문해주세요!

---

## 봇 초대/입장

### Q: 봇을 어떻게 넣나요?

**A:** [대시보드](https://chzzk-bot.ddutto.com/dashboard)에 네이버 계정으로 로그인하고 치지직 채널을 연동한 뒤, **[뚜봇 초대하기]** 를 누르면 돼요.

**참고**

예전처럼 치지직 커뮤니티에 `봇 입장을 희망합니다.` 댓글을 다는 방식은 **이제는 쓰지 않아요.**

[자세한 방법 →](/docs/getting-started/invite-bot)

---

### Q: 봇이 채널에 입장하지 않아요

**A:** 다음 사항을 확인해보세요:

1. **스트리머 본인 계정**으로 로그인했는지 확인 (매니저는 봇을 넣을 수 없어요)
2. 치지직 계정 연동이 되어 있는지 확인
3. 이미 봇이 입장한 상태인지 확인 (`!업타임` 명령어로 테스트)

문제가 지속되면 [디스코드](https://discord.com/invite/QftHRJCTPZ)로 문의해주세요.

---

### Q: 봇을 채널에서 퇴장시키고 싶어요

**A:** 채팅창에서 `!퇴장` 명령어를 사용하면 돼요.

```
!퇴장
```

**스트리머만** 사용할 수 있어요. 명령어를 입력하면 인증번호가 나오고, `!퇴장 [인증번호]`를 입력하면 봇이 퇴장해요.

**주의**

봇이 퇴장하면 **명령어·변수 기능이 전부 꺼지고**, 채널이 대시보드 목록에서 사라져요.
봇도 채팅방에서 나가요.

기록 자체는 남아 있어서, 나중에 봇을 다시 초대하면 **예전 명령어와 출석 기록이 그대로 돌아와요.**
(봇은 퇴장할 때 "데이터(변수, 명령어 등)이 제거되었습니다" 라고 안내하지만 실제로는 기능만 꺼지는 것이에요)

그래도 채널이 목록에서 사라져 대시보드로 손댈 수 없게 되니, 잠깐 쉬는 거라면
`!퇴장` 대신 필요한 기능만 개별로 꺼두시는 걸 권해요.

---

### Q: 봇 UID가 뭔가요?

**A:** 봇에게 권한을 부여할 때 필요한 고유 식별자예요.

**뚜봇 UID 목록:**

| 봇 이름 | UID |
|---------|-----|
| 뚜봇 | `f61127606edd1902e89f7e9cace91059` |
| 뚜이봇 | `7539c7aff49cb4b33f2cac6824d3d0e1` |
| 뚜삼봇 | `62e27807733d3e011866db387f49027b` |
| 뚜사봇 | `ee144a96804e71430ad25f5cd46f360a` |
| 뚜오봇 | `afe0c98ec9a277c17f0ac110a9159cf5` |
| 뚜육봇 | `5224cfe7d9a0e8ac84582f934df0d4a4` |
| 뚜칠봇 | `22cdbe7a2e5d6736e1a1c033409cbeb2` |
| 뚜팔봇 | `eea5d291b388f7ef8ba966d77006d35a` |
| 뚜구봇 | `8e0508081382ebce3b547037cf436fa3` |

**팁**

어떤 봇이 입장했는지는 디스코드에서 확인하거나, 대시보드에서 확인할 수 있어요.

---

### Q: 어떤 봇에게 권한을 줘야 하나요?

**A:** 내 채널에 입장한 봇에게 권한을 부여하면 돼요.

봇이 처음 입장하면 채팅에 이렇게 나와요.

> 봇 입장을 희망하셔서, **'뚜봇'** 이(가) 입장하였습니다.

여기서 **봇 이름**을 확인하고, 위 UID 목록에서 해당 봇의 UID를 찾아 권한을 부여하세요.

---

## 기능이 작동하지 않아요

### Q: 후원했는데 룰렛이 안 돌아가요

**A:** **가장 흔한 원인은 후원 금액이 숨겨져 있는 것**이에요.

뚜봇은 치지직이 보내주는 **후원 이벤트**를 직접 받아요. 다만 금액을 가려두면 봇에게는 **0원**으로 들어와서 룰렛 금액과 맞춰볼 수가 없어요.

**익명 후원**도 룰렛은 정상적으로 돌아가고 `익명의 후원자` 로 기록에 남아요.
봇에게 채널 관리자 권한이 있으면 익명 후원이어도 실제 후원자 신원까지 기록돼요.
익명이 아예 배제되는 건 **참여 제한(리밋)이 걸린 룰렛** 하나뿐이에요.

**해결 방법** — 아래 중 하나를 하시면 돼요.

1. 사용 중인 뚜봇에게 **채널 관리자 권한** 부여
2. **우회 권한(채널 관리자)** 신청
3. 디스코드에서 `#팔로우알림-우회-신청` 작성

그 외에 확인할 것:

- 룰렛 **확률 합계가 100%** 인지 (합이 안 맞으면 후원·명령어로는 조용히 실패해요)
- 후원 금액이 룰렛 금액과 **정확히 일치**하는지 (1,000치즈 룰렛에 1,500치즈는 발동 안 함)
  - 단 **연차**를 설정해뒀다면 별도로 지정한 금액도 인식하고, **자동 연차**를 켜뒀다면 배수 금액도 인식해요 (1,000치즈 룰렛에 2,000치즈 → 2회)
- 룰렛 **스위치가 켜져 있는지**

[룰렛 문제 해결 자세히 보기 →](/docs/features/roulette)

---

### Q: "다른 봇이 감지되어 ○○을 켤 수 없습니다"라고 나와요

**A:** 채널에 **다른 챗봇이 함께 들어와 있으면** 일부 기능이 막혀요. 알림이 중복으로 나가는 것을 막기 위한 장치예요.

**막히는 기능**

- 팔로우 알림 켜기
- 게임 티어 조회 (`$game_tier:`)
- 게임 닉네임 조회 (`$game_nick:`)
- 신청곡
- 노래방
- 스포티파이 신청곡 (`$spotify-song-requests`)

**이미 켜둔 것도 자동으로 꺼져요**

다른 봇이 처음 감지되는 순간, 뚜봇이 **팔로우 알림 · 신청곡 명령어 · 룰렛 자동 연차 ·
룰렛 연차 설정을 스스로 꺼요.** 무엇을 껐는지는 채팅으로 알려줘요.

다른 봇을 내보낸 뒤에는 껐던 것들을 **직접 다시 켜주셔야** 해요.

다른 봇을 내보낸 뒤 다시 시도해보세요. 오류라고 생각되시면 [디스코드](https://discord.com/invite/QftHRJCTPZ)로 문의해주세요.

---

### Q: 오버레이가 화면에 안 보여요

**A:** 순서대로 확인해보세요.

1. 설정 후 **저장**을 눌렀나요?
2. **주소 복사** 버튼으로 복사한 주소를 넣었나요?
3. OBS 브라우저 소스의 **너비·높이**가 0은 아닌가요?
4. 소스가 **다른 소스에 가려져** 있진 않나요? (소스 순서를 위로)
5. 해당 **기능 자체가 켜져 있나요?** (예: 팔로우 알림 오버레이는 `!팔로우알림 켜기` 가 선행되어야 해요)

[오버레이 문제 해결 자세히 보기 →](/docs/features/overlay)

---

### Q: 오버레이 주소를 방송에 보여줘도 되나요?

**A:** **절대 안 돼요.** 주소를 아는 사람은 누구나 그 오버레이를 열어볼 수 있어요.

그래서 뚜봇은 주소를 기본적으로 가려두고, 클릭해서 확인한 뒤 **20초가 지나면 자동으로 다시 가려요.** 방송 화면에 주소가 잡히지 않도록 주의해주세요.

---

## 권한 설정

### Q: 권한 슬롯이 가득 찼어요

**A:** 한도는 **내 채널**이 아니라 **봇 계정** 쪽에 걸려 있어요.
치지직은 한 계정이 **받을 수 있는 매니저 권한을 100개**로 제한해요.

> 이 계정은 너무 많은 채널들의 관리자로 등록되어 있어 더 이상 추가할 수 없습니다

그래서 내 채널에서 다른 계정의 권한을 풀어도 해결되지 않아요. 이미 꽉 찬 건 뚜봇 계정 쪽이니까요.

**해결 방법:** 아직 자리가 남은 다른 뚜봇(뚜육봇 · 뚜칠봇 등)에 권한을 주거나, 우회 계정을 이용하세요.
[자세한 방법 →](/docs/getting-started/permissions)

---

### Q: '채널 관리자' 권한은 어떻게 부여하나요?

**A:** 채널 관리자 권한은 **채널 소유자(스트리머)만** 부여할 수 있어요.

[권한 부여 방법 →](/docs/getting-started/permissions)

---

### Q: '채팅 운영자' 권한은 어떻게 부여하나요?

**A:** 채팅 운영자 권한은 스트리머 또는 채널 관리자가 부여할 수 있어요.

[권한 부여 방법 →](/docs/getting-started/permissions)

---

## 명령어

### Q: 명령어가 작동하지 않아요

**A:** 다음 사항을 확인해보세요:

1. 명령어 접두사(`!`)를 올바르게 입력했는지 확인
2. 해당 명령어가 활성화되어 있는지 대시보드에서 확인
3. 권한이 필요한 명령어인 경우 봇에게 권한이 있는지 확인
4. 봇이 채널에 입장해 있는지 확인 (`!업타임`으로 테스트)

---

### Q: 커스텀 명령어는 어떻게 추가하나요?

**A:** 두 가지 방법이 있어요:

**방법 1: 채팅창에서 추가**
```
!추가 !인사 안녕하세요! 반갑습니다 :>
```

**방법 2: 대시보드에서 추가**
1. 대시보드 접속
2. 좌측 **뚜봇 관리 → 유저 명령어** 클릭
3. 목록 오른쪽 위 **추가** 버튼 클릭
4. 명령어와 응답을 넣고 **추가** 클릭

[커스텀 명령어 자세히 보기 →](/docs/commands/custom)

---

### Q: 변수가 작동하지 않아요

**A:** 다음 사항을 확인해보세요:

1. 변수 이름이 정확한지 확인 (대소문자 구분)
2. `$` 기호가 앞에 붙어있는지 확인
3. `:` 이 들어간 변수는 뒤에 띄어쓰기가 필요해요
   - ✅ `$countdown:2025-12-25 메리크리스마스!`
   - ❌ `$countdown:2025-12-25메리크리스마스!`

[변수 자세히 보기 →](/docs/commands/variables)

---

## 대시보드

### Q: 대시보드 로그인이 안 돼요

**A:** 다음 사항을 확인해보세요:

1. **네이버 계정**으로 로그인 중인지 확인 (대시보드 로그인은 네이버 계정을 사용해요)
2. 브라우저 쿠키/캐시 삭제 후 재시도
3. 다른 브라우저로 시도
4. 시크릿 모드(프라이빗 모드)로 시도

**네이버 로그인 vs 치지직 연동**

- **네이버 로그인**: 대시보드 계정 인증용
- **치지직 연동**: 채널 소유권 확인용. **스트리머 본인은 치지직 로그인(OAuth)** 으로만 확인해요
- **채팅창 인증 코드**: **매니저**가 권한을 받을 때 쓰는 경로예요. `!인증` 이 매니저 전용 명령어라 구독자는 쓸 수 없어요.
  스트리머도 이 방법을 쓸 수 없어요 (`스트리머는 해당 방법으로 인증할 수 없습니다. 치지직 로그인을 이용해주세요.`)

---

### Q: 설정을 변경했는데 적용이 안 돼요

**A:** 설정 변경 후 '저장' 버튼을 눌렀는지 확인해보세요.
일부 설정은 적용까지 시간이 걸릴 수 있어요 (최대 1분).

---

### Q: UID는 어디서 확인하나요?

**A:** UID를 확인하는 방법:

1. 치지직에서 원하는 사용자의 프로필 클릭
2. 주소창에서 `chzzk.naver.com/` 뒤의 문자열이 UID예요

**예시:**
- 주소: `https://chzzk.naver.com/f61127606edd1902e89f7e9cace91059`
- UID: `f61127606edd1902e89f7e9cace91059`

---

## 기능

### Q: 이미 출석한 시청자에게 다른 메시지를 보여주고 싶어요

**A:** `$att_check` 변수와 삼항 연산자를 사용하면 중복 출석 시 다른 메시지를 보여줄 수 있어요.

```
!추가 !출석 #ternary:$att_check==True?$nick님 $att_add번 출석!:$nick님 오늘은 이미 출석하셨어요!
```

**팁**

`$att_check`는 출석 가능 여부를 반환해요. `True`면 출석 가능(아직 안 함), `False`면 이미 출석한 상태예요.

**방송이 꺼져 있을 때**

`$att_check` 는 **방송 여부를 보지 않아요.** 방송이 꺼져 있어도 `True` 를 돌려줘요.
정작 출석을 처리하는 `$att_add` 는 방송이 꺼져 있으면 `[방송이 꺼져있습니다.]` 를 반환해요.

그래서 방송 종료 중에 위 명령어를 치면 `홍길동님 [방송이 꺼져있습니다.]번 출석!` 처럼 어색하게 나와요.

[출석 체크 자세히 보기 →](/docs/features/attendance)

---

### Q: 신청곡 기능이 작동하지 않아요

**A:** 다음 사항을 확인해보세요:

1. 대시보드에서 신청곡 기능이 활성화되어 있는지 확인
2. `$song-requests` 변수가 포함된 명령어가 있는지 확인
3. 신청곡 대기열이 가득 찼는지 확인

---

## 기타

### Q: 버그를 발견했어요 / 기능 제안을 하고 싶어요

**A:** [디스코드 서버](https://discord.com/invite/QftHRJCTPZ)에서 제보해주세요.

---

### Q: 연령제한을 켰더니 뚜사봇, 뚜오봇이 작동하지 않아요!

**A:** 뚜사봇, 뚜오봇, 뚜구봇은 실명 인증이 되지 않아서 연령 제한 방송에 접근할 수 없어요.

연령 제한 방송에서는 **뚜봇, 뚜이봇, 뚜삼봇, 뚜육봇, 뚜칠봇, 뚜팔봇** 중 하나를 사용해주세요.

**참고**

연령 제한 방송에서 사용 가능한 봇으로 변경하려면 [디스코드](https://discord.com/invite/QftHRJCTPZ)에서 요청해주세요.

---

## 더 많은 도움이 필요하신가요?

[디스코드 서버](https://discord.com/invite/QftHRJCTPZ)에서 실시간으로 도움을 받을 수 있어요.

---

# 출석 체크

출처: https://chzzk-bot.ddutto.com/docs/features/attendance
설명: 뚜봇 출석 체크 전체 안내. 연속 출석이 이어지는 규칙과 $attendance·$att_add 등 출석 변수 11종을 다룹니다.

시청자들이 매일 출석 체크하고, 연속 기록을 쌓을 수 있는 기능이에요. 출석 변수를 명령어에 넣으면 나만의 출석 시스템을 만들 수 있어요.

---

## 출석 체크 만들기

출석 체크 명령어를 만들려면 `$attendance` 변수를 사용해요.

- $attendance — 출석 체크 완전판. 자동으로 출석 메시지를 생성해요. / 예: !추가 !출첵 $attendance / 입력: 마지막남은뚜또: !출첵 / 출력: 마지막남은뚜또님, 이 채널의 42번째 출석입니다! (연속 7일) / (명령어에 $nick이나 $name이 없으면 자동으로 닉네임을 포함해요. $att_combo가 없고 연속 출석이 2일 이상이면 자동으로 연속 일수를 포함해요.)

```
!추가 [원하는명령어] $attendance
```

**명령어 이름은 자유롭게**

`!출첵`, `!출석`, `뚜하` 등 원하는 이름으로 만들 수 있어요.

**예시:**
- `!추가 !출첵 $attendance` → `!출첵`으로 출석
- `!추가 !출석 $attendance` → `!출석`으로 출석
- `!추가 뚜하 $attendance` → `뚜하`로 출석

시청자가 명령어를 입력하면 이렇게 나와요.

- **처음 출석**: `마지막남은뚜또님, 이 채널의 1번째 출석입니다!`
- **이미 출석함**: `마지막남은뚜또님은 이미 출석하셨습니다! (1회 출석)`
- **다음 날 출석**: `마지막남은뚜또님, 이 채널의 2번째 출석입니다! (연속 2일)`

**참고**

출석은 매일 자정(00:00, 한국 시간)에 초기화돼요.
하루에 한 번만 출석할 수 있어요!

**방송 중에만 가능**

`$attendance`는 방송 중에만 출석 가능해요!
방송 중이 아니면 `방송중이 아닙니다. 방송중에만 출석체크가 가능합니다!`가 출력돼요.

---

## 연속 출석 규칙

**매일 방송하지 않아도 연속 기록이 유지돼요**

뚜봇은 **직전 방송을 기준**으로 판단해요. 그래서 **주 2~3회만 방송해도** 시청자의 연속 출석이 끊기지 않아요.

아래 중 **하나라도** 해당하면 연속 일수가 1 올라가요.

| 조건 | 설명 |
|---|---|
| 마지막 출석일 = **직전 방송 시작일** | 지난 방송에 출석했으면 유지 |
| 마지막 출석일 = **직전 방송 종료일** | 새벽까지 이어진 방송도 인정 |
| 마지막 출석일 = **어제** | 하루 있어도 이어져요 |
| 마지막 출석일 = **그저께** | 2일까지 봐줘요 |

전부 해당하지 않으면 연속 일수가 **1로 초기화**돼요.

**예시** — 화요일과 금요일에만 방송하는 채널

1. 화요일 방송에서 출석 → 연속 1일
2. (수·목 방송 없음)
3. 금요일 방송에서 출석 → 마지막 출석일이 **직전 방송 시작일(화요일)** 과 같으므로 → **연속 2일** ✅

**봇이 직전 방송 시각을 모를 때**

봇을 처음 붙였거나 방송 기록이 없는 상태에서는 연속을 **끊지 않고 그대로 이어줘요.**
시청자가 손해 보지 않도록 하기 위해서예요.

---

## 출석 메시지 커스터마이징

`$attendance` 대신 개별 변수를 조합하면 원하는 메시지를 만들 수 있어요!

### 인사말 추가하기

```
!추가 !출첵 $nick님! 반가워요! $attendance
```

**팁**

명령어에 `$nick`이나 `$name`이 있으면, `$attendance`에서 닉네임을 중복으로 안 나타내요.

---

## 출석 변수 상세

### $att_add - 출석 횟수 추가

- $att_add — 출석 횟수를 1 올리고, 출석 횟수를 출력해요. / 예: !추가 !출석업 $nick님 $att_add번째 출석하셨습니다! / 입력: 마지막남은뚜또: !출석업 / 출력: 마지막남은뚜또님 42번째 출석하셨습니다! / (당일에 이미 출석했으면 횟수를 올리지 않고 현재 횟수만 출력해요.)

**방송이 꺼져 있으면**

`$att_add` 는 `[방송이 꺼져있습니다.]`를 출력해요. 방송 중에만 쓸 수 있어요.

---

### $att_count - 출석 횟수 확인

- $att_count — 현재 총 출석 횟수를 출력해요. (횟수를 올리지 않음) / 예: !추가 !내출석 $nick님의 총 출석 횟수: $att_count번 / 입력: !내출석 / 출력: 마지막남은뚜또님의 총 출석 횟수: 42번

---

### $att_combo - 연속 출석

- $att_combo — 연속 출석 횟수를 출력해요. / 예: !추가 !연속출석 $att_combo번째 연속 출석이에요! / 입력: !연속출석 / 출력: 7번째 연속 출석이에요!

---

### $att_last - 마지막 출석 날짜

- $att_last — 마지막으로 출석한 날짜를 출력해요. / 예: !추가 !마지막출석 마지막 출석: $att_last / 입력: !마지막출석 / 출력: 마지막 출석: 2024-11-18

---

### $att_check - 출석 가능 여부

- $att_check — 오늘 출석 가능 여부를 출력해요. 가능하면 True, 이미 했으면 False / 예: !추가 !출석가능 출석 가능 여부: $att_check / 입력: !출석가능 / 출력: 출석 가능 여부: True

**조건부 출석**

`$att_check`와 삼항 연산자를 조합하면, 출석 여부에 따라 다른 메시지를 보여줄 수 있어요!

```
!추가 !출석 #ternary:$att_check==True?$nick님 $att_add번 출석!:$nick님 오늘은 이미 출석하셨어요!
```

[삼항 연산자 사용법 →](/docs/commands/custom#조건부-출력-삼항-연산자)

---

### $att_silent - 조용한 출석

- $att_silent — 출석 처리만 하고 아무것도 출력하지 않아요. / 예: !추가 !조용한출석 $att_silent / 입력: !조용한출석 / 출력: (아무것도 출력되지 않음)

**팁**

다른 변수와 조합해서 커스텀 메시지만 출력하고 싶을 때 유용해요!

**방송이 꺼져 있으면**

`$att_silent` 는 방송 중이 아닐 때 **출석 처리를 하지 않고 조용히 넘어가요.** 에러 메시지도 나오지 않아요.

---

### $att_time - 마지막 출석 시간

- $att_time — 마지막 출석 날짜와 시간을 함께 출력해요. / 예: !추가 !출석시간 마지막 출석: $att_time / 입력: !출석시간 / 출력: 마지막 출석: 2024-11-18 15:30:42

**출석 기록이 없으면**

`$att_last` 는 `2005-03-04`, `$att_time` 은 `2005-03-04 00:00:00` 이 나와요.
빈칸이 아니라 이 날짜가 "기록 없음" 표시예요.

---

### $att_count_month - 이번 달 출석

- $att_count_month — 이번 달 출석 횟수를 출력해요. / 예: !추가 !이달출석 이번 달 출석: $att_count_month 번 / 입력: !이달출석 / 출력: 이번 달 출석: 15 번 / (변수 뒤에 글자를 바로 붙이지 마세요. `$att_count_month번` 처럼 붙여 쓰면 `$att_count` 가 먼저 걸려 값이 깨질 수 있어요.)

---

### $att_count_month:N - N개월 전 출석

- $att_count_month:N — N개월 전의 출석 횟수를 출력해요. / 예: !추가 !지난달출석 지난달 출석: $att_count_month:1 번 / 입력: !지난달출석 / 출력: 지난달 출석: 20 번

**참고**

`$att_count_month:1`은 지난달, `$att_count_month:2`는 2달 전 출석 횟수예요.

**1~12만 입력할 수 있어요**

`1` 부터 `12` 까지(또는 `01`~`09`)만 인식해요. 그 밖의 값을 넣으면 이렇게 나와요.

> [오류, 월 서식이 잘못되었습니다.]

**13개월 이상 거슬러 올라가려면** 아래 `$att_count_period:` 를 쓰세요.

---

### $att_count_period - 기간별 출석

- $att_count_period:시작~끝 — 특정 기간의 출석 횟수를 출력해요. / 예: !추가 !올해출석 올해 출석: $att_count_period:2024-01-01~2024-12-31 번 / 입력: !올해출석 / 출력: 올해 출석: 150 번

**날짜 형식**

날짜는 `YYYY-MM-DD` 형식으로, 물결(`~`)로 이어서 입력해주세요.
`2024-01-01~2024-12-31` 처럼 **띄어쓰기 없이** 붙여 씁니다.

| 잘못 입력하면 | 나오는 메시지 |
|---|---|
| 물결이 없거나 두 개 이상 | `[오류, 기간 서식이 잘못되었습니다.]` |
| 시작 날짜 형식이 틀림 | `[오류, 시작 날짜 파싱 실패]` |
| 종료 날짜 형식이 틀림 | `[오류, 종료 날짜 파싱 실패]` |

**종료일 당일도 포함돼요**

`2024-01-01~2024-12-31` 로 조회하면 **12월 31일의 출석까지 포함**해서 세어줘요.
하루 모자라게 나오지 않으니 그대로 쓰시면 돼요.

**이번 달·기간 조회는 서버 기록을 씁니다**

`$att_count_month`, `$att_count_month:N`, `$att_count_period:` 세 개는 서버에 쌓인 출석 로그를 조회해요.
아주 드물게 조회가 실패하면 `[오류, 조회 실패]` 가 나올 수 있어요. 잠시 뒤 다시 시도해보세요.

---

## 변수 비교표

| 변수 | 기능 | 횟수 증가 | 방송 중에만 |
|------|------|----------|----------|
| `$attendance` | 출석 완전판 (자동 메시지) | ✅ | ✅ |
| `$att_add` | 출석 처리 + 횟수 출력 | ✅ | ✅ |
| `$att_silent` | 조용한 출석 (출력 없음) | ✅ | ✅ |
| `$att_count` | 출석 횟수만 출력 | ❌ | ❌ |
| `$att_combo` | 연속 출석 횟수 출력 | ❌ | ❌ |
| `$att_last` | 마지막 출석 날짜 | ❌ | ❌ |
| `$att_time` | 마지막 출석 날짜+시간 | ❌ | ❌ |
| `$att_check` | 출석 가능 여부 (True/False) | ❌ | ❌ |
| `$att_count_month` | 이번 달 출석 횟수 | ❌ | ❌ |
| `$att_count_month:N` | N개월 전 출석 횟수 | ❌ | ❌ |
| `$att_count_period:` | 기간별 출석 횟수 | ❌ | ❌ |

**팁**

**조회용 변수(❌ 표시)** 는 방송이 꺼져 있어도 쓸 수 있어요.
`!내출석`, `!연속출석` 같은 확인 명령어는 방송 밖에서도 잘 동작해요.

---

## 예시: 나만의 출석 명령어

### 기본 출석

```
!추가 !출석 $nick님 $att_add 번째 출석! (연속 $att_combo 일)
```

**결과**: `마지막남은뚜또님 42 번째 출석! (연속 7 일)`

이름이 겹치는 변수끼리는 뒤에 글자를 바로 붙이지 마세요. `$att_count_month번` 처럼 쓰면 `$att_count` 가 먼저 걸려 값이 깨질 수 있어요.
어느 쪽이 먼저 걸릴지는 매번 달라서, 잘 나오다가 갑자기 깨지기도 합니다.
(`$att_add번째` 는 이름이 겹치는 변수가 없어 안전해요.)

---

### 조건부 출석 (중복 방지)

```
!추가 !출석 #ternary:$att_check==True?$nick님 $att_add 번 출석! 연속 $att_combo 일!:$nick님 오늘은 이미 출석하셨어요!
```

**처음 출석**: `마지막남은뚜또님 42 번 출석! 연속 7 일!`
**중복 출석**: `마지막남은뚜또님 오늘은 이미 출석하셨어요!`

---

### 출석 확인

```
!추가 !내출석 $nick님의 출석 정보 - 총 $att_count번 / 연속 $att_combo일 / 마지막: $att_last
```

**결과**: `마지막남은뚜또님의 출석 정보 - 총 42번 / 연속 7일 / 마지막: 2024-11-18`

---

## 자주 겪는 문제

| 증상 | 원인 | 해결 |
|---|---|---|
| `방송중이 아닙니다. 방송중에만 출석체크가 가능합니다!` | 방송이 꺼져 있음 | 방송을 켠 뒤 다시 시도 |
| 숫자 대신 `[방송이 꺼져있습니다.]` 가 나옴 | `$att_add` 를 방송 밖에서 사용 | 방송 중에만 쓰거나, 조회는 `$att_count` 사용 |
| **연속 일수가 안 나와요** | `$attendance` 는 연속이 **2일 이상**일 때만 자동 표시 | 항상 보이게 하려면 `$att_combo` 를 직접 넣으세요 |
| 닉네임이 두 번 나와요 | `$nick` 과 `$attendance` 를 같이 쓰면 자동으로 하나만 나와요 | 정상 동작 — `$name` 도 동일 |
| 연속이 자꾸 1로 돌아가요 | 마지막 출석이 직전 방송·어제·그저께 중 어디에도 안 걸림 | 위 [연속 출석 규칙](#연속-출석-규칙)을 확인해보세요 |
| `[오류, 조회 실패]` | 서버 조회 일시 실패 | 잠시 뒤 다시 시도 |

**출석 현황은 대시보드에서**

대시보드 **출석 현황** 페이지에서 시청자별 출석 횟수와 연속 일수를 한눈에 볼 수 있어요.

![대시보드 출석 현황 — 시청자별 출석 횟수와 마지막 출석 시각](/static/docs/attendance/att-01-list.png)

출석 횟수 옆에 `(2일 연속)` 처럼 **연속 일수**가 함께 표시돼요. 연속이 끊긴 시청자는 횟수만 나와요.

---

## 다음 단계

출석 체크를 익혔다면, 다른 시청자 참여 기능도 확인해보세요!

[가위바위보 →](/docs/features/rock-paper-scissors) · [시청자 참여 →](/docs/features/viewer-participation) · [신청곡 →](/docs/features/song-request)

---

# 채팅 오버레이

출처: https://chzzk-bot.ddutto.com/docs/features/chat-overlay
설명: 치지직 채팅창을 방송 화면에 띄우고 꾸미는 방법. 폰트 117종·색상·투명도·TTS 읽어주기·게임 티어 표시·커스텀 CSS까지 안내해요.

**채팅창을 방송 화면에 띄웁니다**

치지직 채팅창을 그대로 방송 화면에 올리고 꾸밀 수 있어요. 폰트 117종, 색상, 투명도를 자유롭게 바꿀 수 있고
**채팅을 목소리로 읽어주는 TTS**, **시청자의 게임 티어 표시**까지 할 수 있어요.

뚜봇에서 **가장 많이 쓰이는 오버레이**예요.

---

## 1단계 — 채팅창을 OBS에 올리기

### ① 오버레이 주소 복사하기

대시보드 왼쪽 메뉴에서 **오버레이 관리 → 채팅**으로 들어가요.

![채팅 오버레이 설정 화면과 오버레이 주소 위치](/static/docs/overlay/ov-chat-01-url.png)

맨 위의 **주소 복사** 버튼을 누르면 오버레이 주소가 복사돼요.

**🚨 오버레이 주소는 절대 노출하지 마세요**

주소를 아는 사람은 누구나 이 오버레이를 열어볼 수 있어요. **방송 화면에 주소가 그대로 잡히지 않도록** 주의해주세요.

그래서 뚜봇은 주소를 기본적으로 가려두고, 클릭해서 확인한 뒤 **20초가 지나면 자동으로 다시 가려둬요.**

### ② OBS에 브라우저 소스로 추가

  1. **소스 추가**

OBS 하단 **소스** 패널에서 **+** 버튼 → **브라우저**를 선택해요.

  2. **주소 붙여넣기**

**URL** 칸에 복사한 오버레이 주소를 붙여넣어요.

  3. **크기 정하기**

채팅이 표시될 영역 크기로 **너비 · 높이**를 정해요.

화면 왼쪽에 세로로 길게 놓을 때는 **너비 500 × 높이 900** 정도가 무난해요.

  4. **확인**

**확인**을 누르면 방송 화면에 채팅이 나타나요.

**배경이 투명하게 나와요**

채팅 오버레이는 배경이 투명해서 게임 화면 위에 그대로 올려도 돼요. 따로 크로마키를 걸 필요가 없어요.

---

## 2단계 — 보기 좋게 꾸미기

설정을 바꾸면 **오른쪽 채팅 미리보기**에서 바로 확인할 수 있어요.

**참고**

설정을 바꾸면 **새로 올라오는 채팅부터** 반영돼요. 이미 화면에 떠 있는 채팅에는 소급 적용되지 않아요.

### 채팅창 기본 설정

| 설정 | 설명 |
|---|---|
| **채팅 방향** | 왼쪽 / 오른쪽 / 중간 — 채팅이 정렬될 방향 |
| **채팅 자동삭제** | N초 뒤에 채팅이 사라집니다. `0`이면 안 사라져요 |
| **최대 표시 수** | 화면에 유지할 채팅 개수 (기본 250개) |
| **채팅 줄 바꿈** | 켜면 긴 메시지가 닉네임 옆에서 이어지지 않고 통째로 다음 줄로 내려가요. 짧은 메시지는 그대로 닉네임 옆에 붙어요 |
| **강제 중앙 정렬** | 한 줄 안에서 뱃지·닉네임을 글자 높이 기준 **세로** 가운데에 맞춥니다. 가로 정렬은 위의 **채팅 방향**에서 설정해요 |

### 글씨 꾸미기

| 설정 | 설명 |
|---|---|
| **폰트** | **100종 이상** 지원 (빙그레체 기본 · 프리텐다드 9단계 · 배민 도현/주아 · 쿠키런 · 넥슨 메이플 등) |
| **글자 크기** | px 단위 |
| **글자 색** | 색상 선택 |
| **폰트 두께** | 100~900 (기본 500) |
| **줄 간격** | em 단위 (기본 1.2) |
| **그림자 설정** | 글자에 그림자를 넣어 배경과 구분 |

**게임 화면 위에서 잘 안 보인다면**

**그림자 설정**을 켜봐요. 밝은 게임 화면에서도 글씨가 또렷하게 보일 거예요. **다크 모드**나 **투명도** 조절도 함께 해보면 좋아요.

### 표시 항목 켜고 끄기

| 설정 | 설명 |
|---|---|
| **닉네임 표시** | 보낸 사람 이름을 함께 표시 |
| **플랫폼 뱃지** | 채팅이 올라온 플랫폼(치지직·트위치·유튜브) 아이콘 표시. 구독자·매니저 뱃지는 이 설정과 무관하게 항상 나와요 |
| **후원 표시** | 후원 메시지도 채팅에 띄울지 |
| **명령 호출 표시** | `!명령어` 같은 입력을 보여줄지 |
| **봇 채팅 표시** | 뚜봇이 보낸 메시지를 보여줄지 |
| **다크 모드 / 투명도** | 배경 톤 조절 |

### 효과음

**효과음 설정 → 수정**에서 채팅이 올라올 때 나는 소리를 지정할 수 있어요. **재생** 버튼으로 미리 들어보고, **효과음 볼륨**으로 크기를 조절해요.

---

## 3단계 — TTS로 채팅 읽어주기

채팅을 **목소리로 읽어주는** 기능이에요.

![TTS 설정 영역](/static/docs/overlay/ov-chat-02-tts.png)

| 설정 | 설명 |
|---|---|
| **TTS 사용** | 켜면 채팅을 읽어줘요. 읽기 형식까지 합쳐 **100자 이상**이면 읽지 않아요(닉네임 길이도 포함돼요) |
| **제공자** | **로컬** 또는 **구글 TTS**. 목소리 엔진이 아니라 볼륨·피치·속도를 어느 묶음에서 읽을지를 고릅니다 |
| **읽기 형식** | 어떤 방식으로 읽을지. 기본값 `[nick]님: [message]` |
| **무시할 접두사** | 이 글자로 시작하는 채팅은 안 읽어요 |
| **볼륨 / 피치 / 속도** | 목소리 조절 |
| **이모티콘 무시** | 이모티콘을 읽지 않기 |
| **테스트** | 지금 설정으로 한 번 들어보기 |

**TTS 남용을 막으려면**

**무시할 접두사**에 `!` 를 넣으면 명령어는 읽지 않아요.
도배가 걱정된다면 채팅 오버레이 대신 **후원 오버레이**의 TTS를 써도 좋아요 — 후원한 사람의 메시지만 읽어줘요.

**제공자 차이**

음성은 **어느 쪽을 고르든 서버에서 만들어 받아와요.** 제공자 설정은 볼륨·피치·속도를 어느 설정 묶음에서 읽을지만 바꿔요.
두 벌의 값을 따로 저장해두고 오갈 수 있다고 생각하시면 돼요.

---

## 4단계 — 시청자 게임 티어 표시 차별화 기능

채팅 옆에 **시청자 본인의 게임 티어**를 자동으로 붙여줘요.

![게임 연동 설정 영역](/static/docs/overlay/ov-chat-03-game.png)

| 설정 | 설명 |
|---|---|
| **디자인 타입** | 아이콘만 / 텍스트만 / 둘 다 표시 |
| **지원 게임** | 이터널리턴 · 리그오브레전드 · 발로란트 |

시참 방송이나 실력 기반 콘텐츠에서 **누가 어느 티어인지 한눈에** 보여줄 수 있어요.

**참고**

시청자 본인이 게임 계정을 연동해야 표시돼요. 연동 방법은 [게임 전적·티어 문서](/docs/features/game-tier)를 확인해봐요.

---

## 5단계 — 디자인 직접 바꾸기 (선택)

기본 설정으로 부족하다면 **CSS로 직접 꾸미는 것도 가능해요.**

| 설정 | 설명 |
|---|---|
| **CSS ID** | 미리 만들어진 디자인의 ID를 넣고 **적용하기** |
| **추가 CSS** | 직접 작성한 CSS를 넣기 |

**디자인은 어디서 구하나요**

지원 **디스코드**에서 다른 스트리머들이 만든 여러 디자인을 찾아볼 수 있어요. CSS ID만 복사해 넣으면 바로 적용돼요.

---

## 특정 시청자 가리기 — 블랙리스트

**블랙리스트**에 UID 또는 닉네임을 넣으면 그 사람의 채팅은 오버레이에 표시되지 않아요.
**한 줄에 한 명씩** 적으면 돼요.

**참고**

채팅 자체를 막는 기능이 아니라 **오버레이에만 안 보이게** 하는 설정이에요. 채팅 차단은 치지직에서 해주세요.

---

## 문제 해결

### 오버레이가 아예 안 보여요

| 확인할 것 | 해결 |
|---|---|
| 저장은 눌렀나요? | 설정 변경 후 **저장**을 눌러야 반영돼요 |
| 주소를 정확히 붙여넣었나요? | **주소 복사** 버튼으로 다시 복사해보세요 |
| OBS 브라우저 소스 크기가 0은 아닌가요? | 너비·높이를 확인해보세요 |
| 소스가 다른 소스에 가려져 있진 않나요? | OBS 소스 목록에서 순서를 올려보세요 |

### 채팅이 안 올라와요

**봇이 채널에 들어와 있어야** 채팅이 들어와요. 봇이 나가 있다면 `!재입장` 을 해보세요.
방송이 꺼져 있어도 채팅 자체는 정상적으로 들어와요. **테스트 모드**를 켜면 채팅이 없어도 샘플로 확인할 수 있어요.

### 설정을 바꿨는데 그대로예요

저장하면 오버레이가 자동으로 새로고침되면서 설정이 바로 적용돼요. 이때 화면에 떠 있던 채팅은 지워집니다.
그래도 그대로면 OBS 브라우저 소스에서 **새로고침**을 눌러봐요.
(대시보드 미리보기는 리로드하지 않아서 새로 올라오는 채팅부터 반영돼요.)

### 글씨가 배경에 묻혀요

**그림자 설정**을 켜거나, **글자 색**을 바꾸거나, **다크 모드**를 켜보세요.

CSS ID를 쓰고 있다면 **채팅 방향 · 폰트 · 글자 크기 · 글자 색 · 폰트 두께 · 줄 간격 · 다크 모드 · 투명도** 8개가 모두 잠깁니다.
(대시보드에서도 입력이 비활성화돼요) **그림자 설정**이나 **추가 CSS** 로 조정해주세요.

### 채팅이 너무 빨리 사라져요 / 안 사라져요

**채팅 자동삭제** 값을 조절해요. `0`으로 두면 사라지지 않고, **최대 표시 수**만큼 쌓인 뒤 오래된 것부터 밀려나가요.

---

## 다음 단계

[팔로우 알림 →](/docs/features/follow-alert) · [룰렛 →](/docs/features/roulette) · [게임 전적·티어 →](/docs/features/game-tier)

**더 궁금한 점이 있나요?**

  [디스코드](https://discord.com/invite/QftHRJCTPZ)에서 편하게 문의해주세요!

---

# 후원 알림

출처: https://chzzk-bot.ddutto.com/docs/features/donation-alert
설명: 치즈 후원이 들어오면 방송 화면에 알림을 띄우고 메시지를 읽어주는 방법. 표시 형식·이미지·효과음·TTS 설정을 안내해요.

**후원을 놓치지 않고 보여줘요**

시청자가 치즈를 후원하면 방송 화면에 알림이 뜨고, 후원 메시지를 자동으로 읽어줄 수 있어요.

이미지와 효과음으로 채널 분위기에 맞게 꾸밀 수도 있어요.

---

## 1단계 — OBS에 올리기

대시보드 왼쪽 **오버레이 관리 → 후원**으로 들어가요.

![후원 오버레이 설정 화면](/static/docs/overlay/ov-donation-01.png)

  1. **주소 복사**

맨 위의 **주소 복사** 버튼을 누릅니다.

  2. **브라우저 소스 추가**

OBS **소스 → + → 브라우저**

  3. **주소 붙여넣고 크기 정하기**

브라우저 소스의 **URL** 칸에 1번에서 복사한 주소를 붙여넣어요.

**너비 800 × 높이 300** 정도로 시작해보세요.

이미지를 크게 올렸다면 높이를 더 키워야 크게 보여요.

**🚨 오버레이 주소는 방송에 노출되면 안 돼요**

주소를 아는 사람은 누구나 열어볼 수 있어요. 방송 화면에 나타나지 않도록 주의해주세요. 확인 후 **20초 뒤 자동으로 다시 감춥니다.**

---

## 2단계 — 알림 문구 정하기

**표시 형식** 칸에 알림에 보일 문구를 적어요. 아래 변수를 넣으면 자동으로 바뀝니다.

| 변수 | 바뀌는 값 |
|---|---|
| `$nick` | 후원한 사람의 닉네임 |
| `$price` | 치즈 아이콘 + 후원 금액 |
| `$message` | 후원 메시지 |

**예시**

`$nick 님이 $price 후원!`

**$message 를 넣느냐 마느냐**

`$message` 를 **넣으면** 후원 메시지가 그 자리에 함께 표시되고,
**넣지 않으면** 아랫줄에 따로 표시돼요.

한 줄로 깔끔하게 보이고 싶다면 넣고, 메시지를 크게 강조하고 싶다면 빼두세요.

### 표시 시간 · 볼륨

| 설정 | 설명 |
|---|---|
| **표시 시간** | 알림이 화면에 떠 있는 시간 (1~60초, 기본 5초) |
| **알림 볼륨** | 효과음 크기(%) |

---

## 3단계 — 이미지와 효과음 넣기

오른쪽 위의 버튼으로 올립니다.

| 버튼 | 설명 |
|---|---|
| **이미지 업로드** | 알림에 함께 뜰 이미지. 움직이는 이미지(GIF)도 돼요. 올리지 않아도 기본 이미지가 함께 떠요 |
| **효과음 업로드** | 후원이 들어올 때 나는 소리 |

**이미지가 크면 작게 보일 수 있어요**

큰 이미지를 올리면 OBS 브라우저 소스의 **높이를 더 키워야** 큼직하게 나와요. 잘리지는 않고 소스 높이에 맞춰 축소돼요.

**미리보기에서는 소리가 안 나요**

오른쪽 미리보기는 **7초마다 샘플 후원**을 반복해서 보여줘요. 다만 **효과음과 TTS는 미리보기에서 재생되지 않아요.**

---

## 4단계 — 후원 메시지 읽어주기 (TTS)

후원 메시지를 목소리로 읽어주는 기능이에요.

| 설정 | 설명 |
|---|---|
| **TTS 사용** | 켜면 후원 메시지를 읽어줘요. 읽기 형식까지 합쳐 **100자 이상**이면 읽지 않아요(닉네임 길이도 포함돼요) |
| **제공자** | **로컬** 또는 **구글 TTS**. 목소리 엔진이 아니라 볼륨·피치·속도를 어느 묶음에서 읽을지를 고릅니다 |
| **읽기 형식** | 어떻게 읽을지 |
| **무시할 접두사** | 이 글자로 시작하는 문장은 안 읽어요. 후원 메시지가 아니라 **읽기 형식을 적용한 최종 문장** 기준이에요 |
| **볼륨 / 피치 / 속도** | 목소리 조절 |
| **이모티콘 무시** | 이모티콘은 읽지 않기 |
| **테스트** | 지금 설정으로 한 번 들어보기 |

**후원 TTS가 도배 방지에 좋아요**

채팅 TTS는 모든 채팅을 읽어서 도배되기 쉬워요.
후원 TTS는 후원한 사람의 메시지만 읽으므로 훨씬 안정적이에요.

단, 채팅 오버레이에서 **후원 표시**와 **TTS** 를 함께 켜 두면 같은 후원이 두 번 읽혀요. 둘 중 한쪽만 켜주세요.

---

## 디자인 직접 바꾸기 (선택)

**CSS ID** 에 미리 만들어진 디자인을 넣거나, **추가 CSS** 로 직접 꾸밀 수 있어요.
지원 **디스코드**에서 다른 스트리머들의 디자인을 참고할 수 있어요.

---

## 문제 해결

### 후원했는데 알림이 안 떠요

| 확인할 것 | 해결 |
|---|---|
| **저장**을 눌렀나요? | 설정만 바꾸고 저장을 안 하면 반영되지 않아요 |
| 브라우저 소스 크기가 0은 아닌가요? | 너비·높이를 확인해보세요 |
| 다른 소스에 가려져 있진 않나요? | OBS 소스 순서를 위로 올려보세요 |

**후원 인식을 정확하게 하려면**

뚜봇에게 **채널 관리자 권한**을 부여하면 후원 인식이 더 정밀해지고, 익명 후원자도 구분할 수 있어요.
[권한 부여 방법 보기](/docs/getting-started/permissions)

**금액이 0으로 보이거나 금액 조건이 안 먹을 때**

알림 자체는 금액 없이도 정상적으로 뜹니다. 다만 권한이 없으면 금액이 빠진 채로 들어와
**0원으로 표시되고, 금액 조건이 걸린 기능(룰렛 후원 감지 등)이 동작하지 않아요.**
위 채널 관리자 권한을 주시면 해결돼요.

### 소리가 안 나요

- **효과음을 올리셨나요?** 후원 알림은 기본 효과음이 없어서, 파일을 올리지 않으면 소리가 나지 않아요.
- OBS 브라우저 소스 속성에서 **소스를 통해 오디오 제어**를 켜주세요.
- **알림 볼륨**이 0은 아닌지 확인해보세요.
- 미리보기에서는 효과음이 재생되지 않아요. 미리보기 오른쪽 위의 **스피커 아이콘**을 눌러 확인해보세요.
  (TTS 확인은 TTS 칸의 **테스트** 버튼이에요. 이 버튼은 효과음을 재생하지 않아요)

### 이미지가 너무 작게 보여요

OBS 브라우저 소스의 **높이**를 늘려주세요. 이미지는 소스 높이에 맞춰 비율을 지킨 채 축소되기 때문에, 권장값인 높이 300px 에서는 최대 140px 로 나와요. 이미지 크기에 따라 400~600px까지 필요할 수 있어요.

### TTS가 이상한 걸 읽어요

- **이모티콘 무시**를 켜보세요.
- **무시할 접두사**는 후원 메시지가 아니라 **읽기 형식을 적용한 최종 문장**의 맨 앞과 비교해요.
  기본 읽기 형식은 `[nick]님: [message]` 라 문장이 항상 닉네임으로 시작해요. 그래서 `!` 를 넣어도 걸러지지 않아요.
  명령어를 거르려면 읽기 형식을 `[message]` 로 바꾼 뒤 `!` 를 넣어주세요.
- 읽는 속도가 빠르면 **속도** 값을 낮춰보세요.

---

## 다음 단계

[오버레이 전체 보기 →](/docs/features/overlay) · [팔로우 알림 →](/docs/features/follow-alert) · [룰렛 →](/docs/features/roulette)

**더 궁금한 점이 있나요?**

  [디스코드](https://discord.com/invite/QftHRJCTPZ)에서 편하게 문의해주세요!

---

# 이모티콘 뿌리기

출처: https://chzzk-bot.ddutto.com/docs/features/emoticon-spread
설명: 시청자가 채팅에 쓴 이모티콘을 방송 화면에 흩날리게 하는 방법. 애니메이션·크기·중력 설정과 구독티콘 필터를 안내해요.

**채팅 이모티콘이 화면에 흩날립니다**

시청자가 채팅에 이모티콘을 쓰면 화면에 그 이모티콘이 떨어지거나 날아가요.

설정할 것은 움직임 스타일과 크기 정도예요.

---

## 1단계 — OBS에 올리기

대시보드 왼쪽 **오버레이 관리 → 이모티콘 뿌리기**로 들어가요.

![이모티콘 뿌리기 설정 화면과 미리보기](/static/docs/overlay/ov-emoticon-01.png)

  1. **주소 복사**

맨 위의 **주소 복사** 버튼을 누릅니다.

  2. **브라우저 소스 추가**

OBS **소스 → + → 브라우저**

  3. **크기는 화면 전체로**

이모티콘이 화면 전체에 흩날려야 하므로 **방송 해상도와 같게** 잡아주세요.

보통 **너비 1920 × 높이 1080** 입니다.

  4. **맨 위로 올리기**

OBS 소스 목록에서 **가장 위**로 올려주세요. 아래에 있으면 게임 화면에 가려집니다.

**🚨 오버레이 주소는 방송에 노출되면 안 돼요**

주소를 아는 사람은 누구나 열어볼 수 있어요. 방송 화면에 나타나지 않도록 주의해주세요. 확인 후 **20초 뒤 자동으로 다시 감춥니다.**

---

## 2단계 — 움직임 조절하기

| 설정 | 기본값 | 설명 |
|---|---:|---|
| **자동삭제 시간** | 5초 | 이모티콘이 화면에 남아 있는 시간 (1~30초) |
| **이모티콘 크기** | 50px | 기본 크기 (10~400px) |
| **이모티콘 배율** | 1배 | **뿌려지는 개수**에 곱해지는 값. 2배면 이모티콘 하나당 2개가 뿌려집니다 (0.1~5배). 크기와는 무관해요. 1 미만으로 낮춰도 이모티콘 1개는 항상 뿌려져요. 개수 감소는 **같은 이모티콘을 한 채팅에서 2번 이상 반복**했을 때만 체감되고, 서로 다른 이모티콘은 종류마다 최소 1개씩 나와요 |
| **회전 속도** | 5 | 이모티콘이 도는 속도 (0.5~20) |
| **중력** | 0.5 | 클수록 빨리 떨어집니다 (0.1~2) |
| **뿌리는 힘** | 2 ~ 8 | **아래에서 위로 뿌리기** 를 골랐을 때만 나타나요. 솟는 높이 범위(0.1~10)이고, 최소·최대를 벌리면 이모티콘마다 높이가 달라져 분수처럼 보여요 |

**참고**

자동삭제 시간 · 중력 · 회전 속도는 **위에서 뿌리기** 와 **아래에서 위로** 타입에만 적용돼요.
**회전하면서 오른쪽으로** 는 이 값들을 무시하고 항상 10초 고정이에요.

### 애니메이션 타입

| 타입 | 움직임 |
|---|---|
| **위에서 뿌리기 (바운스)** | 위에서 떨어지며 바닥에서 통통 튕깁니다 |
| **아래에서 위로 뿌리기** | 아래에서 위로 솟아오릅니다 |
| **회전하면서 오른쪽으로** | 화면 오른쪽 밖에서 나타나 빙글빙글 돌며 **왼쪽으로** 가로질러 사라집니다. 항상 10초간 남아요 |

**이렇게 조합해보세요**

- **차분한 분위기** — 위에서 뿌리기 + 중력 낮게 + 자동삭제 3초
- **축제 분위기** — 아래에서 위로 + 크기 크게 + 자동삭제 8초
- **화면 방해 최소화** — 위에서 뿌리기 + 크기 작게 + 자동삭제 2초

**참고**

설정 변경은 **새로 뿌려지는 이모티콘부터** 반영돼요. 이미 날아다니는 것에는 적용되지 않아요.

---

## 3단계 — 어떤 이모티콘을 띄울지 고르기

### 본인 방 구독티콘만 나오게

켜면 **다른 채널의 구독티콘**이 걸러집니다. 내 채널 구독티콘과 치지직 기본 이모티콘은 그대로 나와요.
기본 이모티콘까지 빼려면 **기본 이모티콘 비활성화** 를 함께 켜주세요.

구독자 혜택을 강조하고 싶을 때 좋아요.

### 기본 이모티콘 비활성화

켜면 치지직 기본 이모티콘은 나타나지 않고 구독티콘만 뜹니다.

**미리보기가 비어 보여도 고장이 아니에요**

미리보기에 나오는 샘플은 **치지직 기본 이모티콘**입니다.

그래서 **'기본 이모티콘 비활성화'를 켜면** 실제 방송과 똑같이 필터에 걸려서 **미리보기가 비어 보여요.** 정상 동작이에요!

참고로 **'본인 방 구독티콘만 나오게'** 는 다른 채널의 구독티콘만 걸러내는 설정이라 샘플(기본 이모티콘)에는 영향을 주지 않아요.

---

## 디자인 직접 바꾸기 (선택)

**CSS ID** 에 미리 만들어진 디자인을 넣거나, **추가 CSS** 에 직접 쓴 코드를 넣을 수 있어요.

예를 들어 회전을 끄고 싶다면, **타입에 따라 넣을 코드가 다릅니다.**

위에서 뿌리기 · 아래에서 위로:

`.rotatingImage { transform: none !important; }`

회전하면서 오른쪽으로 — 이 타입은 **가로 이동도 같은 애니메이션이 담당**해요.
`animation: none` 을 주면 이동까지 멈춰서 이모티콘이 화면 밖에 선 채로 보이지 않게 돼요.
회전만 빼려면 애니메이션을 끄지 말고 키프레임을 덮어써야 해요.

`@keyframes emoji-rotate { 0% { transform: none; } 100% { left: -5%; transform: none; } }`

**팁**

지원 **디스코드**에서 다른 스트리머들의 디자인을 참고할 수 있어요.

---

## 문제 해결

### 이모티콘이 안 떠요

| 확인할 것 | 해결 |
|---|---|
| **저장**을 눌렀나요? | 설정만 바꾸고 저장을 안 하면 반영되지 않아요 |
| 브라우저 소스 크기가 화면 전체인가요? | 1920 × 1080 권장 |
| 소스가 맨 위에 있나요? | 게임 화면에 가려졌을 수 있어요 |
| **기본 이모티콘 비활성화**를 켜두진 않았나요? | 켜져 있으면 구독티콘만 뜹니다 |
| 시청자가 이모티콘을 쓰고 있나요? | 텍스트만 치면 아무것도 안 뜹니다 |

### 미리보기는 되는데 방송에선 안 떠요

미리보기에는 4초마다 샘플이 자동으로 뿌려집니다. 실제 채팅 이모티콘도 함께 표시되고요.
샘플이 보인다고 방송 화면까지 연결됐다는 뜻은 아니니, OBS 쪽을 따로 확인해보세요.

**기본 이모티콘 비활성화**가 켜져 있다면, 시청자가 **구독티콘**을 써야만 뜹니다.

### 화면이 이모티콘으로 도배돼요

- **자동삭제 시간**을 줄이세요 (5초 → 2~3초)
- **이모티콘 크기**(표시 크기)나 **배율**(뿌려지는 개수)을 줄이세요

### 방송이 버벅여요

이모티콘 뿌리기는 화면 전체에 움직임을 그리기 때문에 컴퓨터 성능을 좀 씁니다.

- OBS 브라우저 소스 속성에서 **FPS를 30**으로 낮춰보세요
- **자동삭제 시간**을 줄여 동시에 떠 있는 개수를 줄이세요
- **보이지 않을 때 소스 종료** 옵션을 켜두세요

---

## 다음 단계

[오버레이 전체 보기 →](/docs/features/overlay) · [채팅 오버레이 →](/docs/features/chat-overlay) · [팔로우 알림 →](/docs/features/follow-alert)

**더 궁금한 점이 있나요?**

  [디스코드](https://discord.com/invite/QftHRJCTPZ)에서 편하게 문의해주세요!

---

# 팔로우 알림

출처: https://chzzk-bot.ddutto.com/docs/features/follow-alert
설명: 새 팔로워가 생기면 채팅과 방송 화면에 알림을 띄우는 방법. 명령어 설정부터 오버레이 꾸미기까지 안내해요.

누군가 팔로우하면 채팅에 인사말이 나가고, 원하면 방송 화면에도 알림을 띄울 수 있어요.

설정은 채팅 명령어 한 줄이면 돼요.

---

## 1단계 — 팔로우 알림 켜기

방송 채팅창에 입력하세요. **매니저 이상**만 사용할 수 있어요.

`!팔로우알림 켜기`

> 뚜봇: 팔로우 알림을 켭니다.

이제 **방송 중에** 새 팔로워가 생기면 채팅에 인사말이 나가요.

**방송이 꺼져 있으면 나가지 않아요**

방송이 꺼진 동안 들어온 팔로우는 채팅 인사말도, 화면 알림도, 카운터 증가도 일어나지 않아요.
나중에 방송을 켜도 밀린 알림이 나오지는 않아요.

`!팔로우알림 테스트` 와 대시보드의 **알림 테스트** 버튼은 방송 여부와 상관없이 동작해요.

**현재 상태가 궁금하다면**

`!팔로우알림` 만 입력하면 사용법과 함께 **현재 켜짐/꺼짐 상태**를 알려줘요.

### 잘 되는지 확인하기

`!팔로우알림 테스트`

테스트 알림이 발송돼요. 알림이 꺼져 있으면 **"팔로우알림이 꺼져있습니다."** 라고 안내해요.

### 끄기

`!팔로우알림 끄기`

**참고**

`!팔로우알람` 으로 입력해도 똑같이 동작해요. 오타를 자주 내신다면 편한 쪽을 쓰세요.

---

## 2단계 — 인사말 바꾸기

기본 인사말은 이렇게 나가요.

> $nick님께서 팔로우해주셨습니다. 반가워요!!

다른 문구로 바꾸려면:

`!팔로우알림 메세지 $nick님 팔로우 감사해요! 재밌게 보고가세요 :)`

**현재 설정된 문구 확인**

`!팔로우알림 메세지`

**문구 삭제** (채팅 알림 없이 오버레이만 쓰고 싶을 때)

`!팔로우알림 메세지 제거`

**쓸 수 있는 변수**

`$nick` 을 넣으면 팔로우한 사람의 닉네임으로 바뀝니다. 다른 변수도 함께 쓸 수 있어요 — [변수 전체 목록](/docs/commands/variables)

---

## 3단계 — 방송 화면에 알림 띄우기 (오버레이)

채팅뿐 아니라 **화면에도** 알림을 띄우려면 오버레이를 추가해요.

대시보드 왼쪽 **오버레이 관리 → 팔로우 알림**으로 들어가세요.

![팔로우 알림 오버레이 설정 화면](/static/docs/overlay/ov-follow-01.png)

**🚨 오버레이 전에 명령어를 먼저 실행해야 해요**

오버레이만 추가해서는 알림이 뜨지 않아요. **1단계의 `!팔로우알림 켜기`** 를 먼저 입력해주세요.

설정 화면 맨 위에도 같은 안내가 노란 띠로 표시돼 있어요.

### 설정 항목

| 설정 | 설명 |
|---|---|
| **알림 테스트** | 지금 설정으로 알림을 한 번 띄워봅니다 |
| **주소 복사** | OBS 브라우저 소스에 넣을 오버레이 주소 |
| **글자 색 / 강조 색**(= 닉네임 색) | 알림 문구의 색상. **CSS ID 를 넣으면 잠기고 적용되지 않습니다** |
| **알림 볼륨** | 효과음 크기 (%) |
| **읽기 형식** | 알림에 표시될 문구 형식. `$nick` 만 쓸 수 있어요 (기본값 `$nick 님께서 팔로우해주셨습니다!`). 2단계의 채팅 인사말과는 별개 값이에요 |
| **이미지 업로드** | 알림에 띄울 이미지 (움짤도 가능) |
| **효과음 업로드** | 알림음 파일 |
| **CSS ID / 추가 CSS** | 디자인 직접 변경 |

**미리보기 사용법**

오른쪽 **팔로우 알림 미리보기**에서 **6초마다 샘플 알림이 반복**돼요.

단, **알림음은 미리보기에서 재생되지 않아요.** 소리는 미리보기 오른쪽 위의 **스피커 버튼**으로 확인해보세요.

### OBS에 추가하기

  1. **주소 복사**

**주소 복사** 버튼을 누릅니다.

  2. **브라우저 소스 추가**

OBS **소스 → + → 브라우저**

  3. **주소 붙여넣고 크기 정하기**

**너비 800 × 높이 250** 정도로 시작해보세요. 이미지를 크게 쓴다면 더 키우면 돼요.

**오버레이 주소는 방송에 노출되면 안 돼요**

주소를 아는 사람은 누구나 열어볼 수 있어요. 방송 화면에 나타나지 않도록 주의해주세요. 뚜봇은 확인 후 **20초 뒤 자동으로 다시 감춥니다.**

---

## 문제 해결

### `!팔로우알림 켜기`를 했는데 권한 오류가 나요

팔로우 정보를 읽으려면 뚜봇에게 치지직 **채널 관리 권한**이 필요해요. 뚜봇을 **채널 관리자**로 지정해주세요.

자세한 방법은 [권한 부여 문서](/docs/getting-started/permissions)를 참고해보세요.

### "다른 봇이 감지되어 팔로우 알림을 켤 수 없습니다"

채널에 **다른 챗봇이 있으면** 팔로우 알림을 켤 수 없어요. 알림이 중복으로 나가는 것을 막기 위한 장치예요.

다른 봇이 처음 감지되면 **켜져 있던 팔로우 알림도 자동으로 꺼집니다.** 채팅으로 알려줘요.

> 타 봇이 감지되어, 일부 기능이 비활성화됩니다.
> - 팔로우 알림이 비활성화되었습니다.

다른 봇을 내보낸 뒤 **그 봇이 마지막으로 채팅한 시점부터 약 1시간**이 지나면 다시 켤 수 있게 돼요.
다만 **알림이 저절로 돌아오지는 않아요.** `!팔로우알림 켜기` 를 다시 입력해주세요.
바로 다시 시도하면 같은 오류가 그대로 나와요. 수동으로 푸는 방법은 없어요.

1시간이 지났는데도 계속 안 되면 디스코드로 문의해주세요.

### 채팅 알림은 나오는데 화면에 안 떠요

| 확인할 것 | 해결 |
|---|---|
| 오버레이를 OBS에 추가했나요? | 3단계를 확인해보세요 |
| 설정 후 **저장**을 눌렀나요? | 저장하지 않으면 반영되지 않아요 |
| 브라우저 소스 크기가 0은 아닌가요? | 너비·높이를 확인해보세요 |
| 다른 소스에 가려져 있진 않나요? | OBS 소스 순서를 위로 올려보세요 |

### 화면에는 뜨는데 소리가 안 나요

- OBS 브라우저 소스 속성에서 **소스를 통해 오디오 제어**를 켜주세요.
- **알림 볼륨**이 0으로 되어 있지 않은지 확인해보세요.
- 미리보기에서는 원래 소리가 나지 않아요. **스피커 버튼**으로 확인해보세요.

### 알림이 너무 자주 떠요

팔로우가 몰리는 시간대에는 알림이 연달아 뜰 수 있어요. 채팅 알림만 쓰고 화면 알림은 끄고 싶다면 OBS에서 브라우저 소스를 잠시 숨겨두세요.

---

## 다음 단계

[오버레이 전체 보기 →](/docs/features/overlay) · [채팅 오버레이 →](/docs/features/chat-overlay) · [권한 부여 →](/docs/getting-started/permissions)

**더 궁금한 점이 있나요?**

  [디스코드](https://discord.com/invite/QftHRJCTPZ)에서 편하게 문의해주세요!

---

# 게임 전적 · 티어 연동

출처: https://chzzk-bot.ddutto.com/docs/features/game-tier
설명: 리그 오브 레전드, TFT, 발로란트, 오버워치2, 배틀그라운드, 이터널 리턴 티어를 채팅 명령어로 보여주는 방법을 안내해요.

**시청자가 !티어 치면 내 티어가 채팅에 뜹니다**

게임 계정을 한 번만 연동해두면, `!티어` 같은 명령어로 **현재 티어와 전적**을 채팅에 자동으로 보여줄 수 있어요.
무엇이 함께 나오는지는 게임마다 다릅니다 (승·패 횟수는 롤·TFT 에서만, 승률은 롤·TFT·발로란트에서 나와요).

**6개 게임**을 지원해요 — 리그 오브 레전드 · TFT · 발로란트 · 오버워치2 · 배틀그라운드 · 이터널 리턴

---

## 지원 게임

| 게임 | 입력할 게임명 | 연동 방법 |
|---|---|---|
| **리그 오브 레전드** | `롤` | 채팅 명령어 |
| **TFT (전략적 팀 전투)** | `TFT` `tft` | 채팅 명령어 |
| **발로란트** | `발로란트` `발로` | **대시보드** |
| **오버워치2** | `오버워치2` `오버워치` `옵치` | 채팅 명령어 |
| **배틀그라운드** | `배그` `배틀그라운드` | 채팅 명령어 |
| **이터널 리턴** | `이터널리턴` `이리` | 채팅 명령어 |

**발로란트 서버 구분**

발로란트는 서버별로 따로 연동해요.

- **한국 서버**: `발로란트` `발로` `발로란트한국` `발로란트한섭` `발로한국` `발로한섭`
- **아시아 서버**: `발로란트아시아` `발로란트아섭` `발로아시아` `발로아섭`

---

## 1단계 — 게임 계정 연동하기

### 채팅으로 연동 (롤 · TFT · 오버워치2 · 배그 · 이터널 리턴)

방송 채팅창에 아래 형식으로 입력하세요. **스트리머와 매니저(채널 관리자 · 채팅 관리자)** 가 사용할 수 있어요.

**주의**

매니저도 게임 계정을 새로 연동하거나 덮어쓸 수 있어요. 같은 게임을 다시 연동하면 이전 계정 정보는 사라집니다.

`!설정 게임연동 [게임명] [닉네임]`

**게임별 예시**

| 게임 | 입력 예시 | 닉네임 형식 |
|---|---|---|
| 리그 오브 레전드 | `!설정 게임연동 롤 뚜또#KR1` | **라이엇 ID** (`이름#태그`) |
| TFT | `!설정 게임연동 TFT 뚜또#KR1` | **라이엇 ID** (`이름#태그`) |
| 오버워치2 | `!설정 게임연동 옵치 뚜또#3123` | **배틀태그** |
| 배틀그라운드 | `!설정 게임연동 배그 ddutto` | 인게임 닉네임 |
| 이터널 리턴 | `!설정 게임연동 이터널리턴 뚜또` | 인게임 닉네임 |

**롤·TFT는 '#태그'까지 꼭 넣어줄게**

`뚜또`만 입력하면 **"잘못된 소환사 이름입니다."** 라고 나와요. 반드시 `뚜또#KR1`처럼 **`#`와 태그**를 함께 입력해야 해요.

라이엇 ID는 게임 클라이언트 우측 상단이나 프로필에서 확인할 수 있어요.

**오버워치2는 프로필이 공개여야 해요**

배틀넷 프로필이 비공개면 **"배틀태그가 잘못되었습니다. 프로필이 공개인지 확인해주세요."** 라고 나와요. 배틀넷 설정에서 프로필을 공개로 바꿔줘요.

**연동된 계정 확인하기** — 닉네임 없이 게임명까지만 입력하면 현재 연동 상태를 알려줘요.

`!설정 게임연동 롤`

### 대시보드로 연동 (발로란트)

**참고**

이 연동은 **스트리머 본인 계정으로 로그인했을 때만** 가능해요.
매니저로 들어가면 `본인 채널에서만 로그인할 수 있어요.` 만 표시돼요.

발로란트는 채팅으로 연동할 수 없어요. 채팅에 입력하면 **"발로란트는 대시보드에서 연동이 가능합니다."** 라고 안내돼요.

  1. **내 정보 관리 열기**

대시보드 좌측 메뉴에서 **내 정보 관리 → 접속 계정 정보**로 이동해요.

  2. **라이엇 계정 연동**

**라이엇과 연동하기**에서 플레이하는 서버를 선택해요.

- **한국 서버** — 한국에서 플레이한다면 이쪽
- **아시아 서버** — 아시아 서버 계정이 따로 있다면 이쪽

  3. **라이엇 로그인**

라이엇 공식 로그인 창에서 인증하면 연동이 완료돼요. 연동된 계정은 `이름#태그` 형태로 표시돼요.

**참고**

연동된 계정을 클릭하면 연동이 해제돼요.

---

## 2단계 — 티어 명령어 만들기

연동이 끝났으면 `$game_tier:` 변수로 명령어를 만들어요.

`!추가 !티어 $game_tier:롤`

이제 시청자가 `!티어`를 치면 이렇게 나와요:

```
개인/2인 랭크 | 다이아몬드 II 45 LP | 120 승 | 100 패 (승률: 54.55%)
```

### 게임별 명령어 예시

| 만드는 명령 | 시청자 입력 | 결과 |
|---|---|---|
| `!추가 !티어 $game_tier:롤` | `!티어` | 롤 티어 |
| `!추가 !롤체 $game_tier:TFT` | `!롤체` | TFT 티어 |
| `!추가 !발로티어 $game_tier:발로란트` | `!발로티어` | 발로란트 티어 |
| `!추가 !옵치티어 $game_tier:옵치` | `!옵치티어` | 오버워치2 티어 |
| `!추가 !배그티어 $game_tier:배그` | `!배그티어` | 배그 티어 |
| `!추가 !이리티어 $game_tier:이터널리턴` | `!이리티어` | 이터널 리턴 티어 |

---

## 원하는 큐만 골라서 보여주기

롤 · TFT · 배그는 **어떤 랭크를 보여줄지** 지정할 수 있어요. 게임명 뒤에 `|`를 붙이고 큐 종류를 적으면 돼요.

### 리그 오브 레전드

| 입력 | 보여주는 것 |
|---|---|
| `$game_tier:롤` | 배치를 마친 **모든 랭크** |
| `$game_tier:롤\|솔랭` | 개인/2인 랭크만 |
| `$game_tier:롤\|자랭` | 자유 랭크만 |
| `$game_tier:롤\|솔랭\|자랭` | 둘 다 |

`솔랭` = `솔로랭` · `자랭` = `자유랭` (같은 뜻)

### TFT

| 입력 | 보여주는 것 |
|---|---|
| `$game_tier:TFT\|랭크` | 일반 랭크 (`랭겜`도 동일) |
| `$game_tier:TFT\|터보` | 초고속 모드 (`터보랭`도 동일) |
| `$game_tier:TFT\|2인랭` | 2인 랭크 |
| `$game_tier:TFT\|더블랭` | 더블 업 |

### 배틀그라운드

| 입력 | 보여주는 것 |
|---|---|
| `$game_tier:배그\|경쟁전` | 스쿼드 (3인칭) |

**`경쟁전 솔로` 는 지금 쓸 수 없어요**

1인칭 스쿼드용 값이 봇에 들어 있긴 하지만, 이름에 **띄어쓰기가 있어서** 채팅으로 입력할 수 없어요.
변수를 읽을 때 공백에서 잘리기 때문에 `$game_tier:배그|경쟁전` 까지만 전달되고 `솔로` 는 그냥 글자로 남아요.

배그에서 `|` 로 지정할 수 있는 값은 `경쟁전` 뿐이에요. 아무것도 지정하지 않으면 1인칭 스쿼드 기록이 있는 경우 함께 나와요.

**솔랭만 보여주고 싶을 때**

아무것도 지정하지 않으면 자유 랭크까지 같이 나와요. 솔랭만 깔끔하게 보여주려면 `$game_tier:롤|솔랭`으로 만들어요.

---

## 게임 닉네임 보여주기

티어 말고 **연동한 닉네임만** 보여주고 싶다면 `$game_nick:`을 씁니다.

- $game_nick:롤 — 연동된 게임 닉네임을 표시해요. / 예: !추가 !롤닉 제 롤 닉네임은 $game_nick:롤 입니다! / 입력: !롤닉 / 출력: 제 롤 닉네임은 뚜또#KR1 입니다!

**전적 사이트 링크와 함께 쓰기**

닉네임 변수를 활용하면 전적 검색 링크를 안내하는 명령어도 만들 수 있어요.

`!추가 !전적 제 전적은 $game_nick:롤 로 검색해주세요!`

---

## 문제 해결

### `[연결된 계정이 없습니다.]`

해당 게임을 아직 연동하지 않았어요. 1단계를 먼저 진행해주세요. 게임명을 정확히 썼는지도 확인해봐요 — 롤 계정을 연동하고 `$game_tier:TFT`를 쓰면 이 메시지가 나와요.

### `[다른 봇이 감지되어 티어을 불러올 수 없습니다. 만일, 오류인 것 같으시다면 문의해주세요.]`

채널에 있는 **다른 챗봇이 채팅을 보내면** 티어 조회가 차단돼요.

다른 봇을 내보내도 **바로 풀리지 않아요.** 그 봇이 마지막으로 채팅한 시점부터 약 1시간이 지나야 해제돼요.
그 전까지는 다시 시도해도 같은 메시지가 나와요. (팔로우 알림 켜기·신청곡·`$game_nick:` 도 같은 차단을 받아요. `$game_nick:` 은 `[다른 봇이 감지되어 닉네임을 불러올 수 없습니다. 만일, 오류인 것 같으시다면 문의해주세요.]` 가 나와요) 오류라고 생각되면 디스코드로 문의해주세요.

### `[데이터가 없습니다.]`

아직 **배치고사를 마치지 않은** 상태예요. 롤·TFT 는 뒤에 `배치중에는 표시되지 않습니다.` 가 붙어요. 배치가 끝나야 티어가 표시돼요. 큐를 지정했다면(`|솔랭` 등) 그 큐의 배치만 안 끝났을 수도 있어요.

### `[잘못된 게임이 입력되었습니다.]`

지원하지 않는 게임명이에요. 위 **지원 게임** 표의 이름을 그대로 써봐요.

### `[잘못된 타입이 입력되었습니다.]`

큐 종류를 잘못 적었어요. 롤은 `솔랭` `자랭`, TFT는 `랭크` `터보` `2인랭` `더블랭`, 배그는 `경쟁전` 만 사용할 수 있어요.

### `[연결된 계정 정보가 올바르지 않습니다. 재등록이 필요합니다.]`

연동 정보가 손상됐어요. 1단계를 다시 진행해 재연동해주세요.

### 소환사 이름을 바꿨어요

롤·TFT 는 이름을 바꿔도 다시 연동할 필요가 없어요. 내부 식별자로 조회하기 때문에 `$game_nick:롤` 도 새 이름을 보여줘요.
다시 연동해야 하는 쪽은 **오버워치2**(배틀태그가 바뀐 경우)이고, 발로란트·배그·이터널 리턴은 `$game_nick` 이 연동 당시의 옛 닉네임을 그대로 출력해요.

---

## 다음 단계

전적 명령어를 만들었다면, 시청자 참여 기능도 붙여봐요.

[룰렛 →](/docs/features/roulette) · [출석 체크 →](/docs/features/attendance) · [변수 전체 목록 →](/docs/commands/variables)

**더 궁금한 점이 있나요?**

  [디스코드](https://discord.com/invite/QftHRJCTPZ)에서 편하게 문의해주세요!

---

# 오버레이

출처: https://chzzk-bot.ddutto.com/docs/features/overlay
설명: 뚜봇이 제공하는 오버레이 16종 전체 목록과 OBS에 추가하는 방법. 채팅·룰렛·팔로우 알림·타이머 등을 방송 화면에 띄웁니다.

**오버레이가 뭔가요?**

방송 화면 위에 채팅, 룰렛, 팔로우 알림, 타이머를 띄워줘요.

OBS의 **브라우저 소스**에 주소만 붙여넣으면 돼요. 배경이 투명해서 게임 위에 바로 올릴 수 있어요.

---

## 어떤 오버레이가 있나요

대시보드 왼쪽 **오버레이 관리** 메뉴에 사용 가능한 오버레이가 나열돼요.
일부 항목은 베타라서 승인받은 채널에만 보여요 (아래 표에 표시해뒀습니다).

### 설정할 게 많은 오버레이

각각 전용 문서가 있어요. 링크를 따라가 주세요.

| 오버레이 | 무엇을 보여주나 | 문서 |
|---|---|---|
| **채팅** | 치지직 채팅. 폰트 117종 · TTS · 게임 티어 표시 | [자세히 →](/docs/features/chat-overlay) |
| **룰렛** | 룰렛 애니메이션과 당첨 결과 | [자세히 →](/docs/features/roulette) |
| **팔로우 알림** | 새 팔로워 알림. 이미지·효과음 지정 가능 | [자세히 →](/docs/features/follow-alert) |
| **후원** | 후원 알림. 표시 형식·TTS 설정 | [자세히 →](/docs/features/donation-alert) |
| **이모티콘 뿌리기** | 채팅 이모티콘이 화면에 흩날림 | [자세히 →](/docs/features/emoticon-spread) |
| **타이머** | 카운트다운 (원형 · 시계) | [자세히 →](/docs/features/timer-counter) |
| **카운터** | 숫자 세기 | [자세히 →](/docs/features/timer-counter) |
| **신청곡** | 지금 재생 중인 곡과 대기열 | [자세히 →](/docs/features/song-request) |

### 설정이 간단한 오버레이

주소를 복사해 OBS에 넣으면 바로 동작해요. 디자인은 `CSS ID` 나 `추가 CSS` 로 꾸밀 수 있어요.

| 오버레이 | 무엇을 보여주나 | 전용 설정 |
|---|---|---|
| **시청자 수** | 현재 시청자 수 | 없음 (CSS만) |
| **승부예측** | 진행 중인 치지직 승부예측 현황 | 없음 (CSS만) |
| **노래방** | 노래방 대기열과 현재 곡 | 없음 (CSS만) |
| **최근 룰렛** | 최근 룰렛 당첨 내역 목록 | 결과 표시 형식 |
| **신청곡 목록** | 신청곡 대기열만 따로 | 배경 · 표시 곡 수(1~20) · 다크모드 |
| **중간 광고 타이머** | 다음 중간 광고까지 남은 시간 | 표기 시작 시간 |
| **그림 후원** 베타 | 시청자가 그려서 보낸 그림 | 재생·유지 시간 · 페이드아웃 · 그림 검수 · 최소 후원 금액 |
| **룰렛 사용권** 베타 | 시청자가 사용권을 썼을 때 뜨는 알림 | 승인 방식 |

**주소를 어디서 찾나요**

**최근 룰렛** 과 **신청곡 목록** 은 별도 메뉴가 아니에요.
각각 **룰렛 오버레이** · **신청곡 오버레이** 설정 페이지 안에 두 번째 주소로 들어 있어요.

**중간 광고 타이머는 권한이 필요해요**

봇에게 **채널 관리자** 권한이 있어야 해요. 없으면 대시보드 설정 페이지 자체가 열리지 않아요.

**베타 표시가 붙은 것들**

**그림 후원** · **룰렛 사용권** 은 승인받은 채널에만 메뉴가 나타나요.
승인 전에는 주소로 직접 들어가도 대시보드로 되돌려 보내져요.

**기능 자체가 켜져 있어야 해요**

오버레이는 뚜봇이 알아서 정보를 채워 넣지만, 채워 넣을 내용이 있어야 보여요.
최근 룰렛은 룰렛이 돌아가야 내역이 쌓이고, 승부예측은 치지직에서 승부예측을 시작해야 표시돼요.

**디자인 생성기**

오버레이 디자인을 AI로 만들어볼 수 있어요. 직접 CSS를 짜지 않아도 원하는 분위기의 디자인을 얻을 수 있어요.
**오버레이 관리** 메뉴 아래에 있고, 베타라서 승인받은 채널에만 나타나요.

---

## OBS에 추가하는 방법 (모든 오버레이 공통)

  1. **오버레이 메뉴 열기**

대시보드 왼쪽 **오버레이 관리**에서 원하는 오버레이를 클릭해요.

  2. **설정하고 저장**

보이는 모습을 설정한 뒤 **저장**을 누릅니다.

저장하지 않으면 반영되지 않아요.

  3. **주소 복사**

맨 위의 **주소 복사** 버튼을 누릅니다. 모든 오버레이가 이 자리에 똑같이 있어요.

![오버레이 페이지 맨 위의 오버레이 주소와 '주소 복사' 버튼](/static/docs/overlay/ov-chat-01-url.png)

  4. **OBS에서 브라우저 소스 추가**

OBS 하단 **소스** 패널 → **+** → **브라우저** 선택

  5. **주소 붙여넣고 크기 정하기**

**URL** 칸에 붙여넣고, 오버레이가 표시될 영역 크기로 **너비 · 높이**를 정해요.

  6. **확인**

**확인**을 누르면 화면에 나타나요. 위치와 크기는 드래그로 조절하세요.

**🚨 오버레이 주소는 방송에 노출되면 안 돼요**

주소를 아는 사람은 누구나 그 오버레이를 열어볼 수 있어요. 방송 화면에 나타나지 않도록 주의해주세요.

뚜봇은 주소를 기본적으로 가리고, 확인 후 **20초가 지나면 자동으로 다시 감춥니다.**

**오버레이는 종류당 1개예요**

오버레이 페이지를 처음 열면 그 종류의 오버레이가 **자동으로 하나** 만들어집니다. 따로 '추가' 할 필요가 없어요.

화면 위쪽의 **오버레이 이름**과 선택 상자는 같은 종류를 여러 개 두기 위한 것인데, 지금은 **직접 추가할 수 없어요.**
채팅 오버레이를 두 개 띄우는 것처럼 같은 종류가 두 개 필요하다면
[디스코드](https://discord.com/invite/QftHRJCTPZ)로 문의해주세요.

### 크기는 얼마로 하나요

정해진 크기는 없어요. 화면에 띄울 공간만큼 잡으면 돼요. 처음에는 아래 크기로 시작하면 좋아요.

| 오버레이 | 시작 크기 |
|---|---|
| 채팅 | 500 × 900 |
| 룰렛 | 700 × 500 |
| 팔로우 알림 · 후원 | 800 × 250 |
| 이모티콘 뿌리기 | 1920 × 1080 (전체 화면) |
| 타이머 · 카운터 · 시청자 수 | 400 × 150 |

**참고**

이모티콘 뿌리기처럼 **화면 전체에 흩날리는** 오버레이는 방송 해상도와 같게(보통 1920 × 1080) 잡아주세요.

---

## 자주 겪는 문제

### 오버레이가 안 보여요

| 확인할 것 | 해결 |
|---|---|
| **저장**을 눌렀나요? | 설정만 바꾸고 저장을 안 하면 반영되지 않아요 |
| 주소가 정확한가요? | **주소 복사** 버튼으로 다시 복사해보세요 |
| 브라우저 소스 크기가 0은 아닌가요? | 너비·높이를 확인해보세요 |
| 다른 소스에 가려져 있진 않나요? | OBS 소스 목록에서 순서를 위로 올려보세요 |
| 해당 기능이 켜져 있나요? | 예를 들어 룰렛 오버레이는 룰렛이 활성화되어 있어야 해요 |

### 설정을 바꿨는데 화면이 그대로예요

OBS 브라우저 소스 속성에서 **현재 페이지 새로고침**을 눌러보세요. 그래도 안 되면 **캐시 삭제 후 새로고침**을 시도해보세요.

### 오버레이가 끊기거나 버벅여요

- 브라우저 소스 속성에서 **FPS를 30**으로 낮춰보세요.
- **보이지 않을 때 소스 종료** 옵션을 켜면 자원을 아낄 수 있어요.
- 오버레이를 여러 개 띄웠다면 필요 없는 건 꺼주세요.
  단 **룰렛 오버레이는 켜 두세요.** 결과를 표시해야 봇이 채팅과 카운터·타이머 액션을 실행하는데,
  꺼져 있던 동안의 결과는 다시 켜도 따라잡지 않아요. ([룰렛 문서 →](/docs/features/roulette))

### 배경이 검게 나와요

브라우저 소스 속성에서 **사용자 지정 CSS** 칸에 아래가 들어 있는지 확인해보세요. OBS가 기본으로 넣어주는 값이에요.

`body { background-color: rgba(0, 0, 0, 0); margin: 0px auto; overflow: hidden; }`

### 소리가 안 나요 (TTS·효과음)

브라우저 소스 속성에서 **소스를 통해 오디오 제어**가 켜져 있는지 확인해보세요. 꺼져 있으면 OBS가 소리를 잡지 못해요.

---

## 다음 단계

[채팅 오버레이 자세히 →](/docs/features/chat-overlay) · [룰렛 →](/docs/features/roulette) · [신청곡 →](/docs/features/song-request)

**더 궁금한 점이 있나요?**

  [디스코드](https://discord.com/invite/QftHRJCTPZ)에서 편하게 문의해주세요!

---

# 가위바위보

출처: https://chzzk-bot.ddutto.com/docs/features/rock-paper-scissors
설명: 뚜봇과 가위바위보를 하는 방법. 하루 판수 제한 설정, 별명 인식, 전적·승률 변수까지 안내해요.

시청자들이 봇과 가위바위보를 하는 기능이에요. 승/무/패 전적과 연승 기록이 개인별로 쌓여요.

**시작하기 전에 꼭 읽어주세요**

**기본 설정은 "한 사람당 하루 1판"입니다.**
그래서 처음 만들면 시청자들이 한 번 하고 나서 "더 못 해요"라는 말을 듣게 돼요.
마음껏 하게 하려면 아래 명령어를 먼저 입력하세요.

```
!설정 가위바위보 하루판수 -1
```

---

## 1단계 — 명령어 만들기

가위바위보는 `$rock-paper-scissors` 변수로 동작해요.

```
!추가 !가위바위보 $rock-paper-scissors
```

**명령어 이름은 자유롭게**

`!가위바위보`, `!rps`, `!묵찌빠`, `!한판` 등 원하는 이름으로 만들 수 있어요.
아래에서는 `!가위바위보` 로 만들었다고 가정해요.

---

## 2단계 — 하루 판수 정하기 ⭐

**이 설정을 안 하면 시청자당 하루 1판까지만 가능해요.**

- !설정 가위바위보 하루판수 [숫자] — 시청자 한 명이 하루에 할 수 있는 판수를 정해요. / 예: !설정 가위바위보 하루판수 -1 / 봇 응답: 가위바위보 하루 판수가 '무제한' 으로 설정되었습니다. / 쿨타임 1s

| 값 | 동작 |
|---|---|
| **`1`** (기본값) | 한 사람당 **하루 1판**만 가능 |
| `2` ~ `100` | 한 사람당 하루 그 횟수만큼 가능 |
| **`-1`** | **무제한** — 몇 번이든 가능 |
| `0` | 게임 잠금 — `지금은 게임을 할 수 없습니다.` |

**판수는 자정에 초기화돼요**

날짜(한국 시간 기준)가 바뀌면 모든 시청자의 오늘 판수가 0으로 돌아가요.
새벽 방송 중에 자정이 지나면 그 순간부터 다시 할 수 있어요.

판수를 다 쓴 시청자에게는 이렇게 나와요.

> 하루에 1번만 가능합니다. 마지막 게임: 2026-07-30 / 전적: 3W 1D 2L (연속 0번 승리)

**어떻게 설정하는 게 좋을까요?**

- **소통 방송에서 가볍게** → `-1` (무제한). 시청자가 원할 때 자유롭게
- **이벤트/보상이 걸려 있다면** → `1` ~ `3`. 도배와 노가다를 막을 수 있어요
- **잠깐 막고 싶다면** → `0` (게임 중단)

---

## 3단계 — 플레이하기

명령어 뒤에 가위 / 바위 / 보를 붙이에요.

```
!가위바위보 가위
```

> (마지막남은뚜또) [가위] VS [보] - 승리 | 1W 0D 0L | 연속 1번 승리

### 결과 읽는 법

```
(닉네임) [내 선택] VS [봇 선택] - 결과 | 승W 무D 패L | 연속 N번 승리
```

| 예시 | 뜻 |
|---|---|
| `(채링) [바위] VS [바위] - 무승부 \| 2W 1D 3L \| 연속 0번 승리` | 비겼고, 연승이 끊김 |
| `(후로기) [보] VS [가위] - 패배 \| 0W 0D 1L \| 연속 0번 승리` | 졌고, 연승이 끊김 |

**참고**

**연승은 이겼을 때만 올라가고, 지거나 비기면 0으로 돌아가요.**
봇의 선택은 매번 완전 랜덤이에요.

---

## 이렇게 써도 알아들어요 (별명 인식)

`가위`, `바위`, `보` 말고도 아래 단어들을 전부 인식해요.

| 낼 것 | 인식하는 말 |
|---|---|
| **가위** | `가위` `ㄱㅇ` `ㄱ` `찌` `ㅈ` `ㅉ` `찔러` `울버린` `에드워드 가위손` `젠가` `닌자` `닌자거북이` `쌍칼` `부엌칼` `가위바위보의 가위` |
| **바위** | `바위` `ㅂㅇ` `ㅁ` `묵` `주먹` `주먹밥` `돌멩이` `돌잔치` `산` `지구` `통나무` `오딘` `더 락` `헐크` `골렘` `타노스` `둠피스트` `가 문비나무` |
| **보** | `보` `ㅂ` `ㅃ` `빠` `보자기` `보자기댄스` `종이` `한지` `이불` `장판` `철판` `아이언맨` `아이언멘` `캡틴 아메리카` `배트맨 망토` `스파이더맨` |

```
!가위바위보 묵
!가위바위보 타노스
!가위바위보 ㅃ
```

전부 정상 동작해요.

목록에 없는 말을 쓰면 안내 메시지가 나와요.

```
!가위바위보 묵찌빠
```

> 가위, 바위, 보 중에서 선택해주세요. (유저 입력: 묵찌빠)

아무것도 안 붙이면:

```
!가위바위보
```

> 가위, 바위, 보 중에서 선택해주세요. (유저 입력: 없음)

---

## 빠른 선택 명령어

시청자가 낼 것을 **미리 고정**한 명령어를 만들 수 있어요.

- !추가 !바위 $rock-paper-scissors:바위 — 시청자가 바위를 낸 것으로 자동 처리해요. (봇은 여전히 랜덤) / 예: !추가 !바위 $rock-paper-scissors:바위 / 봇 응답: '!바위' 명령어가 추가되었습니다. / 쿨타임 1s

이제 시청자가 `!바위` 만 치면 바위를 낸 것으로 처리돼요.

**봇이 고정되는 게 아니에요**

`$rock-paper-scissors:바위` 는 **시청자의 선택**을 고정하는 겁니다.
**봇은 여전히 랜덤**이라 승률이 유리해지지는 않아요.

세 개를 다 만들어두면 시청자가 한 단어로 끝낼 수 있어 편해요.

```
!추가 !가위 $rock-paper-scissors:가위
!추가 !바위 $rock-paper-scissors:바위
!추가 !보 $rock-paper-scissors:보
```

---

## 전적과 승률

전적은 **시청자 개인별**로 저장되고, 방송을 껐다 켜도 유지돼요.

| 표기 | 뜻 |
|---|---|
| **W** | 승리 (Win) |
| **D** | 무승부 (Draw) |
| **L** | 패배 (Lose) |

### 승률 확인 변수

- $rps-winrate — 가위바위보 승률을 소수점 둘째 자리까지 출력해요. / 예: !추가 !승률 $nick님의 가위바위보 승률: $rps-winrate / 입력: 마지막남은뚜또: !승률 / 출력: 마지막남은뚜또님의 가위바위보 승률: 65.00%

**승률 계산 방식**

`승 ÷ (승 + 무 + 패)` 예요. **무승부도 분모에 들어가요.**
1승 1무면 50.00% 예요.

아직 한 판도 안 한 시청자는 `0%` 로 나와요.

### 대시보드에서 전적 보기

대시보드 **가위바위보 현황** 페이지에서 시청자별 전적을 한눈에 볼 수 있어요.

![대시보드 가위바위보 전적 — 유저별 전적·우승 비율·마지막 판](/static/docs/rps/rps-01-stats.png)

| 열 | 읽는 법 |
|---|---|
| **전적** | `41전 \| 14승 / 14패 / 13무` — 괄호로 `(4연승)` 이 붙기도 해요 |
| **우승 비율** | 위 계산식 그대로. 위 그림의 `14승 / 41전` 이 **34.15%** 인 게 무승부가 분모에 들어간 결과예요 |
| **마지막 가위바위보** | 최근에 한 판 시각 |

**0번은 봇 자신이에요**

목록 맨 위 `뚜봇` 은 봇의 누적 전적이에요. 시청자 전체를 상대한 기록이라 판수가 제일 많아요.

---

## 자주 겪는 문제

| 증상 | 원인 | 해결 |
|---|---|---|
| **한 판 하고 더 안 돼요** | 하루 판수가 기본값 `1` | `!설정 가위바위보 하루판수 -1` |
| `방송중이 아닙니다.` | 방송이 꺼져 있음 | 방송 중에만 동작해요 |
| `지금은 게임을 할 수 없습니다.` | 하루 판수가 `0` 으로 잠김 | `!설정 가위바위보 하루판수 -1` |
| `가위, 바위, 보 중에서 선택해주세요.` | 인식 못 하는 단어 | 위 [별명 표](#이렇게-써도-알아들어요-별명-인식) 참고 |
| `숫자로 입력해주세요.` | 판수 자리에 글자 입력 | 숫자만 입력 |
| `100보다 작은 숫자로 입력해주세요. 무제한 게임을 원하시는 경우에는 -1을 입력하시면 됩니다.` | 101 이상 입력 | 무제한은 `-1` 입니다 |

---

## 에러 응답 정리

| 상황 | 응답 |
|------|------|
| 방송 중이 아님 | `방송중이 아닙니다.` |
| 하루 판수 소진 | `하루에 N번만 가능합니다. 마지막 게임: YYYY-MM-DD / 전적: ...` |
| 판수가 0으로 잠김 | `지금은 게임을 할 수 없습니다.` |
| 잘못된 입력 | `가위, 바위, 보 중에서 선택해주세요. (유저 입력: X)` |

---

## 다음 단계

가위바위보를 익혔으니 다른 시청자 참여 기능도 확인해봐요!

[시청자 참여 →](/docs/features/viewer-participation) · [출석체크 →](/docs/features/attendance) · [룰렛 →](/docs/features/roulette)

---

# 룰렛

출처: https://chzzk-bot.ddutto.com/docs/features/roulette
설명: 치지직 뚜봇 룰렛을 처음부터 끝까지 따라 만드는 방법. 후원 감지, 연차, 확률 설정, 권한, 제한, 오버레이 연동을 사진과 함께 안내해요.

**룰렛이 뭔가요?**

시청자가 **후원하면 방송 화면에서 룰렛이 돌아가고**, 당첨된 항목 이름이 채팅에 요약되어 나가는 기능이에요.

벌칙, 게임 결과, 선물 추첨, 시청자 순서 정하기 등에 쓸 수 있어요.

아래 순서대로 따라오면 **10분 안에** 완성돼요.

---

## 시작하기 전에 — 딱 두 가지만 확인

**🚨 1. 치지직에서 후원 금액이 공개되어 있어야 해요**

뚜봇은 **치지직 채팅창에 올라오는 후원 메시지**를 읽어서 동작해요.

그래서 치지직 설정에서 **후원 금액을 가려두면 룰렛이 전혀 돌아가지 않아요.**

**'익명의 후원자'** 는 기록에 그 이름 그대로 남습니다(빈칸이 아니에요). 다만 누구인지 알 수 없어서,
**참여 제한을 걸어둔 룰렛은 익명 후원으로 돌아가지 않아요.**

**해결 방법** — 아래 중 하나만 하시면 돼요.

- 사용 중인 뚜봇에게 **채널 관리자 권한**을 주기 ([권한 부여 방법 →](/docs/getting-started/permissions))
- **우회 권한(채널 관리자)** 신청하기
- 지원 디스코드에서 `#팔로우알림-우회-신청` 작성하기

봇에게 직접 권한을 준 경우엔 봇이 알아서 재입장해요.
우회 권한이나 디스코드 신청으로 받은 경우엔 `!재입장` 으로 다시 들여주세요.

> 룰렛이 안 도는 **가장 흔한 원인**이에요. 가장 먼저 확인해보세요!

**🚨 2. 룰렛 오버레이는 필수예요**

**오버레이를 추가하지 않으면 룰렛 결과가 채팅에도, 카운터·타이머에도 반영되지 않아요.** (당첨 기록은 남아요.) 화면에 안 보이는 정도가 아니라
채팅 결과도, 카운터·타이머 연동도 전혀 동작하지 않아요.

룰렛이 돌아가는 순서가 이렇기 때문이에요.

1. 후원이 들어오면 서버가 당첨 항목을 정해요
2. **오버레이가 결과를 화면에 표시한 뒤 서버에 "표시 끝났다"고 알립니다**
3. 그 알림을 받고 나서야 봇이 채팅에 결과를 보내고 항목 액션을 실행해요

2번이 없으면 3번이 영원히 오지 않아요. (아래 [오버레이 섹션](#방송-화면에-띄우기-오버레이) 참고)

**추가해 두고 OBS 소스를 꺼두는 것도 같습니다.** 오버레이는 꺼져 있던 동안 들어온 결과를 나중에 따라잡지 않아서,
그때의 채팅 결과와 카운터·타이머 액션은 다시 켜도 실행되지 않아요.

**채팅 결과가 나가는 조건**

후원으로 돌리는 룰렛은 **방송 중일 때만** 발동해요. 방송이 꺼져 있으면 스핀도 당첨 기록도 없습니다.
오버레이를 추가했더라도, 채팅에 결과가 나가려면 아래를 **전부** 만족해야 해요.

- **방송 중**일 것
- **당첨 항목이 2개 이상**이거나, 룰렛 설정에서 **"한 개만 돌아가도 채팅으로 알림"** 을 켰을 것

한 번에 하나만 당첨되는 룰렛인데 채팅에 아무것도 안 나온다면 두 번째 조건을 확인해보세요.

---

## 1단계 — 룰렛 만들기

### ① 룰렛 목록에서 새로 만들기

대시보드 왼쪽 메뉴에서 **룰렛**을 누른 뒤, 오른쪽 위 **룰렛 생성하기** 버튼을 눌러주세요.

![룰렛 관리 화면에서 룰렛 생성하기 버튼 위치](/static/docs/roulette/roul-01-create.png)

**참고**

이 화면 위쪽의 안내문은 꼭 한 번 읽어보세요. 위에서 설명한 **후원 금액 공개** 문제와 **룰렛이 안 돌아갈 때 확인할 것**이 적혀 있어요.
(첫 번째 안내문은 후원감지가 '채팅' 일 때만 노란색 경고로 뜨고, '모두' 로 바꾸면 초록색 안내로 바뀌어요.)

### 편집 화면은 이렇게 생겼습니다

![룰렛 편집 화면 전체 구성](/static/docs/roulette/roul-02-overview.png)

| 영역 | 하는 일 |
|---|---|
| **왼쪽 위 — 룰렛 설정** | 이름, 금액, 권한, 회전 시간 등 기본 정보 |
| **왼쪽 아래 — 연차 설정** | 많이 후원하면 여러 번 돌리기 |
| **오른쪽 위 — 룰렛 미리보기** | 방송에 어떻게 보일지 확인 · 이미지 교체 |
| **오른쪽 아래 — 룰렛 제한 설정** | 하루 횟수, 기간 등 제한 |
| **아래 — 아이템 표** | 당첨 항목과 확률 |

### ② 룰렛 금액 정하기

시청자가 **얼마를 후원하면** 룰렛이 돌아갈지 정해요. 단위는 치지직 후원 화폐인 **치즈**예요.
치지직 최소 후원 단위가 500치즈라, 룰렛 금액도 **500치즈**부터 지정할 수 있어요.
500 미만을 넣으면 안내 없이 500 으로 바뀌니 저장 전에 값을 확인하세요.

![룰렛 금액 입력란](/static/docs/roulette/roul-06-price.png)

**룰렛 이름**도 지어주세요. (예: `벌칙룰렛`, `가챠`) 나중에 여러 개를 만들면 구분하기 좋아요.

**팁**

처음이라면 **1,000치즈**로 시작해보세요. 부담 없이 참여할 수 있는 금액이라 반응을 보기 좋아요.

### ③ 누가 돌릴 수 있는지 정하기

![룰렛 필요 권한 선택](/static/docs/roulette/roul-07-permission.png)

등급마다 판정 방식이 달라요. 특히 **팔로워는 상위 등급이 통과하지 않아요.**

| 권한 | 참여 가능한 사람 |
|---|---|
| **시청자 이상 (누구나)** | 제한 없음 |
| **팔로워 이상** | 채널을 팔로우한 시청자만. **팔로우하지 않은 매니저·스트리머는 참여할 수 없습니다** |
| **구독자 이상** | 채널 구독자 또는 매니저 이상 |
| **매니저 이상** | 채널 매니저 |
| **스트리머 이상** | 본인만 |

**이 권한은 후원 감지 경로에만 적용돼요**

`$roulette:` **채팅 명령어로 돌릴 때는 이 설정을 보지 않아요.** 여기서 '구독자 이상' 으로 막아둬도
명령어를 만들어두면 아무나 칠 수 있어요.

명령어 쪽을 제한하려면 대시보드 **뚜봇 관리 → 유저 명령어** 에서 그 명령어의
**필요 권한**을 따로 올려주세요.

### ④ 당첨 항목과 확률 넣기

새로 만든 룰렛에는 **예시 항목 4개가 미리 들어 있어요** — `꽝!` 75% · `치즈 맛잇다` 12% · `움냠냠` 12% · `공포게임` 1% (합계 100%).
쓰지 않을 항목은 각 줄의 삭제 버튼으로 먼저 지우세요. 예시를 남겨둔 채 항목만 더하면 확률 합이 100%를 넘어, 저장은 되어도 룰렛이 꺼진 채로 들어갑니다.

그다음 화면 맨 아래 **아이템 추가** 버튼으로 항목을 하나씩 추가해요.

![아이템 추가와 확률 합계 표시](/static/docs/roulette/roul-05-items.png)

항목마다 두 가지를 정하세요.

- **아이템 이름** — 당첨 항목 이름 (예: 대성공, 실패)
- **확률** — 이 항목이 나올 확률 (%)

**참고**

당첨되면 **이 이름이 그대로 채팅에 나가요.** 항목별로 따로 문구를 지정하는 칸은 없어요.
그래서 이름을 곧 안내 문구처럼 지어두면 편해요 (예: `노래 부르기`, `면제`).

항목에는 이 밖에 **기록/자동 사용**, **액션(카운터·타이머)**, **사용권** 을 붙일 수 있어요.
자세한 건 아래 [항목 고급 설정](#항목-고급-설정)을 참고하세요.

**시뮬레이션으로 미리 확인해보세요**

왼쪽의 **시뮬레이션** 버튼을 누르면 지정한 횟수(기본 1000번)만큼 돌려본 결과를 보여줘요. 확률이 의도한 대로 나오는지 저장 전에 확인할 수 있어요.

### ⑤ 저장하기

![저장 버튼 위치](/static/docs/roulette/roul-09-save.png)

화면 왼쪽 위의 파란 **저장** 버튼을 누르세요. 저장하지 않으면 설정이 반영되지 않아요.

---

### ⑥ 테스트해보기

저장했다면 실제 후원 없이 돌려볼 수 있어요.

- 룰렛 목록에서 그 룰렛의 **테스트** 버튼을 누르기
- 채팅에 `!설정 룰렛 테스트 <횟수> <룰렛 이름>` 입력 (매니저 이상, 1~3000회)

오버레이를 이미 OBS 에 넣어뒀다면 화면에서 돌아가는 것까지 확인할 수 있어요.
[명령어 자세히 보기 →](/docs/commands/system)

---

## ⚠️ 확률 합계는 반드시 100%여야 해요

아이템 표 오른쪽 아래에 **전체 확률**이 표시돼요.

- 모자라면 → **"아직 N% 부족해요..!"**
- 정확히 맞으면 → **"확률이 정확해요!"**

**"확률이 정확해요!"가 뜰 때까지 맞춰주세요.**

### 100%가 아니면 어떻게 되나요?

**저장은 돼요. 대신 룰렛이 꺼진 채로 저장돼요.**

| 상황 | 결과 |
|---|---|
| 합계가 100이 아님 | 저장은 되지만 **자동으로 비활성 처리** — 목록의 스위치가 켜지지 않아요 |
| 개별 확률이 0 미만이거나 100 초과 | **저장 거부** — `확률은 0 이상 100 이하의 값이어야 합니다.` |
| 정확히 100% | ✅ 정상 저장. **새로 만든 룰렛만 켜진 상태로** 들어가요 |

**고쳐도 스위치는 저절로 안 켜집니다**

합계가 안 맞아 자동으로 꺼진 룰렛을 확률만 고쳐 저장하면, 스위치는 **꺼진 채로 남아요.**
수정 저장은 직전 상태를 그대로 유지하고, 합계가 틀릴 때만 끄기 때문이에요.

목록에서 **스위치를 직접 다시 켜주세요.**

저장했는데 목록에서 스위치가 안 켜진다면 확률 합계부터 확인해보세요.

**합계가 안 맞는 룰렛은 조용히 실패해요**

확률 합계가 100이 아닌 룰렛은 **돌아가지 않아요.**

- **후원**으로 돌리면 채팅에 아무 안내도 나가지 않아요
- **명령어**로 돌리면 `오류: 해당 룰렛을 찾을 수 없습니다.` 가 나가요.

후원 쪽은 채팅에 아무 안내도 안 나가서, 시청자 입장에서는 후원했는데 반응이 없는 것처럼 보여요.

**테스트로도 확인할 수 없어요.** 확률 합이 안 맞으면 룰렛이 꺼진 상태로 저장되고, 꺼진 룰렛은 봇이 아예 읽지 않아요.
대시보드 목록의 테스트 버튼은 눌리지 않고, `!설정 룰렛 테스트` 는 `해당 룰렛이 존재하지 않습니다.` 라고만 답해요.

대신 **룰렛 목록 카드에 빨간 글씨로 `확률 합이 100%가 아닙니다.`** 가 표시돼요.
편집 화면에서도 `아직 N% 부족해요..!` / `초과된 N%가 있어요..!` 로 알려주니 거기서 맞춰주세요.

---

## 2단계 — 룰렛 돌리는 방법 정하기

두 가지 방법이 있어요. 함께 써도 괜찮아요.

| 방법 | 난이도 | 언제 쓸까요 |
|---|---|---|
| **① 후원 감지** | ⭐ 가장 쉬움 | 후원 이벤트, 벌칙 룰렛 — **보통 이것만 써도 됩니다** |
| ② 채팅 명령어 | 보통 | 무료로 누구나 돌리게 할 때 |

이와 별개로 **사용권**이 있는데, 이건 룰렛을 돌리는 방법이 아니라
[이미 당첨된 보상을 나중에 받게 하는 방법](#사용권--당첨-보상을-나중에-받게-하기-베타)입니다.

---

## ① 후원 감지 — 가장 쉬운 방법 (권장)

**"룰렛 금액에 맞는 후원 감지시 즉발"** 스위치가 켜져 있는지만 확인해보세요 (새 룰렛은 기본으로 켜져 있어요). 명령어를 만들 필요가 없어요.

![후원 감지 스위치 위치](/static/docs/roulette/roul-03-donation.png)

이제 시청자가 **1,000치즈**를 후원하면 룰렛이 1번 돌아가요.

**금액이 '정확히' 일치해야 해요**

룰렛 금액이 1,000치즈면 **정확히 1,000치즈**를 후원해야 발동해요.

**1,500치즈를 후원하면 아무 일도 일어나지 않아요.** "1,000치즈 이상"이 아니라 "정확히 1,000치즈"예요. 여러 금액을 받고 싶다면 아래 **연차 설정**을 쓰세요.

### 같은 금액으로 여러 룰렛을 쓰고 싶다면 — 감지 키워드

- **"후원과 함께 키워드 감지"** 를 켜고 **룰렛 감지 키워드**를 정하면, 후원 메시지에 그 단어가 있을 때만 이 룰렛이 돌아가요.
- **"시청자 페이지에 키워드 공개"** 를 켜면 시청자가 어떤 단어를 써야 하는지 볼 수 있어요.

**참고**

잠금이 **후원 감지 → 키워드 감지 → 키워드 공개** 순으로 풀립니다.
후원 감지만 켜면 "후원과 함께 키워드 감지" 까지 열리고, **룰렛 감지 키워드** 입력칸과
"시청자 페이지에 키워드 공개" 는 키워드 감지까지 켜야 풀려요. 키워드 감지를 켜면 공개는 자동으로 함께 켜집니다.

### 한 번 돌린 결과를 채팅에도 나타내기

**"한 개만 돌아가도 채팅으로 알림"** 을 켜면 1번만 돌아가도 결과가 채팅에 나와요.

### 어떤 후원까지 인식할지 정하기

채팅창에 안 보이는 후원도 감지하고 싶으면, **매니저 이상**이 채팅에 입력하세요.

`!설정 룰렛 후원감지 모두`

| 값 | 동작 |
|---|---|
| **채팅** (기본값) | 채팅창에 올라온 후원만 인식 |
| **모두** | 모든 후원을 인식 |

**팁**

"후원했는데 룰렛이 안 돌아가요"가 계속된다면 이 설정을 **모두**로 바꿔보세요. 그래도 안 되면 뚜봇에게 **채널 관리자 권한**을 주시는 게 가장 확실해요.

---

## 연차 — 많이 후원하면 여러 번 돌리기

"1,000치즈에 1번인데, 10,000치즈 후원하면 10번 돌려주고 싶다" — 이럴 때 씁니다. 후원 감지를 켜야 사용해요.

**연차는 뚜봇만 작동 중일 때 쓸 수 있어요**

자동 연차를 켜거나 수동 연차를 하나라도 추가하면, 저장할 때 다른 봇이 있는지 검사해요.
최근에 타 봇이 감지된 채널은 저장이 거부되고 그 이유를 알려줘요.

**저장에 성공한 뒤에도 안전하지 않아요.** 방송 중이 아니어도, 채팅에서 타 봇이 감지되면 그 시점에
**이 채널의 모든 룰렛에서 자동 연차가 꺼지고 수동 연차 항목이 전부 삭제돼요.**
삭제는 바로 저장되어 되돌릴 수 없고, 봇을 다시 켜도 살아나지 않아요.

이때 채팅으로 알려줘요.

> 타 봇이 감지되어, 일부 기능이 비활성화됩니다.
> - 룰렛 자동 연차 기능이 비활성화되었습니다.
> - 룰렛 연차 기능이 비활성화되었습니다.

연차를 쓰지 않으면 이 검사는 걸리지 않아요.

![연차 설정 영역](/static/docs/roulette/roul-08-chain.png)

### 자동 연차 — 최소·최대만 정하면 끝

**"자동 연차 기능"** 을 켜고 최소 / 최대 횟수만 정하세요.

룰렛 금액 1,000치즈 + 자동 연차 **1~10** 인 경우:

| 후원 금액 | 결과 |
|---:|---|
| 1,000치즈 | 1번 |
| 2,000치즈 | 2번 |
| 5,000치즈 | 5번 |
| 10,000치즈 | 10번 |
| **2,500치즈** | ❌ **아무 일도 안 일어남** |
| **11,000치즈** | ❌ **아무 일도 안 일어남** |

**자동 연차가 안 되는 두 가지 경우**

**1. 나누어떨어지지 않을 때** — 후원 금액이 룰렛 금액의 정확한 배수여야 해요. 1,000치즈 룰렛에 2,500치즈는 2.5배라서 발동하지 않아요.

**2. 최소~최대 범위를 벗어날 때** — 1~10으로 설정했으면 11배(11,000치즈)는 범위 밖이라 발동하지 않아요. 큰 금액도 받으려면 최대 횟수를 올리거나 아래 **수동 연차**로 따로 등록하세요.

### 수동 연차 — 특정 금액에 원하는 횟수 지정

연차 설정에서 **추가** 버튼을 눌러 `감지 금액`과 `횟수`를 직접 넣어요.
감지 금액은 **룰렛 금액보다 커야** 하고, 횟수는 **2~3000회** 여야 해요. 벗어나면 저장이 `잘못된 값이 입력되었습니다. 연차 설정을 확인해주세요` 로 튕겨요. 배수 규칙을 무시할 수 있어요.

- 10,000치즈 → **11번** (보너스 1번 더!)
- 3,000치즈 → 5번 (이벤트 프로모션)
- 2,500치즈 → 2번 (배수가 아니어도 OK)

### 어느 쪽이 먼저 적용되나요?

같은 금액에 여러 설정이 겹치면 **위에서부터** 검사해요.

  1. **룰렛 금액과 정확히 같은가?**

→ **1번** 돌립니다.

  2. **수동 연차에 등록된 금액인가?**

→ 등록한 **횟수만큼** 돌립니다.

  3. **자동 연차 조건에 맞는가?**

→ **배수만큼** 돌립니다.

  4. **어디에도 안 맞으면**

→ 아무 일도 일어나지 않아요.

**수동이 자동을 이깁니다**

1,000치즈 룰렛 + 자동 연차 1~10이면 10,000치즈는 원래 10번이에요.

여기에 **수동 연차로 "10,000치즈 → 11번"** 을 등록하면 수동이 먼저 검사되므로 **11번**이 돼요. 큰 후원에 보너스를 줄 때 이렇게 쓰세요.

---

## ② 채팅 명령어로 돌리기

후원 없이 채팅만으로 돌리게 하려면 명령어를 만들어요.

**룰렛 필요 권한이 안 걸려요**

이 경로는 룰렛 설정의 **필요 권한을 검사하지 않아요.** 제한하려면 만든 명령어의
**필요 권한**을 대시보드에서 올려주세요.

`!추가 [명령어] $roulette:룰렛ID`

| 만드는 명령 | 시청자 입력 | 결과 |
|---|---|---|
| `!추가 !룰렛 $roulette:550e8400-e29b-41d4-a716-446655440000` | `!룰렛` | 1번 |
| `!추가 !10연차 $roulette:550e8400-e29b-41d4-a716-446655440000\|10` | `!10연차` | 10번 |

**룰렛 ID는 어디서 보나요**

룰렛 ID는 만들 때 **자동으로 생성되는 UUID** 라서 직접 정할 수 없어요.
룰렛 목록의 각 카드에서 복사해 쓰세요.

명령어 이름(`!룰렛`, `!뽑기`, `!가챠` 등)은 자유롭게 지으시면 돼요.

---

## 사용권 — 당첨 보상을 나중에 받게 하기 베타

**베타 기능이에요**

사용권은 아직 **베타 단계**로, 권한이 부여된 채널에서만 설정 화면이 보여요. 사용을 원하시면 디스코드로 문의해주세요.

사용권은 룰렛을 **돌리는** 방법이 아니라, 이미 당첨된 보상을 **나중에 받게** 하는 방법이에요.

사용권을 쓰면 룰렛이 다시 돌아가지 않아요. 발급 시점에 얼려둔 그 항목의 보상이 그대로 실행돼요.
당첨은 이미 끝났고, 실행 시점만 시청자가 고르는 셈이에요.

기본값은 **승인 필요**라서, 시청자가 사용권을 써도 스트리머가 승인해야 보상이 실행돼요.
자동 승인으로 바꾸면 바로 실행돼요.

- **아이템 표의 '설정' 칸**에 항목별 **사용권** 스위치가 있어요. 켜면 그 항목에 당첨될 때 사용권이 지급돼요.
  스위치 옆 드롭다운에서 승인 방식(채널 기본 / 즉시 처리 / 승인 필요)을 고를 수 있고, 사용권을 켜면 같은 칸의 '기록/자동 사용' 은 자동으로 꺼지고 잠겨요.

왼쪽 메뉴의 **사용권** 화면에서 아래 두 가지를 쓸 수 있어요. **스트리머 본인만** 가능해요.

- **사용권 지급** — 룰렛을 돌리지 않고 특정 시청자에게 바로 지급 (이벤트 보상 등)
- **일괄 만료** — 발급된 사용권을 한 번에 만료

**일괄 만료는 되돌릴 수 없어요**

**이 룰렛만이 아니라 채널 전체의 사용권**이 대상이에요. '사용 가능'·'승인 대기' 상태의 모든 사용권이 만료되며 **복구할 수 없어요.**

---

## 남용 막기 — 제한 설정

**"룰렛에 제한 걸기"** 를 켜면 네 가지 제한을 걸 수 있어요.

![룰렛 제한 설정 네 가지 항목](/static/docs/roulette/roul-04-limit.png)

| 항목 | 설명 |
|---|---|
| **이 룰렛은 총 N회까지만** | 누적 총 횟수 |
| **이 룰렛은 하루에 N회까지만** | 하루에 돌 수 있는 횟수 |
| **시청자당 하루에 N회까지만** | 한 사람이 하루에 돌릴 수 있는 횟수 |
| **이 룰렛은 (날짜)까지만** | 종료 기한. 그 날 0시부터 돌지 않으니, 마지막으로 돌아가는 날은 전날이에요 |

**-1은 '제한 없음'입니다**

기본값 `-1`은 제한이 없다는 뜻이에요. 제한할 항목에만 숫자를 넣으세요.

**팁**

경품이 걸린 룰렛이라면 한 사람이 독식하지 않도록 **시청자당 하루 횟수**를 걸어두세요. 기간 이벤트라면 **종료 날짜**도 함께 넣어두면 깜빡하는 일을 막을 수 있어요.

---

## 항목 고급 설정

### 당첨 결과를 바로 '처리 완료' 로 둘지 정하기

**기록을 켜고 끄는 스위치가 아니에요**

**당첨 결과는 이 스위치와 상관없이 항상 룰렛 기록에 남아요.**

**기록/자동 사용** 이 정하는 건 그 기록의 처리 상태예요.

| 설정 | 당첨되면 |
|---|---|
| **켜짐** | 곧바로 처리 완료로 들어가요. 리모콘 처리 목록에 안 뜹니다 |
| **꺼짐** | **'미사용'** 으로 남아요. 대시보드 → 리모콘에서 하나씩 처리 표시할 수 있어요 (최근 7일치만 보여줘요) |

그래서 **"나중에 이행해야 하는" 벌칙이나 경품은 오히려 꺼둬야** 해요.

한 번 처리 완료로 넘긴 당첨도 다시 **미사용**으로 되돌릴 수 있어요.
다만 사용권이 아직 살아 있는 당첨은 사용권 쪽이 상태를 정하기 때문에 되돌려지지 않고 조용히 건너뜁니다.
켜두면 챙기기도 전에 이미 준 것으로 처리돼요.

바로 끝나는 항목(그 자리에서 웃고 넘어가는 벌칙 등)에만 켜세요.
사용권을 켠 항목은 이 스위치가 잠깁니다.

### 카운터 · 타이머 연동

당첨되면 **카운터나 타이머를 자동으로 조작**할 수 있어요.

**카운터 연동**

| 항목 | 설명 |
|---|---|
| 대상 카운터 | 조작할 카운터 이름 |
| 조작 대상 | `값`(현재값) 또는 `목표` |
| 연산 | 증가 / 감소 / 곱하기 / 나누기 / 초기화 |
| 값 | 연산에 쓸 숫자 |

**타이머 연동**

| 항목 | 설명 |
|---|---|
| 대상 타이머 | 조작할 타이머 제목 |
| 연산 | 추가 / 감소 |
| 시간 | 숫자 + 단위(초 / 분 / 시간). 기본 60초 |

**이렇게 쓰면 좋아요**

- **"방송 연장 10분"** 항목 → 타이머에 +600초
- **"데스 카운트 +1"** 항목 → 카운터 현재값에 +1
- **"목표 달성"** 항목 → 카운터 초기화

---

## 채팅에 나가는 결과 문구

당첨되면 봇이 **항목 이름을 모아서** 한 줄로 보내요.

```
룰렛 결과: 대성공, 실패 2개
```

같은 항목이 여러 번 나오면 `이름 N개` 로 묶여요.

**항목마다 다른 문구를 정할 수는 없어요**

문구 형식은 위 한 가지로 고정이에요. 항목별로 메시지를 따로 지정하거나
당첨자 닉네임을 넣는 기능은 없어요.

당첨자가 누구인지는 **룰렛 오버레이 화면**과 대시보드의 **룰렛 기록**에서 확인할 수 있어요.

---

## 방송 화면에 띄우기 (오버레이)

룰렛이 돌아가는 모습을 방송에 보여주려면 오버레이를 추가해야 해요.

- **오버레이 주소** — 돌아가는 애니메이션과 당첨 결과
- **최근 결과 오버레이 주소** — 최근 당첨 내역 목록. 띄운 이후부터 집계되고, 새로고침하면 초기화돼요.
  아직 처리하지 않은(미사용) 당첨만 올라와요 — **기록/자동 사용**을 켠 항목은 여기 뜨지 않습니다

둘 다 **룰렛 오버레이 설정** 한 페이지 안에 주소가 나란히 있어요.

대시보드에서 오버레이 주소를 복사해 **OBS의 브라우저 소스**로 추가하세요.
**룰렛 회전 시간**(1~10초)은 룰렛 편집 화면에서 조절해요.

### 룰렛 오버레이 설정 페이지 항목

| 설정 | 설명 |
|---|---|
| **알림 볼륨** | 룰렛이 뜰 때 나는 소리 크기 |
| **틱(돌아갈 때) 볼륨** | 돌아가는 동안 나는 소리 크기 |
| **결과 볼륨** | 당첨 결과가 나올 때 소리 크기 |
| **타입** | **슬롯머신**(돌아가는 애니메이션) 또는 **즉시 공개**(애니메이션 없이 결과만) |
| **표시 형식** | 룰렛 위에 뜨는 후원자·금액 안내 줄. 기본값 `$nick 님이 $price 후원!` — `$nick`(후원자 닉네임)과 `$price`(치즈 아이콘 + 금액)만 치환돼요. 당첨 항목 이름은 넣을 수 없어요 |
| **최근 결과 표시 형식 (1)** | 최근 결과 오버레이의 사람별 줄. 기본값 `🎲 {nick}님 🎲` |
| **최근 결과 표시 형식 (2)** | 그 아래 항목 줄. 기본값 ` └  {rouletteResult}: {rouletteCount} 개` |
| **TTS 사용** | 켜면 당첨 결과를 음성으로 읽어줘요 |
| **제공자** | **로컬** 또는 **구글 TTS**. 볼륨·피치·속도를 어느 묶음에서 읽을지 고릅니다 |
| **읽기 형식** | 읽어줄 문장 틀 |
| **무시할 접두사** | 이 글자로 시작하면 안 읽어요 |
| **볼륨 · 피치 · 속도** | 제공자별로 따로 저장돼요 |

**타입**을 '즉시 공개' 로 두면 돌아가는 애니메이션 자체가 나오지 않아요.

[오버레이 설정 방법 자세히 보기 →](/docs/features/overlay)

---

## 이렇게 만들어보세요

### 벌칙 룰렛 (1,000치즈)

| 항목 이름 | 확률 |
|---|---:|
| 노래 한 곡 | 25% |
| 댄스 타임 | 25% |
| 먹방 | 25% |
| 면제 | 25% |

**합계 100%** ✅ · 자동 연차 1~10을 켜두면 5,000치즈 후원 시 5번 돌아가요.

### 게임 결과 룰렛

| 항목 이름 | 확률 |
|---|---:|
| 대성공 | 5% |
| 성공 | 30% |
| 실패 | 50% |
| 대실패 | 15% |

**합계 100%** ✅

### 선물 룰렛

| 항목 이름 | 확률 |
|---|---:|
| 1등 | 1% |
| 2등 | 9% |
| 3등 | 20% |
| 꽝 | 70% |

**합계 100%** ✅ · 1~3등은 **기록/자동 사용을 꺼두세요.** 그래야 '미사용' 으로 남아서 경품을 줬는지 추적할 수 있어요.

---

## 문제 해결

### 룰렛이 아예 반응하지 않아요

위에서부터 순서대로 확인해보세요.

| 확인할 것 | 해결 |
|---|---|
| **후원 금액이 가려져 있는가?** | **가장 흔한 원인.** 가려두면 봇에게 **0원**으로 들어와 금액이 안 맞아요. 치지직에서 후원 금액을 공개하거나 뚜봇에게 채널 관리자 권한을 주세요 |
| **후원감지가 '채팅'으로 되어 있는가?** | `!설정 룰렛 후원감지 모두` 로 바꿔보세요 |
| 저장은 눌렀는가? | 설정만 바꾸고 저장을 안 누르면 반영되지 않아요 |
| 룰렛 스위치가 켜져 있는가? | 목록에서 해당 룰렛의 스위치를 확인해보세요 |
| **룰렛 오버레이를 OBS에 추가했는가?** | **오버레이가 없으면 채팅 결과도 안 나가요.** 오버레이가 결과를 표시한 뒤 서버에 알려야 봇이 채팅을 보내요 |
| 방송 중인가? | **방송이 꺼져 있으면 후원 룰렛은 아예 돌지 않아요** — 오버레이도 당첨 기록도 남지 않습니다. (`$roulette:` 명령어와 목록의 테스트 버튼은 방송이 꺼져 있어도 돌아가고, 이때는 채팅 결과만 안 나가요) |
| 당첨이 하나뿐인가? | 항목이 1개만 당첨되면 **"한 개만 돌아가도 채팅으로 알림"** 을 켜야 채팅에 나가요 |
| 후원 금액이 정확히 일치하는가? | 1,000치즈 룰렛에 1,500치즈는 발동하지 않아요 |
| 자동 연차가 배수인가? | 1,000치즈 룰렛에 2,500치즈는 배수가 아니에요 |
| 자동 연차 범위 안인가? | 1~10 설정에 11배는 범위를 벗어나요 |
| 권한이 맞는가? | '구독자 이상'인데 비구독자가 시도했을 수 있어요 (후원 감지로 돌릴 때만 해당 — `$roulette:` 명령어에는 안 걸려요) |
| 제한에 걸렸는가? | 하루 횟수·총 횟수·종료 날짜를 확인해보세요 |

### 특정 항목이 잘 안 나와요

확률이 낮게 설정돼 있는지 확인해보세요. 확률이 의도대로 나오는지 궁금하다면 **시뮬레이션** 버튼으로 1,000번 돌려본 결과를 확인할 수 있어요.

### 당첨자가 '익명'으로만 남아요

익명 후원은 뚜봇이 누구인지 알 수 없어요. 뚜봇에게 **채널 관리자 권한**을 주면 기록에 표시할 수 있어요.

### 명령어 사용 시 오류 메시지

| 응답 | 원인 |
|---|---|
| `오류: 해당 룰렛을 찾을 수 없습니다.` | 룰렛 ID가 틀렸거나, 삭제됐거나, **목록에서 스위치가 꺼져 있습니다** |
| `오류: 룰렛을 돌릴 횟수는 숫자여야 합니다.` | `$roulette:ID\|횟수`의 횟수가 숫자가 아니에요 |
| `오류: 룰렛을 돌릴 횟수는 1 이상이어야 합니다.` | 횟수를 1 이상으로 지정하세요 |

---

## 다음 단계

[오버레이 설정 →](/docs/features/overlay) · [가위바위보 →](/docs/features/rock-paper-scissors) · [게임 전적·티어 →](/docs/features/game-tier)

**더 궁금한 점이 있나요?**

  [디스코드](https://discord.com/invite/QftHRJCTPZ)에서 편하게 문의해주세요!

---

# 단축 링크

출처: https://chzzk-bot.ddutto.com/docs/features/short-link
설명: 긴 주소를 ddu.to 짧은 주소로 줄이는 방법. 채팅 명령어에 넣기 좋은 형태로 만들 수 있어요.

긴 주소를 `https://ddu.to/xxxxxxxx` 형태로 줄여줘요.

봇이 **공식 API로** 보내는 채팅은 95자까지만 나가요. 긴 주소를 그대로 넣으면 뒤 내용이 잘릴 수 있어요.

---

## 만드는 방법

  1. **설정 페이지 열기**

대시보드 왼쪽 메뉴에서 **설정** 을 누르고, **단축 링크** 항목을 찾아요.

  2. **링크 추가**

**링크 추가** 버튼을 누르고 줄이려는 주소를 붙여넣어요.

  3. **생성**

**생성** 을 누르면 `https://ddu.to/` 로 시작하는 주소가 만들어집니다.
목록에서 바로 확인할 수 있어요.

**https 주소만 돼요**

`http://` 로 시작하는 주소는 `링크가 잘못 입력되었습니다.` 가 나와요. `https://` 인지 확인해보세요.

---

## 알아둘 것

| 항목 | 내용 |
|---|---|
| **개수 제한** | 채널당 **10개** |
| **주소 형식** | `https://ddu.to/` + 8글자 |
| **주소 지정** | **불가능.** 주소는 원본 링크로부터 자동 생성돼요 |
| **같은 링크 재등록** | 불가능. 이미 등록한 주소를 또 넣으면 거부돼요 |
| **수정** | 불가능. 지우고 다시 만들어야 해요 |

**같은 주소를 줄이면 항상 같은 링크가 나와요**

단축 주소는 원본 링크를 계산해서 만들기 때문에, 같은 원본이면 언제 만들어도 같은 주소가 나와요.
그래서 `ddu.to/내채널` 처럼 **원하는 단어로 지정할 수는 없어요.**

---

## 명령어에 넣기 — 95자 제한 때문에 필요해요

봇이 **공식 API로** 보내는 채팅은 95자까지만 나가요. 넘으면 뒤가 잘린 상태로 전송돼요.
(공식 API를 연동하지 않은 채널이나, 치지직 이모티콘이 들어간 응답은 다른 경로로 나가서 이 제한을 받지 않아요)

길이가 긴 주소가 이 공간을 많이 차지해요.

| 넣는 주소 | 길이 | 남는 글자 |
|---|---:|---:|
| `https://chzzk.naver.com/4c3a50fe635854036b4dcf15c9a4d0a2/community/detail/9745642` | **81자** | 14자 |
| `https://ddu.to/1a2b3c4d` | **23자** | 72자 |

같은 주소인데도 **72자**가 남아요. 원본을 쓸 때보다 58자를 더 확보하는 셈이라, 안내 문구를 충분히 붙일 수 있어요.

`!추가 !디코 디스코드는 여기로 오세요! https://ddu.to/1a2b3c4d`

**이모지는 2자로 계산돼요**

글자 수는 화면에 보이는 개수가 아니라 UTF-16 단위로 세어집니다.
한글·영문·숫자는 1자지만 이모지는 최소 2자예요. 국기(🇰🇷)는 4자, 가족(👨‍👩‍👧‍👦)처럼 여러 조각이 합쳐진 이모지는 11자까지도 먹습니다. 이모지를 많이 넣으면 생각보다 빨리 잘릴 수 있어요.

[커스텀 명령어 만들기 →](/docs/commands/custom)

---

## 지우기

목록에서 해당 줄의 **삭제** 버튼을 누르면 삭제돼요. 지운 주소로 접속하면 `링크를 찾을 수 없습니다.` 가 표시돼요.

**지우면 되살릴 수 없어요**

이미 방송이나 커뮤니티에 공유한 주소를 지우면 그 링크는 더 이상 작동하지 않아요.
명령어에 들어가 있다면 명령어도 함께 수정해주세요.

---

## 오버레이 주소에는 쓰지 마세요

**🚨 단축해도 보안이 보장되지 않아요**

오버레이 주소를 단축 링크로 만들어도 주소를 아는 사람은 열어볼 수 있어요.
단축은 글자 수를 줄일 뿐 접근 제한은 하지 못해요.

오버레이 주소는 OBS에만 넣고 어디에도 공개하지 마세요.
[오버레이 문서 →](/docs/features/overlay)

---

## 다음 단계

[커스텀 명령어 →](/docs/commands/custom) · [기본 명령어 →](/docs/commands/basic)

**더 궁금한 점이 있나요?**

  [디스코드](https://discord.com/invite/QftHRJCTPZ)에서 편하게 문의해주세요!

---

# 신청곡

출처: https://chzzk-bot.ddutto.com/docs/features/song-request
설명: 치지직 뚜봇으로 시청자 노래 신청을 받는 방법. 명령어 만들기, 변수, 플레이어·목록 오버레이 설정까지 안내해요.

시청자들이 유튜브에서 노래를 검색해서 신청할 수 있어요. 변수를 사용해 나만의 명령어를 만들 수 있어요.

**참고**

신청곡은 **기본적으로 열려 있어요.** 한 번도 손대지 않은 채널이라면 시청자가 바로 신청할 수 있어요.
닫으려면 대시보드에서 **'신청곡 열림 여부'** 토글을 끄거나, 만들어둔 신청곡 명령어 뒤에 `닫기` 를 붙이세요 (`!신청 닫기`).

**대부분 방송 중에만 가능**

신청곡 변수는 대부분 방송 중에만 동작해요. 예외가 둘 있어요.

- `$song-remaining-limit-per-user` · `$song-remaining-limit-total` 은 방송 여부를 보지 않아요.
- **스트리머 본인**은 방송이 꺼져 있어도 신청할 수 있어요 (신청 경로만 매니저까지 방송 검사를 받아요. 조회·스킵은 스트리머도 방송 중에만 돼요).

---

## 신청곡 명령어 만들기

신청곡 기능을 사용하려면 `$song-requests` 변수를 사용해요.

```
!추가 [원하는명령어] $song-requests
```

**명령어 이름은 자유롭게!**

`!sr`, `!노래신청`, `!신청` 등 원하는 이름으로 만들 수 있어요!

**예시:**
- `!추가 !sr $song-requests` → `!sr 노래제목`으로 신청
- `!추가 !노래신청 $song-requests` → `!노래신청 노래제목`으로 신청
- `!추가 !신청 $song-requests` → `!신청 노래제목`으로 신청

---

## 신청곡 변수

### $song-requests - 신청곡 기능

- $song-requests — 신청곡 기능을 활성화해요. 시청자가 검색어나 URL로 노래를 신청할 수 있어요. / 예: !추가 !sr $song-requests / 입력: !sr 린 Overdose / 출력: 신청이 완료되었습니다: Overdose (なとり) / 아오쿠모 린 (Aokumo Rin) Cover

---

### $song-current - 현재 곡

- $song-current — 현재 재생 중인 곡 제목을 출력해요. / 예: !추가 !지금 신청곡: $song-current / 입력: !지금 / 출력: 신청곡: 첫사랑 ( 백아 ) / 아라하시 타비 Cover

---

### $song-link - 현재 곡 링크

- $song-link — 현재 재생 중인 곡의 유튜브 링크를 출력해요. / 예: !추가 !링크 $song-link / 입력: !링크 / 출력: https://youtu.be/HBoqsgRoDw4

---

### $song-next - 다음 곡

- $song-next — 다음에 재생될 곡 제목을 출력해요. / 예: !추가 !다음곡 다음곡: $song-next / 입력: !다음곡 / 출력: 다음곡: Overdose (なとり) / 아오쿠모 린 (Aokumo Rin) Cover

---

### $song-count - 남은 곡 수

- $song-count — 대기열에 남은 곡 수를 출력해요. / 예: !추가 !대기 남은 곡: $song-count / 입력: !대기 / 출력: 남은 곡: 5개 / (값에 이미 `개` 가 붙어 나와요. 뒤에 `곡` 을 붙이면 `5개곡` 이 돼요.)

---

## 예시: 종합 신청곡 정보

여러 변수를 조합해서 자세한 정보를 보여줄 수 있어요!

```
!추가 !노래 신청곡: $song-current ($song-link) / $song-count 남음.
```

**결과**: `신청곡: 첫사랑 ( 백아 ) / 아라하시 타비 Cover (https://youtu.be/HBoqsgRoDw4) / 2개 남음.`

---

## 신청곡 설정하기

대시보드 **신청곡** 페이지는 이렇게 생겼어요.

![대시보드 신청곡 — 플레이어와 대기열](/static/docs/song-request/song-01-queue.png)

| 화면 | 하는 일 |
|---|---|
| 왼쪽 **플레이어** | 지금 재생 중인 곡. 아래에 제목·신청자가 표시돼요 |
| 오른쪽 **대기열** | 신청된 순서. 각 곡의 `삭제` 로 개별 제거 |
| **신청곡 열림 여부** | 이걸 켜야 시청자가 신청할 수 있어요 |
| **영상이 끝났을 때, 자동 스킵** | 곡이 끝나면 다음 곡으로 자동 이동 |
| **오류 발생시, 자동 스킵** | 재생 불가한 영상을 자동으로 건너뛰어요 |
| **전체 삭제** | 대기열을 통째로 비워요 |

  1. **대시보드 접속**

뚜봇 대시보드에 로그인하세요.

  2. **신청곡 메뉴**

좌측 메뉴에서 **'신청곡'** 을 클릭해요.

  3. **기능 활성화**

**'신청곡 열림 여부'** 토글을 켜세요. 꺼져 있으면 시청자가 신청할 수 없어요.

  4. **제한값은 채팅 명령으로**

대시보드에는 제한값 입력칸이 없어요. 아래 명령을 방송 채팅창에 입력하세요.

- `!설정 신청곡 전체갯수제한 <개수>` — 대기열에 쌓일 수 있는 전체 곡 수
- `!설정 신청곡 유저제한 <개수>` — 한 사람이 대기열에 동시에 올려둘 수 있는 곡 수 (최대 100)
- `!설정 신청곡 길이제한 <시간(초)>` — 신청 가능한 영상 길이. **분이 아니라 초입니다**
- `!설정 신청곡 중복제한 <개수>` — 같은 영상이 대기열에 동시에 들어갈 수 있는 개수

**전체갯수·유저·중복** 세 제한은 **대기열 기준**이에요. 곡이 재생을 마치면 자리가 비어서 같은 사람도, 같은 영상도 다시 신청할 수 있어요. (길이제한은 대기열과 무관하게 영상 자체의 재생 시간을 봐요.)

앞의 셋은 `-1` 을 넣으면 무제한이 돼요. **중복제한만 다릅니다** — `-1` 은 거부되고(`0보다 큰 숫자로 입력해주세요.`), 끄려면 `0` 을 넣으세요.

값 없이 치면 현재 설정을 알려줘요.

**참고**

대시보드에서 켜고 끌 수 있는 건 신청곡 열림 여부 · 유튜브 로그인 사용 · 자동 스킵(영상 종료 / 오류 발생) 입니다.
이 페이지에서는 설정을 바꾼 뒤 따로 '저장' 을 누를 필요가 없어요.

자동 스킵 2종은 이 브라우저에만 저장돼요. 다른 PC·다른 브라우저에서는 기본값(영상 종료=켬, 오류 발생=끔)으로 돌아가요.
이 두 토글은 **대시보드 플레이어에만** 적용돼요. OBS 로 띄운 오버레이는 곡이 끝나거나 오류가 나면 항상 다음 곡으로 넘어갑니다.

다만 **'유튜브 로그인 사용'** 은 아예 저장되지 않아요. 이 브라우저에서만 켜지고 새로고침하면 다시 꺼지며, 오버레이에는 적용되지 않아요.
켜면 로그인된 유튜브 계정의 시청 기록과 추천이 신청곡으로 오염될 수 있어요 — 대시보드에서도 켤 때 같은 경고가 뜹니다.

---

## 관리용 변수

신청곡을 관리하는 변수예요. 명령어로 만들어 쓸 수 있어요.

### $song-skip - 곡 스킵

- $song-skip — 현재 재생 중인 곡을 건너뛰어요. / 예: !추가 !스킵 $song-skip / 입력: 마지막남은뚜또: !스킵 / 출력: '첫사랑 ( 백아 ) / 아라하시 타비 Cover' 노래를 스킵했습니다.

---

### $song-time - 현재 곡 길이

- $song-time — 현재 재생 중인 곡의 길이를 출력해요. / 예: !추가 !곡길이 현재 곡 길이: $song-time / 입력: 마지막남은뚜또: !곡길이 / 출력: 현재 곡 길이: 03:42

---

### $song-total-time - 전체 대기열 길이

- $song-total-time — 대기열에 있는 모든 곡의 총 길이를 출력해요. / 예: !추가 !총길이 남은 신청곡 길이: $song-total-time / 입력: 마지막남은뚜또: !총길이 / 출력: 남은 신청곡 길이: 15:30

---

### $song-remaining-limit-per-user - 개인 남은 신청 횟수

- $song-remaining-limit-per-user — 내가 추가로 신청할 수 있는 곡 수를 출력해요. / 예: !추가 !남은신청 남은 신청 가능: $song-remaining-limit-per-user곡 / 입력: 마지막남은뚜또: !남은신청 / 출력: 남은 신청 가능: 2곡 / (1인당 제한을 설정하지 않았거나 무제한(-1)이면 개수 대신 `-1` 이 나와요.)

---

### $song-remaining-limit-total - 전체 남은 신청 가능 수

- $song-remaining-limit-total — 대기열에 추가로 들어갈 수 있는 곡 수를 출력해요. / 예: !추가 !대기열여유 대기열 여유: $song-remaining-limit-total곡 / 입력: 마지막남은뚜또: !대기열여유 / 출력: 대기열 여유: 15곡 / (전체갯수제한을 설정하지 않았거나 무제한(-1)이면 곡 수 대신 `-1` 이 나와요.)

---

## 관리 명령어 예시

관리용 명령어를 만들어 쓸 수 있어요.

### 곡 스킵 명령어

```
!추가 !스킵 $song-skip
```

이제 `!스킵` 을 치면 현재 곡이 건너뛰어져요.

**기본 권한은 '시청자'입니다**

`!추가` 로 만든 명령어는 **누구나 쓸 수 있는 상태로 만들어집니다.** 이대로 두면
시청자 아무나 재생 중인 곡을 넘길 수 있어요.

매니저만 쓰게 하려면 대시보드 좌측 **뚜봇 관리 → 유저 명령어** 에서 `!스킵` 을 수정하고,
**필요 권한** 을 **매니저** 로 바꿔주세요.

---

### 신청곡 정보 명령어

```
!추가 !신청곡 🎵 $song-current | 다음: $song-next | 남은 곡: $song-count
```

현재 재생 중인 곡과 다음 곡, 남은 곡 수를 한 번에 확인할 수 있어요.

---

### 신청 가능 여부 확인

```
!추가 !신청가능 대기열 여유: $song-remaining-limit-total곡 / 내 남은 신청: $song-remaining-limit-per-user곡
```

---

## 에러 응답

| 상황 | 응답 |
|------|------|
| 신청곡이 닫혀 있음 | **아무 응답도 하지 않습니다** |
| 전체 대기열 초과 | `오류: 이 채널은 최대 20개 까지만 신청 가능합니다.` |
| 개인 신청 제한 초과 | `오류: 한 사람당 최대 3개 까지만 신청 가능합니다.` |
| 중복 신청 초과 | `오류: 같은 영상은 최대 1개 까지만 신청 가능합니다.` |
| 곡 길이 초과 | `오류: 300초 이상의 영상은 신청할 수 없습니다.` |
| 검색 결과 없음 | `오류: 유튜브 검색 결과가 없거나, 찾지 못했습니다.` |

숫자 부분에는 실제로 설정한 제한값이 들어가요.

### 방송이 꺼져 있을 때

무엇을 하려 했느냐에 따라 문구가 다릅니다.

| 하려던 것 | 응답 |
|------|------|
| 신청 | `방송중이 아닙니다. 신청은 방송 중에만 가능합니다.` |
| 조회 (`$song-current` 등) | `방송중이 아닙니다. 조회는 방송 중에만 가능합니다.` |
| 스킵 (`$song-skip`) | `방송중이 아닙니다. 스킵은 방송 중에만 가능합니다.` |

### 곡이 없을 때

| 변수 | 응답 |
|------|------|
| `$song-current` · `$song-link` · `$song-time` · `$song-total-time` | `재생중인 노래가 없습니다.` |
| `$song-skip` | `재생중인 곡이 없습니다.` |
| `$song-next` | `다음곡이 없습니다.` |

---

## 방송 화면에 띄우기 (오버레이)

신청곡은 오버레이가 **두 개**입니다. 대시보드 **오버레이 관리 → 신청곡**에서 둘 다 받을 수 있어요.

| 오버레이 | 무엇을 보여주나 | 꼭 필요한가 |
|---|---|---|
| **신청곡 (플레이어)** | 노래를 실제로 **재생**해요 | ✅ **필수** |
| **신청곡 목록** | 대기 중인 곡 목록을 표시해요 | 선택 |

**🚨 플레이어 오버레이가 없으면 노래가 재생되지 않아요**

신청만 받고 소리가 안 난다면 대부분 이 오버레이를 OBS에 추가하지 않아서예요.

**신청곡(플레이어) 오버레이를 반드시 OBS에 넣어주세요.**

### OBS에 추가하기

  1. **플레이어 오버레이 추가**

위쪽 **오버레이 주소**의 **주소 복사** → OBS **소스 → + → 브라우저**

소리만 나오면 되므로 크기는 **400 × 300** 정도면 충분해요. 화면 밖으로 빼두셔도 돼요.

  2. **소리 설정 확인**

브라우저 소스 속성에서 **소스를 통해 오디오 제어**를 켜주세요. 꺼져 있으면 OBS가 노래 소리를 잡지 못해요.

  3. **목록 오버레이 추가 (선택)**

아래쪽 **신청곡 목록**의 주소를 복사해 같은 방식으로 추가해요.

권장 크기는 **400 × 600** 정도예요.

### 설정 항목

| 설정 | 설명 |
|---|---|
| **오버레이 볼륨** | 노래 재생 음량 |
| **오버레이 배경** | 목록 오버레이의 배경 |
| **표기되는 노래 갯수** | 목록에 몇 곡까지 보여줄지 |
| **다크모드** | 목록 오버레이의 어두운 테마 |
| **CSS ID / 추가 CSS** | 디자인 직접 변경 |

이 표의 항목은 **신청곡 오버레이 설정 페이지**에 있어요. 값을 바꾼 뒤 페이지 제목 옆 **'저장'** 을 눌러야 반영돼요.

**미리보기에서는**

- **플레이어** — 자동 재생 안 되고 삭제도 안 돼요
- **목록** — 삭제 버튼이 눌리지 않아요

실제 방송에서는 정상이에요.

**오버레이 주소는 노출하지 마세요**

주소를 아는 사람은 누구나 열어볼 수 있어요. 방송 화면에 주소가 잡히지 않도록 주의해주세요. 확인 후 **20초 뒤 자동으로 다시 가려집니다.**

---

## 다음 단계

신청곡 설정이 완료되었다면, 시청자 참여 기능도 확인해보세요.

[시청자 참여 →](/docs/features/viewer-participation)

---

# 타이머 · 카운터

출처: https://chzzk-bot.ddutto.com/docs/features/timer-counter
설명: 방송 화면에 카운트다운 타이머와 숫자 카운터를 띄우는 방법. 명령어로 조작하고 룰렛 당첨과 연동할 수 있어요.

**화면에 시간과 숫자를 띄웁니다**

**타이머** — 카운트다운을 띄우고, 후원이 들어오면 시간을 늘릴 수 있어요. 노방종 방송에 딱이에요.

**카운터** — 데스 카운트, 목표 달성 횟수 같은 숫자를 세어 보여줄 수 있어요.

둘 다 **룰렛 당첨과 연동**해서 자동으로 조작할 수 있어요.

---

## 타이머

## 1단계 — 타이머 만들기

방송 채팅창에 입력하세요. **매니저 이상**만 사용할 수 있어요.

`!타이머 추가 30분 방송종료까지`

`30분` 자리에 원하는 시간을, `방송종료까지` 자리에 타이머 이름을 넣으세요.

### 시간 적는 법

**`시간` · `분` · `초` 를 그대로 쓰면 돼요.** 이게 제일 편해요.

| 입력 | 의미 |
|---|---|
| `30분` | 30분 |
| `2시간` (또는 `2시`) | 2시간 |
| `1시간30분` | 1시간 30분 |
| `1시간30분45초` | 1시간 30분 45초 |
| `90분` | 90분 (1시간 30분) |
| `45초` | 45초 |

**시간은 붙여 쓰세요**

`!타이머 추가` · `!타이머 수정` 은 **띄어쓰기 앞부분만** 시간으로 읽어요.

`!타이머 추가 1시간 30분 45초 방송종료까지` 라고 치면 `1시간` 만 시간이 되고,
남은 `30분 45초 방송종료까지` 가 통째로 타이머 **이름**이 돼요. 오류도 안 나요.

`1시간30분45초` 처럼 한 덩어리로 적어주세요. 중간 단위는 건너뛰어도 돼요 (`1시간45초`).
이름 없이 쓰는 `!타이머 1시간 30분 45초` 만 띄어쓰기가 허용돼요.

숫자나 콜론으로도 적을 수 있어요.

| 입력 | 의미 |
|---|---|
| `600` | **600초** — 숫자만 쓰면 초로 봅니다 |
| `1800` | 1800초 = 30분 |
| `0:30` | 30초 |
| `10:00` | 10분 |
| `1:30` | **1분 30초** (콜론이 2칸이면 `분:초`) |
| `1:30:00` | **1시간 30분** (콜론이 3칸이면 `시:분:초`) |
| `3:45:30` | 3시간 45분 30초 |

**콜론으로 적을 땐 2칸이 '분:초' 예요**

`1:30` 은 1시간 30분이 아니라 **1분 30초**예요.
1시간 30분을 원하면 `1:30:00` 처럼 **세 칸**으로 적어야 해요.

또 콜론 표기에서는 **분과 초가 0~59** 까지만 돼요. `60:00` 은 오류가 나요.
헷갈리면 그냥 **`1시간30분` 처럼 한글로 적는 게 편해요.** (한글 표기는 `90분` 도 돼요)

**'밤 10시까지' 처럼 시각으로 정하기**

앞에 `N` 을 붙이면 **그 시각까지 남은 시간**으로 타이머를 걸 수 있어요.

`!타이머 추가 N22:00:00 방송종료까지`

지금이 13시라면 9시간짜리 타이머가 만들어져요. 이미 지난 시각이면 **다음 날** 그 시각으로 잡혀요.

반드시 `N시:분:초` **세 칸의 콜론 표기**로 적으세요. `N22:00` 은 22시가 아니라 **0시 22분**으로 읽혀요.
`N22시` 처럼 한글로 적는 건 아직 지원하지 않아요.

**이름 없이 빠르게 하나만**

`!타이머 30분` 처럼 시간만 적으면 **`타이머`** 라는 이름으로 바로 만들어져요.
이미 같은 이름이 있으면 덮어써요. 잠깐 쓰고 말 때 편해요.

## 2단계 — 타이머 조작하기

| 명령어 | 하는 일 |
|---|---|
| `!타이머 목록` | 만들어둔 타이머와 남은 시간 확인 |
| `!타이머 수정 시간추가 10분 방송종료까지` | 시간 **늘리기** |
| `!타이머 수정 시간제거 5분 방송종료까지` | 시간 **줄이기** |
| `!타이머 일시정지 방송종료까지` | 잠시 멈추기 |
| `!타이머 재개 방송종료까지` | 다시 시작 |
| `!타이머 제거 방송종료까지` | 이 타이머만 삭제 |
| `!타이머 초기화` | **모든 타이머 삭제** |

**순서에 주의하세요**

`수정` 은 **시간이 먼저, 이름이 나중**이에요.

- ✅ `!타이머 수정 시간추가 10분 방송종료까지`
- ❌ `!타이머 수정 시간추가 방송종료까지 10분`

**`!타이머 초기화` 는 전부 지워요**

"처음 시간으로 되돌리기"가 아니라 **등록된 타이머를 모두 삭제**해요.
하나만 지우려면 `!타이머 제거 <이름>` 을 써요.

**이미 있는 이름으로 또 추가하면**

시간이 **덮어써지지 않고 더해져요.**
`!타이머 추가 10:00 방송종료까지` 를 두 번 치면 20분이 돼요.

## 3단계 — 타이머 화면에 띄우기

대시보드 **오버레이 관리 → 타이머**에서 **주소 복사** 후 OBS 브라우저 소스에 넣어요.

**타이머 레이아웃**을 두 가지 중에 고를 수 있어요.

| 레이아웃 | 모습 |
|---|---|
| **원형** | 동그란 게이지가 줄어들어요 |
| **시계** | 원형 게이지 없이 이름과 숫자만 표시돼요 |

권장 크기는 **400 × 400**(원형) 또는 **400 × 150**(시계) 정도예요.

---

## 카운터

## 1단계 — 카운터 만들기

`!카운터 추가 10 데스`

`10` 은 **목표 값**, `데스` 는 카운터 이름이에요.

**목표 값이 필요 없다면**

목표를 정하고 싶지 않으면 **`0`** 을 넣어요. `!카운터 추가 0 데스` 처럼요.

`!카운터 목록` 과 오버레이 '간단' 모드가 목표를 감추고 현재값만 보여줘요.
('기본' 모드는 목표가 0이어도 `0 / 0` 으로 표기해요)

`-1` 도 입력은 되지만 **'목표 없음' 으로 취급되지 않아요.** 목록에 `'데스' - 0 / -1` 처럼 그대로 나와요.

## 2단계 — 숫자 조작하기

| 명령어 | 하는 일 |
|---|---|
| `!카운터 목록` | 만들어둔 카운터 확인 |
| `!카운터 더하기 1 데스` | 현재값 **더하기** |
| `!카운터 빼기 1 데스` | 현재값 **빼기** |
| `!카운터 설정 5 데스` | 현재값을 특정 숫자로 |
| `!카운터 목표더하기 5 데스` | **목표값** 더하기 |
| `!카운터 목표빼기 5 데스` | 목표값 빼기 |
| `!카운터 목표설정 20 데스` | 목표값을 특정 숫자로 |
| `!카운터 제거 데스` | 이 카운터만 삭제 |
| `!카운터 초기화` | **모든 카운터 삭제** |

**값이 먼저, 이름이 나중이에요**

- ✅ `!카운터 더하기 1 데스`
- ❌ `!카운터 더하기 데스 1`

이름에 띄어쓰기가 있어도 괜찮아요. 값 뒤의 나머지를 통째로 이름으로 봐요.

**`!카운터 초기화` 는 값이 아니라 카운터를 지웁니다**

값을 0으로 되돌리는 게 아니라 **등록된 카운터가 전부 사라집니다.** 오버레이에서도 없어져요.
이름과 목표값을 `!카운터 추가` 로 다시 만들어야 해요. 카운터 이름을 뒤에 붙여도 마찬가지예요.

값만 0으로 만들고 싶다면 카운터마다 `!카운터 설정 0 데스` 를 써주세요.

**참고**

`!카운트` 로 입력해도 똑같이 동작해요.

## 3단계 — 카운터 화면에 띄우기

대시보드 **오버레이 관리 → 카운터 오버레이**에서 주소를 복사해 OBS에 추가해요.
권장 크기는 **400 × 150** 정도예요.

---

## 룰렛과 연동하기 추천

**룰렛 당첨 결과로 타이머·카운터를 자동 조작**할 수 있어요. 이게 진짜 재밌는 부분이에요.

룰렛 아이템의 **액션 추가 ▾** 버튼을 눌러 **+ 카운터** / **+ 타이머** 를 추가해요.

| 이런 룰렛을 만들 수 있어요 | 연동 설정 |
|---|---|
| **"방송 10분 연장"** 당첨 | 타이머에 **+600초** |
| **"방송 5분 단축"** 당첨 | 타이머에 **−300초** |
| **"데스 카운트 +1"** 당첨 | 카운터 현재값 **+1** |
| **"목표 상향"** 당첨 | 카운터 목표값 **+5** |
| **"리셋"** 당첨 | 카운터 **초기화** |

**노방종 룰렛 만들기**

1. `!타이머 추가 2시간 방송종료까지` 로 타이머를 만들고
2. 룰렛 아이템에 "10분 연장"(타이머 +600초), "5분 단축"(타이머 −300초) 등을 넣은 뒤
3. 룰렛 설정의 **룰렛 금액에 맞는 후원 감지시 즉발** 이 켜져 있으면 (기본값 켜짐)

시청자가 후원할 때마다 방송 시간이 늘었다 줄었다 하는 콘텐츠가 완성돼요.

자세한 설정 방법은 [룰렛 문서의 카운터·타이머 연동](/docs/features/roulette#카운터--타이머-연동) 부분을 봐주세요.

---

## 문제 해결

### 명령어를 쳤는데 반응이 없어요

**매니저 이상** 권한이 필요해요. 일반 시청자는 사용할 수 없어요.

### 화면에 안 떠요

| 확인할 것 | 해결 |
|---|---|
| 오버레이를 OBS에 추가했나요? | 대시보드에서 주소를 복사해 브라우저 소스로 추가하세요 |
| 타이머·카운터를 만들었나요? | `!타이머 목록` / `!카운터 목록` 으로 확인해보세요 |
| 브라우저 소스 크기가 0은 아닌가요? | 너비·높이를 확인해보세요 |
| 다른 소스에 가려져 있진 않나요? | OBS 소스 순서를 위로 올려보세요 |

### `시간을 인식하지 못했습니다` 가 나와요

| 이렇게 쓰면 ❌ | 이렇게 쓰세요 ✅ |
|---|---|
| `60:00` (콜론 표기의 분은 59까지) | `60분` 또는 `1:00:00` |
| `한시간` (숫자가 아님) | `1시간` |

콜론 표기는 시(0~24) · 분(0~59) · 초(0~59) 범위를 지켜야 해요.
**한글 표기(`90분`, `120분`)에는 이 범위 제한이 없어요.**

### 오류는 안 나는데 시간이 이상해요

아래는 전부 **정상 생성**돼요. 값만 의도와 다르게 들어가서 더 찾기 어려워요.

| 입력 | 실제로 잡히는 시간 | 원하는 대로 쓰려면 |
|---|---|---|
| `N22:00` (밤 10시 의도) | 0시 22분 | `N22:00:00` |
| `!타이머 1시간 30` (이름 없이) | 1분 30초 | `!타이머 1시간30분` |
| `!타이머 추가 1시간 30 이름` | 1시간 + 이름이 `30 이름` | `!타이머 추가 1시간30분 이름` |
| `1:30` (1시간 30분 의도) | 1분 30초 | `1:30:00` |

### 이름에 띄어쓰기가 있으면요?

`!타이머 추가 30:00 잠깐 쉬는 시간` 처럼 띄어쓰기가 들어간 이름도 만들 수 있어요.
조작할 때도 **이름을 그대로** 끝까지 적어주면 돼요. (`!타이머 제거 잠깐 쉬는 시간`)

**참고**

타이머·카운터는 **이름으로만** 찾아요. 목록에 보이는 순서를 번호로 넣는 건 동작하지 않아요.
헷갈린다면 띄어쓰기 없는 짧은 이름을 쓰는 게 편해요.

---

## 다음 단계

[룰렛 →](/docs/features/roulette) · [오버레이 전체 보기 →](/docs/features/overlay)

**더 궁금한 점이 있나요?**

  [디스코드](https://discord.com/invite/QftHRJCTPZ)에서 편하게 문의해주세요!

---

# 시청자 참여 (시참)

출처: https://chzzk-bot.ddutto.com/docs/features/viewer-participation
설명: 채팅으로 참여자를 모으고 랜덤 추첨하는 시참 기능. 참여·취소·보기·추첨·초기화·삭제·켜기·끄기 전체 사용법을 안내해요.

채팅으로 참여자를 모으고, 랜덤으로 뽑는 기능이에요. 명령어 하나로 **참여 · 취소 · 확인 · 추첨**이 모두 돼요.

**방송 중에만 동작해요**

시참은 방송이 켜져 있을 때만 쓸 수 있어요. **스트리머·매니저도 예외가 아니에요.**
방송을 끈 채로 미리 연습해보려 하면 참여·추첨·켜기 전부 `방송중이 아닙니다.` 만 나와요.

---

## 1단계 — 명령어 만들기

시참은 `$viewer_participation` 변수로 동작해요. 이 변수를 넣은 명령어를 하나 만들면 끝이에요.

```
!추가 !참여 $viewer_participation
```

**명령어 이름은 자유롭게**

`!참여`, `!시참`, `!파티`, `!이벤트`, `!추첨` 등 원하는 이름으로 만들어요.

**여러 명령어를 만들어도**

**참여자 목록은 채널당 하나**를 공유해요. `!파티 참여`로 들어온 사람이 `!참여 보기`에도 나타나요.

---

## 2단계 — 전체 명령어 한눈에 보기

만든 명령어 뒤에 아래 단어를 붙여서 사용해요.

| 입력 | 하는 일 | 필요 권한 |
|---|---|---|
| `!참여 참여` | 참여자 목록에 들어가요 | 누구나 |
| `!참여 취소` | 내 참여를 뺍니다 | 누구나 |
| `!참여 보기` | 지금 참여자 전체를 보여줘요 | 누구나 |
| `!참여 추첨 [N]` | N명을 랜덤으로 뽑아요 | **매니저** |
| `!참여 삭제 [닉네임]` | 특정 사람을 목록에서 뺍니다 | **매니저** |
| `!참여 초기화` | 참여자 목록을 전부 비워요 | **매니저** |
| `!참여 켜기` / `!참여 끄기` | 시참 기능 자체를 열고 닫아요 | **매니저** |

**뭘 입력해야 할지 모르면**

`!참여` 만 치세요. 사용 가능한 목록이 나와요.

---

## 참여 · 취소 · 보기 (시청자용)

### 참여하기

```
!참여 참여
```

> 마지막남은뚜또님의 참여가 완료되었습니다. 현재 참여자 수: 5명

**'추가'라고 해도 돼**

`참여` 대신 `추가`를 써도 돼요. 마침표나 쉼표가 붙어도 인식해요.

이미 들어와 있는 사람이 또 치면 이렇게 나와요.

> 마지막남은뚜또님은 이미 참여하셨습니다.

---

### 참여 취소하기

```
!참여 취소
```

> 마지막남은뚜또님의 참여가 취소되었습니다. 현재 참여자 수: 4명

---

### 참여자 목록 보기

```
!참여 보기
```

> 참여자(4명): 채링 님, 후로기 님, 마지막남은뚜또 님, 링챈 님

**팁**

`보기` 대신 `목록`을 써도 돼요.

---

## 추첨하기 (매니저용)

`추첨` 뒤에 **뽑을 인원수**를 적어요.

```
!참여 추첨 1
```

> 추첨이 완료되었습니다: 채링 님

```
!참여 추첨 3
```

> 추첨이 완료되었습니다: 채링 님, 후로기 님, 마지막남은뚜또 님

**같은 사람이 중복으로 안 뽑혀요.** 3명을 뽑으면 서로 다른 3명이 나와요.

**추첨해도 목록은 안 사라져요**

기본적으로 참여자 목록이 **유지돼요.** 그래서 바로 또 추첨하면 방금 당첨된 사람이 다시 뽑힐 수 있어요.

- 매번 새로 모으고 싶다 → `!설정 시참 자동초기화 켜기`
- 그때그때 직접 비우고 싶다 → `!참여 초기화`
- 당첨자만 빼고 계속 돌리고 싶다 → `!참여 삭제 [당첨자 닉네임]`

---

## 목록 관리하기 (매니저용)

### 특정 사람만 빼기

```
!참여 삭제 채링
```

> 채링님의 참여 신청이 삭제되었습니다. 현재 참여자 수: 3명

**닉네임을 정확히 입력해야 해요**

**채팅에 보이는 닉네임 그대로** 입력하세요. 일부만 맞으면 안 돼요.

`!참여 보기` 목록은 닉네임 뒤에 **' 님'** 을 붙여서 보여줘요. 거기서 그대로 복사해 붙이면
`채링 님님은 참여하신 적이 없습니다. 닉네임을 올바르게 입력하였는지 확인해주세요.` 가 나와요. **' 님' 은 빼고** 넣어주세요.

`!참여 보기`로 목록을 띄운 뒤 복사하고, 뒤에 붙은 ' 님' 을 지운 다음 붙여넣으세요.

### 전부 비우기

```
!참여 초기화
```

> 참여자 목록이 초기화되었습니다.

---

## 기능 켜고 끄기 (매니저용)

모집을 마감하고 싶을 때 씁니다.

```
!참여 끄기
```

> 기능을 껐습니다.

꺼져 있는 동안에는 참여·취소·보기·추첨이 전부 아래처럼 막힙니다.

> 기능이 꺼져있습니다.

다시 열려면 `!참여 켜기` 를 입력하세요.

**이렇게 쓰면 좋아요**

1. `!참여 켜기` → 기능 열기 (기본값이 켜짐이라 대개 칠 필요가 없어요. 이미 켜져 있으면 `이미 기능이 켜져있습니다.` 가 나와요)
2. `!참여 초기화` → 이전 참여자 비우기
3. 시청자들이 `!참여 참여`
4. `!참여 추첨 3` → 당첨자 발표
5. `!참여 끄기` → 마감

**켜기가 먼저예요.** 초기화·삭제·추첨은 기능이 켜져 있어야만 동작해요.
꺼진 상태에서 초기화부터 하면 `기능이 꺼져있습니다.` 만 나와요.

**추첨을 먼저 하고 그다음에 끄세요.** 순서를 바꾸면 안 돼요.

**끄면 추첨도 막힙니다**

`!참여 끄기` 는 모집만 닫는 게 아니라 **참여·취소·보기·추첨을 전부** 막아요.

끈 상태에서 `!참여 추첨 3` 을 치면 당첨자 대신 이 문구가 나와요.

> 기능이 꺼져있습니다.

발표 직전에 슬쩍 참여하는 걸 막고 싶다면 `끄기` 대신 **구두로 마감을 알리고 바로 추첨**하시거나,
추첨 후 `!참여 초기화` 로 목록을 비우세요.

---

## 자동 초기화 설정

추첨을 하면 목록을 자동으로 비울지 정할 수 있어요.

- !설정 시참 자동초기화 [켜기/끄기] — 추첨한 직후 참여자 목록을 자동으로 비워요. / 예: !설정 시참 자동초기화 켜기 / 봇 응답: 시참 자동 초기화가 켜졌습니다. / 쿨타임 1s

| 설정 | 추첨 후 목록 | 이럴 때 좋아요 |
|---|---|---|
| **꺼짐** (기본값) | 그대로 남음 | 같은 참여자 풀에서 여러 번 뽑을 때 |
| **켜짐** | 자동으로 비워짐 | 라운드마다 새로 모집할 때 |

값을 빼고 `!설정 시참 자동초기화` 만 치면 현재 설정을 알려줘요.

---

## 활용 예시

### 게임 파티원 뽑기

```
!추가 !파티 $viewer_participation
```

1. 스트리머: `!파티 켜기` → `!파티 초기화`
2. 시청자: `!파티 참여`
3. 스트리머: `!파티 추첨 4` → (마감하려면) `!파티 끄기`

### 경품 추첨 (당첨자 빼고 계속)

```
!추가 !이벤트 $viewer_participation
```

1. 시청자: `!이벤트 참여`
2. `!이벤트 추첨 1` → 1등 발표
3. `!이벤트 삭제 [1등 닉네임]` → 1등 제외
4. `!이벤트 추첨 1` → 2등 발표

### 라운드마다 새로 모으기

```
!설정 시참 자동초기화 켜기
```

추첨할 때마다 목록이 비워지므로, 매 라운드 새로 `!참여 참여` 를 받으면 돼요.

---

## 주의사항

**봇을 재시작하면 목록이 사라져요**

참여자 목록은 임시 저장돼요. **모집과 추첨은 이어서** 진행하세요.

**익명으로 참여하면**

봇 응답에는 '익명'으로 나오지만, **추첨과 목록에는 실제 닉네임**이 표시돼요.

**매니저는**

치지직 채널의 매니저를 뜻해요. 스트리머 본인도 쓸 수 있어요.

---

## 에러 응답 정리

| 응답 | 원인 | 해결 |
|------|------|------|
| `방송중이 아닙니다.` | 방송이 꺼져 있음 | 방송을 시작한 뒤 사용하세요 |
| `기능이 꺼져있습니다.` | 시참이 꺼져 있음 | `!참여 켜기` |
| `권한이 부족합니다.` | 매니저 전용 명령을 시청자가 사용 | 매니저 권한 확인 |
| `OOO님은 이미 참여하셨습니다.` | 중복 참여 | 정상 동작이에요 |
| `OOO님은 참여하신 적이 없습니다.` | 참여 안 한 상태에서 취소 | — |
| `참여자가 없습니다.` | 목록이 비어 있는데 추첨/보기 시도 | 먼저 참여를 받으세요 |
| `사용 방법: !참여 추첨 [N]` | 뽑을 인원수를 안 적음 | `!참여 추첨 3` 처럼 숫자 입력 |
| `오류: 숫자를 입력해주세요.` | 인원수 자리에 글자를 입력 | 숫자만 입력 |
| `오류: 1 이상의 숫자를 입력해주세요.` | `0` 또는 음수 입력 | 1 이상 입력 |
| `오류: 참여자 수보다 큰 수를 입력하셨습니다.` | 참여자보다 많이 뽑으려 함 | `!참여 보기` 로 인원 확인 |

---

## 다음 단계

시참을 익혔다면, 후원과 연동되는 룰렛도 확인해보세요!

[룰렛 →](/docs/features/roulette) · [가위바위보 →](/docs/features/rock-paper-scissors) · [시스템 설정 →](/docs/commands/system)

---

# 대시보드 가입 방법

출처: https://chzzk-bot.ddutto.com/docs/getting-started/dashboard-signup
설명: 뚜봇 대시보드에 가입하여 봇 설정을 관리하는 방법을 안내해요.

대시보드에 가입하면 명령어 추가, 룰렛 설정, 노래 신청 관리 등 다양한 기능을 웹에서 편하게 관리할 수 있어요!

## 대시보드 가입하기

  1. **대시보드 접속하기**

아래 버튼을 클릭해서 뚜봇 대시보드에 접속하세요.

- [뚜봇 대시보드로 이동](https://chzzk-bot.ddutto.com)

  2. **대시보드로 이동하기 버튼 클릭**

화면 중앙의 **'대시보드로 이동하기'** 버튼을 눌러주세요.

  3. **네이버 로그인하기**

네이버 로그인 화면이 나오면 로그인해주세요.

**동의하기**

  동의 화면이 나오면 **동의하기** 버튼을 눌러주세요. 네이버 로그인을 통해 뚜봇으로 넘어오는 정보는 '암호화된 네이버 ID값' 뿐이에요. 이외의 개인정보는 전송되지 않아요!

  4. **치지직 계정 연결하기**

처음 오셨다면 이 화면이 나와요. 눌러서 본인의 치지직 계정과 연결해주세요.

![대시보드의 '앗, 새로 방문해주신 것 같아요.' 화면](/static/docs/signup/signup-01-newbie.png)

**네이버 NID가 왜 보이나요?**

문의하실 때 계정을 특정하기 위한 값이에요. **클릭해야 보이도록** 가려져 있어요.

  5. **인증 방법 선택하기**

본인이 스트리머인지 매니저인지에 따라 버튼이 다릅니다.

![인증 방법 선택 화면 — 치지직으로 인증하기 / 채팅으로 인증하기](/static/docs/signup/signup-02-method.png)

| 버튼 | 누가 쓰나 |
|---|---|
| **치지직으로 인증하기** | **스트리머** (채널 주인) |
| **채팅으로 인증하기** | **매니저** |

- [스트리머로 가입하기](#스트리머로-가입하기)
- [매니저로 가입하기](#매니저로-가입하기)

  6. **선택한 방법으로 인증 마치기**

아래 두 절 중 본인에게 해당하는 쪽을 따라 인증을 끝내면 가입이 완료돼요.

## 스트리머로 가입하기

  1. **'치지직으로 인증하기' 클릭**

위 화면에서 **'치지직으로 인증하기 (스트리머는 여기!)'** 를 눌러주세요.

  2. **치지직 채널 연동하기**

**'치지직으로 인증하기'** 를 누르면 치지직 계정 연동 페이지로 바로 넘어가요.
거기서 연동을 승인해주세요.

  3. **연동 완료 확인하기**

연동이 완료되면 대시보드 가입이 끝이에요.

이제 기능을 설정할 수 있어요!

## 매니저로 가입하기

**스트리머가 먼저 봇을 초대해둬야 해요**

채널 UID를 넣고 '인증하기' 를 눌렀을 때 그 채널에 뚜봇이 없으면 **인증 문구조차 나오지 않아요.**

> 봇이 해당 채널에 들어가있는지 확인해주세요.
>
> 아직 봇을 넣지 않으셨다면, 채널 주인(스트리머)이 치지직 로그인 후
> 대시보드에서 '뚜봇 초대하기' 를 눌러 봇을 입장시켜야 합니다.

봇 초대는 **스트리머만** 할 수 있어요. 매니저 혼자서는 이 단계를 넘을 수 없어요.

  1. **채널 UID 입력하기**

**'채팅으로 인증하기 (매니저는 여기!)'** 를 누르면 이 화면이 나와요.
인증할 스트리머 채널의 **UID**를 입력해주세요.

![채널 UID 입력 화면](/static/docs/signup/signup-03-uid.png)

**채널 UID란?**

  채널 UID는 치지직 채널의 고유 번호예요.

  **찾는 방법:**
  1. 치지직에서 **인증할 스트리머의** 채널 페이지로 이동
  2. 주소창을 확인
  3. `chzzk.naver.com/` 뒤에 있는 32글자가 UID입니다!

  예시: `https://chzzk.naver.com/4c3a50fe635854036b4dcf15c9a4d0a2`
  → 채널 UID: `4c3a50fe635854036b4dcf15c9a4d0a2`

  2. **인증 문구 입력하기**

**'인증하기'** 를 누르면 입력창이 `!인증` 으로 시작하는 문구로 바뀝니다.
이 문구를 **그대로 복사**해서 해당 채널의 **채팅창에 입력**해주세요.

![인증 문구가 표시된 화면 — !인증 으로 시작하는 코드](/static/docs/signup/signup-04-authcode.png)

정말 이 채널의 권한이 있는지 확인하기 위한 과정이에요.

**참고**

  방송이 꺼져 있어도 돼요. 봇은 방송 중이 아닐 때도 채팅을 받고 있어요.

  3. **인증하기 버튼 클릭**

채팅창에 문구를 입력한 후, 대시보드의 파란색 **'인증하기'** 버튼을 눌러주세요.

버튼을 누르면 가입이 완료돼요. 이제 대시보드에서 기능을 설정할 수 있어요.

---

## 대시보드에서 할 수 있는 것들

대시보드에 가입하면 채팅이 아닌 웹에서 설정을 관리할 수 있어요.

### 뚜봇 관리

| 기능 | 설명 |
|-----|------|
| **유저 명령어** | 커스텀 명령어 추가·수정·삭제 |
| **시스템 명령어** | 봇 내장 명령어 목록 확인 |
| **시스템 변수** | 명령어에서 쓸 값 관리 |
| **매크로** | 자동으로 반복되는 메시지 |
| **룰렛** | 항목·확률·연차·제한 설정 |
| **신청곡 · 노래방 · 노래책** | 대기열 관리와 재생 |
| **출석 · 가위바위보 현황** | 참여 기록 확인 |
| **금칙어 · 마커 · 시청자 목록** | 채팅 운영 |
| **커스텀 스크립트 · 블루프린트** | 고급 자동화 |

### 오버레이 관리

채팅 · 후원 · 타이머 · 신청곡 · 이모티콘 뿌리기 · 팔로우 알림 · 룰렛 · 중간 광고 타이머 · 시청자 수 · 카운터 · 승부예측 · 노래방 · 그림 후원 · 룰렛 사용권

[오버레이 전체 보기 →](/docs/features/overlay)

### 그 외

**디자인 생성기**로 오버레이 디자인을 만들거나, **리모콘**으로 방송 중 빠르게 조작할 수 있어요.

---

## 다음 단계

대시보드 가입이 완료됐다면, 봇에 권한을 부여해서 기능을 더 활용해보세요!

**룰렛·후원 기능을 쓸 계획이라면**

**채널 관리자 권한**을 주는 걸 권해요. 권한이 없으면 후원 금액을 가려둔 경우 룰렛이 동작하지 않아요.

[권한 부여 방법 →](/docs/getting-started/permissions)

---

# 뚜봇 넣는 방법

출처: https://chzzk-bot.ddutto.com/docs/getting-started/invite-bot
설명: 치지직 채널에 뚜봇을 초대하는 방법을 단계별로 안내해요. 준비물, 봇 권한, 잘 안 될 때 확인할 것까지 정리했어요.

대시보드에 **네이버 계정으로 로그인**하고 **치지직 채널을 연동**한 뒤, **[뚜봇 초대하기]** 를 누르면 들어와요.

- [대시보드에서 초대하기](https://chzzk-bot.ddutto.com/dashboard)

들어온 뒤에 [`!업타임` 과 `!추가`](#들어왔으면-바로-해볼-것) 를 입력해보세요.

---

## 시작하기 전에

**이것만 확인해보세요**

- **치지직 채널이 있어야 해요.** (스트리머 계정)
- **채널 주인 본인**이 신청해야 해요. 시청자는 다른 사람 채널에 봇을 넣을 수 없어요.
- 네이버 로그인이 되어 있어야 해요.

### 봇이 들어오면 뭘 할 수 있나요?

처음 초대하는 분들이 가장 궁금해하시는 부분이에요.

| 초대 직후 | 권한을 더 주면 |
|---|---|
| 채팅 읽기 · 채팅 보내기 | 팔로우 알림 |
| 명령어 응답 | 후원자 정보 정확히 인식 |
| 룰렛 · 출석 · 노래신청 | 금칙어 제재 · 임시 차단 |
| 방송 제목·카테고리·태그 변경 | |

방송 제목·카테고리 변경은 **치지직 계정 연동만으로도** 돼요. 초대 과정에서 이미 연동을 끝냈다면 따로 권한을 줄 필요가 없습니다.
팔로우 알림이나 후원자 정보처럼 [권한을 따로 부여](/docs/getting-started/permissions)해야 하는 것도 있어요.

---

## 뚜봇 초대하기

  1. **대시보드 열기**

- [뚜봇 대시보드로 이동](https://chzzk-bot.ddutto.com/dashboard)

  2. **네이버 로그인 후 치지직 연동**

로그인은 네이버 계정으로 해요. 그다음 치지직 채널을 연결해주세요. **두 단계가 모두 끝나야** 초대 버튼이 동작해요.

이 과정이 곧 [대시보드 가입](/docs/getting-started/dashboard-signup) 의 '스트리머로 가입하기' 입니다. 여기서 끝내면 따로 가입할 필요가 없어요.

**참고**

이 과정으로 **채널 주인이라는 게 확인**돼요. 그래서 따로 인증할 게 없어요.

  3. **[뚜봇 초대하기] 누르기**

채널에 봇이 아직 없으면 이 화면이 보여요. 버튼을 누르면 바로 들어와요.

![대시보드의 '아직 뚜봇이 들어간 채널이 없어요.' 화면과 뚜봇 초대하기 버튼](/static/docs/invite-bot/invite-01-button.png)

**참고**

매니저는 이 버튼을 쓸 수 없어요. 아래 **'매니저분이시라면, 여기를 눌러주세요.'** 를 누르면
[채팅 인증](/docs/getting-started/dashboard-signup)으로 연결돼요.

  4. **봇 입장 확인하기**

채널 채팅창에 뚜봇이 들어와 이렇게 인사해요.

> 봇 입장을 희망하셔서, '뚜봇' 이(가) 입장하였습니다.
> 반가워요 :> 저에 대해 궁금하시다면, 제 프로필에 있는 설명서를 참고해주세요! ( 최초 1번만 표시됩니다. )

이 인사는 **처음 초대했을 때만** 나와요. 재입장·재초대 때는 안 나와요.

**스트리머 본인만 초대할 수 있어요**

매니저는 봇을 넣을 수 없어요. **채널 주인**이 치지직 로그인으로 직접 눌러주셔야 해요.

봇이 들어온 뒤에는 매니저도 [대시보드에 가입](/docs/getting-started/dashboard-signup)해서 설정을 도울 수 있어요.

**예전에 댓글로 초대하셨다면**

치지직 커뮤니티에 `봇 입장을 희망합니다.` 라고 댓글을 다는 방식은 **더 이상 안 써요.**
대시보드에서 버튼으로 넣어주세요.

---

## 들어왔으면 바로 해볼 것

봇이 들어와도 **화면에는 아무 변화가 없어요.** 채팅을 입력해야 작동하는 게 보여요.

아래 두 개만 해보시면 뚜봇이 어떤 물건인지 감이 와요. **1분이면 돼요.**

### 1단계 — 살아있는지 확인 (10초)

방송 채팅창에 입력해보세요.

`!업타임`

> 업타임: 1시간 23분 45초

이렇게 답하면 정상이에요.

**답이 없다면**

방송이 꺼져 있어도 `!업타임` 은 답해요. 대신 `업타임: [방송중이 아님]` 이라고 나와요.

**아무 답도 없다면** 봇이 아직 안 들어왔거나, 10초 쿨다운에 걸린 것이에요.
10초 뒤에 다시 쳐보시고, 그래도 조용하면 아래를 입력해보세요.

`!명령어`

### 2단계 — 내 명령어 만들어보기 (30초)

뚜봇에서 제일 많이 쓰는 기능이에요. 채팅창에 그대로 입력해보세요.

`!추가 !인사 안녕하세요! 반갑습니다`

> '!인사' 명령어가 추가되었습니다.

이제 누구든 `!인사` 를 치면 뚜봇이 **"안녕하세요! 반갑습니다"** 라고 답해요.
`!디코`, `!사양`, `!노래신청방법` 처럼 자주 안내하는 것들을 만들어두면 편해요.

**`!추가` 를 쳤는데 봇이 아무 말도 없다면**

`!추가` 는 **매니저 이상**만 쓸 수 있어요. 권한이 없으면 봇은 오류 메시지 없이 **조용히 무시해요.**

채널 주인 본인이면 그냥 돼요. 매니저로 도와주시는 분이라면 스트리머에게 매니저 권한을 받아야 해요.

**여기까지 되면 설치는 끝이에요.** 나머지 기능은 이것 위에 쌓는 것들이에요.

---

## 초대가 안 될 때

| 나오는 메시지 | 뜻 | 해결 |
|---|---|---|
| `치지직 계정 연동이 필요합니다` | 네이버 로그인만 되어 있고 치지직 채널이 연결되지 않음 | 치지직 로그인으로 채널을 연결해주세요 |
| `이미 해당 채널에 ○○봇이 들어가 있습니다` | 이미 초대되어 있음 | 채팅창에 `!업타임` 을 쳐보세요 |
| `치지직에서 채널 정보를 가져오지 못했습니다` | 치지직 서버 응답 지연 | 잠시 후 다시 눌러주세요 |
| 초대 버튼이 안 보임 | 이미 채널이 목록에 있음 | 채널 카드를 눌러 들어가세요 |

그래도 안 되면 문의해주세요.

- [디스코드로 문의하기](https://discord.com/invite/QftHRJCTPZ)

---

## 알아두면 좋은 것

### 방송 켤 때마다 나오는 인사 메시지 끄기

방송을 시작하면 뚜봇이 이렇게 알립니다.

> 방송 시작 감지됨! 봇 입장 완료! | 언제나 봇을 사용해주셔서 감사합니다 :> ( 이 메세지는 `!설정 입장안내 끄기` 로 끌 수 있어요. )

이 메시지가 부담스럽다면 채팅창에 입력해 끌 수 있어요. **매니저 이상**만 가능해요.

`!설정 입장안내 끄기`

### 봇을 내보내고 싶다면

채널 주인이 채팅창에 `!퇴장` 을 입력하면 인증번호가 나오고, 그 번호를 `!퇴장 [번호]` 로 다시 입력하면 봇이 나가요.
**스트리머 전용**이에요.

봇이 나가면 명령어·변수 기능이 전부 꺼지고 채널이 대시보드 목록에서 사라집니다.
기록 자체는 남아 있어서 나중에 다시 초대하면 예전 설정이 그대로 돌아와요.

잘 안 되면 디스코드로 문의해주세요.

---

## 다음 단계

설정을 더 하기 전에, **하고 싶은 걸 먼저 골라보세요.** 필요한 준비물은 각 문서에 적혀 있어요.

| 이런 게 하고 싶다면 | 여기로 |
|---|---|
| 후원받으면 룰렛 돌리기 | [룰렛 만들기 →](/docs/features/roulette) |
| 시청자한테 노래 신청받기 | [신청곡 →](/docs/features/song-request) |
| 채팅을 화면에 띄우고 읽어주기 | [채팅 오버레이 · TTS →](/docs/features/chat-overlay) |
| 출석체크 굴리기 | [출석 체크 →](/docs/features/attendance) |
| 명령어 더 만들기 | [커스텀 명령어 →](/docs/commands/custom) |
| 새 팔로워 알림 받기 | [팔로우 알림 →](/docs/features/follow-alert) |

**이건 해두면 두고두고 편해요**

- **[권한 부여](/docs/getting-started/permissions)** — 방송 제목 변경, 팔로우 알림, 후원 금액 정확히 인식하기에 필요해요.

**더 궁금한 점이 있나요?**

  [디스코드](https://discord.com/invite/QftHRJCTPZ)에서 편하게 문의해주세요!

---

# 권한 부여 방법

출처: https://chzzk-bot.ddutto.com/docs/getting-started/permissions
설명: 뚜봇에 권한을 부여하여 더 많은 기능을 사용하는 방법을 안내해요.

뚜봇은 권한 없이도 기본 기능을 사용할 수 있어요!
하지만 방송 제목 변경, 팔로우 알림 같은 기능을 쓰려면 봇에 권한을 부여해야 해요.

먼저 봇이 채널에 들어와 있어야 해요. 아직이라면 [뚜봇 넣는 방법](/docs/getting-started/invite-bot) 부터 보세요.

## 치지직 매니저 권한과 봇 권한은 어떻게 다른가요?

둘은 서로 다른 권한이고, 하나를 준다고 나머지가 따라오지 않아요.

**매니저**는 **사람**에게 주는 치지직 자체 권한이에요. 스트리머가 치지직 스튜디오에서 지정하면,
매니저가 된 사람은 `!추가` `!금칙어` 같은 관리 명령어를 쓸 수 있어요.

**채팅 운영자 · 채널 관리자**는 **봇 계정**에게 주는 권한이에요. 이걸 줘야 봇이 메시지를 삭제하거나
방송 제목을 바꿀 수 있어요. 이 문서에서 설명하는 건 이쪽이에요.

즉 매니저를 아무리 지정해도 **봇 권한은 따로 부여해야** 해요.

**정리**

- **매니저** — 명령어를 *쓰는 사람*에게 필요한 권한
- **채팅 운영자 / 채널 관리자** — *봇*이 채널에서 갖고 있어야 하는 권한

**권한 없이도 사용 가능한 기능**

**채널 주인(스트리머)이** 대시보드에서 치지직 계정을 연동하면, 권한 없이도 아래 기능을 사용할 수 있어요!
(매니저가 자기 계정을 연동하는 것으로는 켜지지 않아요.)
- 방송 제목 변경
- 방송 카테고리 변경
- 방송 태그 변경
- 채팅 모드 변경
- 채팅 공지 등록
- **메시지 삭제(블라인드)**
- **임시 차단**

연동 후 채팅창에 `!재입장`을 입력하면 적용돼요.

---

## 봇 권한 종류 알아보기

아래는 **봇에게 부여하는 권한**이에요. 봇이 더 많은 기능을 실행할 수 있게 해줘요.

| 봇 권한 | 할 수 있는 것 |
|-----|-------------|
| **권한 없음** | 기본 명령어, 커스텀 명령어, 룰렛, 출석 체크 등 |
| **채팅 운영자** | + 메시지 삭제, 임시 차단, 금칙어 제재 적용 (계정 연동이 안 돼 있을 때 필요) |
| **채널 관리자** | + 방송 제목/카테고리 변경, 팔로우 알림, 팔로우 순번 조회(`$followOrder`), **후원 인식 정밀화** |

팔로워 **수** 조회(`$followCount`)는 공개 정보라 권한이 없어도 돼요. 권한이 필요한 건 순번 쪽이에요.

**🚨 후원 관련 기능을 쓴다면 '채널 관리자'를 권해요**

뚜봇은 기본적으로 **치지직 채팅창에 올라오는 후원 메시지**를 읽어서 동작해요. 그래서 권한이 없으면 이런 제약이 생겨요.

| 상황 | 권한 없을 때 | 채널 관리자일 때 |
|---|---|---|
| 후원 **금액을 가려둔** 경우 | ❌ 금액이 **0원**으로 들어와 룰렛·후원 알림이 **동작하지 않음** | ✅ 정상 동작 |
| **익명의 후원자** | `익명의 후원자` 로 기록됨 (신원은 알 수 없음) | ✅ 실제 후원자 신원까지 기록 |

**"후원했는데 룰렛이 안 돌아가요"의 1순위 원인**이 바로 이거예요. 룰렛·후원 알림을 쓰신다면 채널 관리자 권한을 주시는 걸 권해요.

권한 슬롯이 부족하다면 아래 **우회 권한**을 이용하거나, 디스코드에서 `#팔로우알림-우회-신청`을 작성해주세요.

---

## 권한 부여하기

  1. **권한 관리 페이지 접속**

치지직 스튜디오의 권한 관리 페이지로 이동하세요.
채널 주인뿐 아니라 **'채널 관리자' 권한을 가진 매니저**도 열 수 있어요.

- [권한 관리 페이지로 이동](https://studio.chzzk.naver.com/authority)

  2. **봇 UID 입력하기**

화면 상단의 입력창에 **사용 중인 뚜봇의 UID**를 입력하세요.

**뚜봇 UID 목록**

현재 사용할 수 있는 봇들의 UID입니다:

| 봇 이름 | UID |
|--------|-----|
| 뚜봇 | `f61127606edd1902e89f7e9cace91059` |
| 뚜이봇 | `7539c7aff49cb4b33f2cac6824d3d0e1` |
| 뚜삼봇 | `62e27807733d3e011866db387f49027b` |
| 뚜사봇 | `ee144a96804e71430ad25f5cd46f360a` |
| 뚜오봇 | `afe0c98ec9a277c17f0ac110a9159cf5` |
| 뚜육봇 | `5224cfe7d9a0e8ac84582f934df0d4a4` |
| 뚜칠봇 | `22cdbe7a2e5d6736e1a1c033409cbeb2` |
| 뚜팔봇 | `eea5d291b388f7ef8ba966d77006d35a` |
| 뚜구봇 | `8e0508081382ebce3b547037cf436fa3` |

어떤 봇을 사용 중인지 모르겠다면, 채팅창에서 봇이 말할 때 나오는 닉네임을 확인해보세요!

  3. **권한 선택 및 추가**

원하는 권한(채팅 운영자 또는 채널 관리자)을 선택하고 **추가** 버튼을 클릭하세요.

![치지직 스튜디오 권한 관리에서 봇 닉네임을 입력하고 역할을 고르는 화면](/static/docs/permissions/perm-02-add.png)

**팁**

UID 대신 **봇 닉네임(`뚜봇`)을 그대로 입력**해도 돼요.

  4. **제대로 들어갔는지 확인**

목록에 봇이 추가되고 **역할**이 표시되면 성공이에요.

![권한 목록에 뚜구봇이 채널 관리자로 등록된 모습](/static/docs/permissions/perm-01-list.png)

  5. **봇 재입장시키기**

**권한은 봇이 다시 들어와야 적용돼요.** 채팅창에 아래를 입력해주세요.

`!재입장`

또는 대시보드 **설정** 페이지의 '봇 재입장시키기' 버튼을 사용해도 돼요.

---

## 권한 슬롯이 가득 찼을 때

"이 계정은 너무 많은 채널들의 관리자로 등록되어 있어 더 이상 추가할 수 없어요"라는 오류가 나오나요?

이건 치지직에서 각 계정당 권한 부여 가능 수를 100개로 제한해서 생기는 문제예요.

**해결 방법:**

1. **다른 봇 사용하기**: 뚜육봇, 뚜칠봇 등 다른 봇에 권한을 부여해보세요.
   그 후 [디스코드](https://discord.com/invite/QftHRJCTPZ)에서 봇 변경을 요청하면 돼요.

2. **우회 권한 사용하기**: 아래 우회 계정에 권한을 부여하고 디스코드에서 신청하세요.

   **우회 계정 목록:**
   - 채팅 봇: `06881491985991d533ea409808a83a93`
   - 대한민국정부: `e74e0a56971145242316144046c05789`
   - 람군 봇: `9f921eb7b64ab79b2380c6cdab6e7420`

자세한 우회 방법은 [디스코드 서버](https://discord.com/invite/QftHRJCTPZ)에서 안내받으실 수 있어요.

---

## 권한을 줬는데도 안 될 때

  1. **봇이 채널에 들어와 있나요?**

봇이 없으면 `!재입장` 을 받을 대상도, 대시보드의 재입장 버튼도 없어요.
[뚜봇 넣는 방법 →](/docs/getting-started/invite-bot)

  2. **봇을 재입장시켰나요?**

봇이 채널에 있으면 권한 변경을 스스로 감지해 재입장해요. 이때 아래 안내가 채팅에 나와요.

> 봇의 권한 변경이 감지되었어요. 자동으로 봇을 재입장시키고있어요! 잠시만 기다려주세요 :>

이 메시지가 안 나왔다면 직접 입력해주세요.

`!재입장`

  3. **권한을 준 봇이 맞나요?**

채널에 들어와 있는 봇과 권한을 준 봇의 **UID가 같은지** 확인해보세요. 뚜봇이 아니라 뚜이봇이 들어와 있는데 뚜봇에 권한을 준 경우가 종종 있어요.

  4. **다른 봇이 함께 있진 않나요?**

채널에 **다른 챗봇이 같이 들어와 있으면** 팔로우 알림·게임 티어 조회 같은 일부 기능이 막혀요. 알림이 중복으로 나가는 걸 막기 위한 장치예요.

> 다른 봇이 감지되어 팔로우 알림을 켤 수 없습니다. 만일, 오류인 것 같으시다면 문의해주세요.

  5. **그래도 안 되면**

- [디스코드로 문의하기](https://discord.com/invite/QftHRJCTPZ)

---

## 다음 단계

권한 설정이 완료되었다면 기능을 써보세요.

[기본 명령어 →](/docs/commands/basic) · [룰렛 →](/docs/features/roulette) · [팔로우 알림 →](/docs/features/follow-alert)

---

# 뚜봇 가이드

출처: https://chzzk-bot.ddutto.com/docs/index
설명: 치지직 채팅봇 뚜봇 사용 설명서. 봇 초대부터 룰렛·오버레이·게임 전적 연동까지 전부 안내해요.

- [뚜봇 넣으러 가기](/docs/getting-started/invite-bot)

---

## 처음 오셨나요?

아래 세 가지만 하면 바로 사용할 수 있어요.

  1. **뚜봇 초대하기**

대시보드에 **네이버 계정으로 로그인**하고 **치지직 채널을 연동**한 뒤, 버튼 한 번만 누르면 돼요.

[뚜봇 넣는 방법 →](/docs/getting-started/invite-bot)

  2. **대시보드 가입하기**

웹에서 명령어·룰렛·오버레이를 편하게 설정할 수 있어요.
1번에서 로그인·연동을 끝냈다면 스트리머는 이미 가입된 상태예요. 매니저라면 여기를 보세요.

[대시보드 가입 방법 →](/docs/getting-started/dashboard-signup)

  3. **권한 부여하기**

팔로우 알림, 후원자 정보 정확히 인식 같은 기능을 쓰려면 필요해요. (방송 제목 변경은 1번에서 치지직 계정을 연동했다면 이미 돼요.)

[권한 부여 방법 →](/docs/getting-started/permissions)

---

## 뭘 할 수 있나요?

### 시청자와 함께 노는 기능

| 기능 | 이런 걸 할 수 있어요 |
|---|---|
| **[룰렛](/docs/features/roulette)** | 후원하면 룰렛이 돌아가고 벌칙·선물이 정해져요. 연차·제한·사용권까지 |
| **[출석 체크](/docs/features/attendance)** | 시청자 출석과 콤보를 관리해요 |
| **[노래 신청](/docs/features/song-request)** | 시청자가 노래를 신청하고 대기열이 자동으로 돌아가요 |
| **[가위바위보](/docs/features/rock-paper-scissors)** | 봇과 가위바위보. 전적도 남아요 |
| **[시청자 참여](/docs/features/viewer-participation)** | 시참 신청과 순서 관리 |

### 방송 화면 꾸미기

| 기능 | 이런 걸 할 수 있어요 |
|---|---|
| **[채팅 오버레이](/docs/features/chat-overlay)** | 채팅을 화면에 표시. 폰트 117종 · TTS · 게임 티어까지 |
| **[팔로우 알림](/docs/features/follow-alert)** | 새 팔로워를 화면과 채팅으로 알려요 |
| **[후원 알림](/docs/features/donation-alert)** | 후원 알림 + 메시지 읽어주기 |
| **[이모티콘 뿌리기](/docs/features/emoticon-spread)** | 채팅 이모티콘이 화면에 흩날려요 |
| **[타이머 · 카운터](/docs/features/timer-counter)** | 카운트다운과 숫자 세기. 룰렛과 연동돼요 |
| **[오버레이 전체 보기](/docs/features/overlay)** | 16종 오버레이 목록과 OBS 설정법 |

### 방송 운영

| 기능 | 이런 걸 할 수 있어요 |
|---|---|
| **[커스텀 명령어](/docs/commands/custom)** | `!디코`, `!사양` 같은 명령어를 직접 만들어요 |
| **[방송 설정](/docs/commands/broadcast)** | 채팅으로 방송 제목·카테고리를 바꿔요 |
| **[게임 전적 · 티어](/docs/features/game-tier)** | 롤·TFT·발로란트·오버워치2·배그·이터널리턴 티어 표시 |
| **[변수](/docs/commands/variables)** | 명령어 안에서 쓰는 값들 |

### 개발자용

| 기능 | 이런 걸 할 수 있어요 |
|---|---|
| **[API](/docs/api/overview)** | 룰렛·신청곡·출석 정보를 외부에서 가져다 써요 |

---

## 자주 겪는 문제

**후원했는데 룰렛이 안 돌아가요**

치지직 설정에서 **후원 금액이 숨겨져 있고** 뚜봇에게 **채널 관리자 권한도 없으면** 금액이 **0원**으로 들어와서 룰렛 금액과 맞출 수가 없어요.

[룰렛 문서의 '시작하기 전에'](/docs/features/roulette) 부분을 확인해보세요.

**일부 기능이 안 켜져요**

채널에 **다른 챗봇이 함께 있으면** 팔로우 알림·게임 티어 같은 기능이 막혀요. 중복 동작을 막기 위한 장치예요.

**방송 제목이 안 바뀌어요**

뚜봇에게 **채널 관리자 권한**을 주거나, 대시보드에서 **치지직 계정을 연동**해주세요. 둘 중 하나만 있으면 돼요.

[권한 부여 방법 →](/docs/getting-started/permissions)

---

## 도움이 필요하신가요?

- [자주 묻는 질문](/docs/faq)을 먼저 확인해보세요.
- 그것도 도움이 안 되면 아래로 문의해주세요.

- [디스코드로 문의하기](https://discord.com/invite/QftHRJCTPZ)

**참고**

뚜봇은 치지직·유튜브·트위치 및 관련 게임사와 **공식 제휴 관계가 없는 제3자 서비스**예요.

---