/setup 메뉴: X Bot 텔레그램 UI 완전 가이드

X Bot을 설정하는 가장 빠른 방법은 인터랙티브 /setup 메뉴입니다. 모든 관리자 명령을 클릭 가능한 즉시 편집 인터페이스로 감싸므로 외울 슬래시 명령어가 없습니다.

가장 빠른 경로: 그룹에 봇을 추가하고 /setup을 입력한 다음 🚀 Quick Start를 탭하고 네 가지 안내를 따라가세요. 2분 이내에 실제 필터로 동작하는 일일 리포트 일정을 갖추게 됩니다.

/setup의 모습

╔══════════════════════════════════════════════╗
║ ⚙️  Bot Setup                                ║
║                                              ║
║ Pick a section. Settings save instantly.     ║
║                                              ║
║ Current state                                ║
║ ─ Project:  MyToken                          ║
║ ─ Filter:   3 keywords · 2 cashtags          ║
║ ─ Schedule: daily 18:00 UTC                  ║
║ ─ Plan:     FREE — 47/100 credits left       ║
╠══════════════════════════════════════════════╣
║ [ 🚀 Quick Start ]                           ║
║ [ 🎯 Filters     ] [ ⏰ Schedule       ]      ║
║ [ 📊 Reports     ] [ 🎨 Customization  ]      ║
║ [ 👥 Admins      ] [ 💳 Buy Credits   ]      ║
║ [ ℹ️  About       ]                          ║
║ [ ✕ Close ]                                  ║
╚══════════════════════════════════════════════╝

모든 화면은 상단에 현재 상태를 보여주므로 변경하기 전에 무엇이 설정되어 있는지 알 수 있습니다. 모든 변경 사항은 데이터베이스에 즉시 저장됩니다 — 잊어버릴 "저장" 버튼 같은 건 없습니다.

Quick Start 마법사

🚀 Quick Start를 탭하면 새 채팅을 "아무것도 설정되지 않음"에서 "첫 예약 리포트"까지 최소한의 안내로 이끄는 4단계 선형 플로우가 시작됩니다. Skip과 Exit는 언제나 사용할 수 있습니다 — 부분적으로 완료된 마법사가 여러분을 막는 일은 없으며, 설정은 그저 기본값으로 유지됩니다.

네 가지 단계:

단계	묻는 것	저장 위치
1	프로젝트 이름	ProjectName 설정(리포트, 리더보드 카드, 관리자 DM에 사용)
2	X에서 무엇을 추적할지 — 계정, 캐시태그, 또는 키워드	기본 필터의 from, cashtags, keywords 배열
3	일일 리포트를 언제 게시할지 — 4개 프리셋 시각 또는 사용자 지정 HH:MM	채팅에 연결된 예약 작업
4	완료 — 지금 바로 미리보기할 수 있는 /recreate 힌트가 담긴 요약 화면	(없음)

전체 메뉴

각 최상위 버튼은 하나의 집중된 화면을 엽니다. 자유롭게 하위로 이동하세요 — 모든 화면에는 이전 단계로 가는 ← Back과 닫는 ✕ Close가 있습니다.

🎯 Filters

봇이 예약 실행마다 가져오는 X 게시물을 정의합니다.

카테고리를 탭하면 하위로 이동합니다. Excludes는 체크박스 방식입니다 — 한 번 탭하면 "리트윗/답글/인용 트윗 제외"가 토글됩니다.

Named filters(고급)는 한 채팅에서 여러 필터를 동시에 운영할 수 있게 해줍니다 — 한 그룹에서 여러 클라이언트를 관리할 때 유용합니다. 각 명명된 필터에는 확인 탭이 있는 행별 삭제 버튼이 있습니다. ➕ Add named filter를 탭해 메뉴를 통해 한 줄짜리 정의를 보내세요(name from:@x keywords:y cashtags:$Z mention:@m exclude:retweet ignore:@spam). from / keywords / cashtags / mention 중 최소 하나는 필요합니다.

카테고리 화면은 다음과 같습니다 — 카테고리가 하는 일에 대한 짧은 설명, 현재 값, Add / Remove / Clear all 액션:

➕ Add를 탭하면 메뉴가 입력 모드로 전환됩니다 — 일반 메시지처럼 답장을 입력하면 화면이 확인 배너("✓ Added 2 cashtags: $BTC, $ETH")와 함께 자동으로 다시 그려집니다.

➕ Add cashtags

Send the cashtags to track, space-separated.
The $ is optional.

Example:  $BTC $ETH SOL

Type your reply as a normal message,
or tap Cancel to go back.

[✕ Cancel]

⏰ Schedule

봇이 언제 실행되어 일일 리포트를 게시할지입니다.

네 가지 일일 프리셋이 대부분의 커뮤니티를 커버합니다. 현재 활성화된 프리셋은 라벨 앞에 ✓가 붙습니다. Custom time은 HH:MM을 요구합니다. Specific days는 14:30 Mon Wed Fri 형식을 받습니다. Cron은 표준 크론 표현식을 받습니다(예: cron(0 12 ? * MON-FRI *)). 봇은 비용을 예측 가능하게 유지하기 위해 최소 12시간 간격을 강제합니다.

필터가 없는 채팅에서 일정 프리셋을 탭하면 메뉴는 친절한 오류와 함께 🎯 Filters로 다시 안내하며 거부합니다 — 봇은 가져올 대상이 없는 채팅에는 일정을 잡지 않습니다.

📊 Reports & Period

📊 Reports & Period

Period: 01/05/2026 7days
Start:  2026-05-01
End:    2026-05-07

The bot fetches X posts inside this window on
every scheduled run. Without a period
configured, the bot uses a rolling 24-hour
window.

[📆 Set period]   [🗑 Clear period]
[⚡ Generate report now]
[📰 Show last report]

Set period는 리포트를 특정 구간(예: 1주일간의 경쟁)으로 제한합니다. 형식은 DD/MM/YYYY Ndays 또는 Nweeks입니다. Clear period는 기본값인 롤링 24시간으로 되돌립니다. Generate report now는 크론이 사용하는 것과 동일한 Step Function을 트리거합니다 — 즉시 미리보기에 유용합니다. Show last report는 /report를 가리킵니다(크레딧 소모 없이 가장 최근 캐시된 이미지를 다시 게시합니다).

🎨 Customization

리포트와 공개 리더보드에 표시되는 프로젝트 메타데이터입니다.

🎨 Customization

🏷 Name:        MyToken
✏️ Description: A community-driven DeFi project
📝 Long desc.:  (multi-paragraph project pitch…)
🖼 Logo:        ✓ uploaded
🔗 URLs:        2 URLs
💬 Topic:       Forum topic "Reports"

[🏷 Name]      [✏️ Description]
[📝 Long desc.][🖼 Logo]
[🔗 URLs]      [💬 Topic]
[📈 Leaderboard customization]

Leaderboard 하위 트리는 다음을 노출합니다:

설정	형식
🏆 Points	공백으로 구분된 5개 숫자: likes retweets replies quotes views(예: 5 1 20 10 0.01)
🎨 Colors	같은 순서의 5개 헥스 색상
🔢 Top count	1~10 사이의 정수 — 리더보드에 표시할 사용자 수
📛 Top title	자유 텍스트. 선택적 |#hex 접미사로 커스텀 색상 지정(예: Top contributors|#FF8800)
🥇 Best-tweet title	동일
📊 Engagement title	동일

로고 업로드는 봇의 기존 사진 핸들러를 사용합니다 — 🖼 Logo를 탭한 다음 이미지를 텔레그램 사진으로 보내세요(파일 아님). 봇이 크기를 조정해 웹사이트 CDN에 업로드합니다.

Topic은 원하는 포럼 토픽 안에서 /set_topic을 보내라고 안내합니다. 메뉴는 콜백 버튼에서 message_thread_id를 캡처할 수 없으므로 이는 슬래시 명령 전용 영역으로 남아 있습니다.

👥 Admins & Notifications

크레딧 소진, 가져오기 오류, 채팅-없음 경고에 대한 비공개 DM을 받도록 지정된 사용자를 나열합니다. 관리자 추가는 여전히 채팅에서 /add_admin @user1 @user2를 요구합니다 — 텔레그램의 @-멘션 파서는 콜백이 아니라 실제 메시지에서만 작동합니다.

👥 Admins & Notifications

Currently:
  • Alice (@alice_admin)
  • Bob (@bob_dev)

To add admins, send /add_admin @user1 @user2
in this chat.

[🗑 Clear notification list]

💳 Buy Credits & Plan

요금제 + 잔액 표시, 그리고 구매/관리 흐름을 구동하는 버튼입니다. 화면은 채팅의 현재 요금제에 따라 다르게 렌더링됩니다:

FREE 채팅:

💳 Buy Credits & Plan

Plan: FREE
Used this month: 47 / 100
Remaining:        53
Resets: 2026-06-01

[💰 Buy credits / upgrade]   [🛠 Manage subscription]
[📊 Usage this month]

PRO 구독 채팅:

💳 Buy Credits & Plan

Plan: PRO (subscription) ✓
Unlimited fetching with Stripe metering above 1 000 / month free.

[💰 Buy credits / upgrade]   [🛠 Manage subscription]
[📊 Usage this month]

PRO 크레딧 채팅(ETH로 구매):

💳 Buy Credits & Plan

Plan: PRO (credits)
Credits remaining: 4 152
Total purchased:   5 000

[💰 Buy credits / upgrade]   [🛠 Manage subscription]
[📊 Usage this month]

💰 Buy credits / upgrade 버튼은 메뉴 아래에 결제 옵션 카드를 게시합니다. 봇이 제공하는 옵션은 현재 요금제에 따라 다릅니다:

• FREE → 💳 Pay with Credit Card(Stripe 구독)와 🪙 Pay with ETH(크레딧 팩) 둘 다.
• PRO 크레딧 → 두 옵션 모두 표시. ETH는 기존 잔액을 충전하고, Stripe는 그 위에 구독을 쌓습니다(기존 ETH 크레딧은 유지되며 가져오기당 먼저 소진됩니다).
• PRO 구독 → 구매 옵션 없음. 봇은 "구독이 이미 존재함" 메시지로 응답하며 Stripe 포털로 가는 🛠 Manage를 안내합니다.

🛠 Manage subscription 버튼은 브라우저에서 Stripe 고객 포털을 엽니다 — 카드를 업데이트하거나 취소하거나 인보이스를 다운로드할 수 있는 곳입니다. 활성 Stripe 구독이 있을 때만 의미가 있습니다.

📊 Usage this month 하위 화면은 당월과 오늘의 fetched_posts와 fetch_attempts를 분리해 보여줍니다 — 조용한 실패를 발견하는 데 유용하며(시도는 많은데 게시물이 0건이면 402나 빈 쿼리일 가능성), 1,000건 임계값에 가까워질 때 다음 Stripe 인보이스를 미리 볼 수 있습니다.

구매 + 관리는 레거시 슬래시 명령 /buy와 /subscription으로도 접근할 수 있습니다. 동작은 동일하며, 메뉴 버튼은 그저 타이핑을 줄여줄 뿐입니다.

📡 X Posts Auto-relay

선택한 X 계정의 게시물을 게시되는 즉시 채팅으로 전달합니다 — 예약된 리포트와는 별개입니다. 프로젝트가 X를 확인하지 않고도 커뮤니티 관리자가 공식 계정 트윗을 실시간으로 보길 원할 때 유용합니다.

📡 X Posts Auto-relay

Forward posts from X accounts to this chat as soon
as they're published. Posts can take up to 5
minutes to appear here after the original was
posted on X.

3 active relays:
▶️ @MyTokenOfficial    (4/10 today)
▶️ @MyTokenCEO         (1/10 today)
⏸ @MyTokenSupport     (0/10 today)

[ ▶️ @MyTokenOfficial ]
[ ▶️ @MyTokenCEO ]
[ ⏸ @MyTokenSupport ]
[ ➕ Add Account ]

각 릴레이는 X API를 통해 5분마다 폴링합니다. 새 게시물(마지막 성공적 전달 이후)은 일반 URL로 채팅에 푸시됩니다 — 텔레그램이 X 미리보기 카드를 자동으로 렌더링하므로 게시물 본문이 보입니다.

릴레이별 관리 화면에서 운영자는 동작을 조정할 수 있습니다:

📡 X Posts Auto-relay › @MyTokenOfficial

State: ▶️ Active
Today: 4/10 forwarded
Polls every: 5 min

Post types to forward
☐ Retweets
☐ Replies (to other users)
✅ Quote tweets
✅ Thread continuations (self-replies)

Topic: (default — top of chat)

[ ⏸ Pause ] [ ✏️ Cap: 10/day ]
[ ☐ Retweets ] [ ☐ Replies ]
[ ✅ Quote tweets ] [ ✅ Thread ]
[ 💬 Set topic ] [ 🧹 Clear topic ]
[ 🗑 Delete relay ]

설정	하는 일
Cap(1~100/day)	채팅당 UTC 하루 최대 전달 건수 — 도달하면 릴레이는 자정 UTC까지 조용히 전달을 멈춥니다. 기본값 10.
Pause / Resume	해당 릴레이의 폴링 일정을 비활성화합니다. 재개하면 즉시 다시 생성됩니다.
Retweets	✅면 릴레이 대상 계정의 리트윗이 전달됩니다. 기본값 off.
Replies	✅면 다른 사용자에 대한 답글이 전달됩니다. 기본값 off.
Quote tweets	✅면 인용 트윗이 전달됩니다. 기본값 on.
Thread continuations	✅면 자기 자신에 대한 답글(스레드)이 전달됩니다 — 트위터 스레드를 커버합니다. 기본값 on. 각 스레드의 첫 트윗만 원한다면 이 옵션을 off로 설정하세요.
Topic	선택적 텔레그램 포럼 토픽 ID. 설정하면 릴레이는 메인 스레드가 아니라 해당 토픽에만 게시합니다.

자동 정리: 텔레그램이 "채팅 사라짐" 오류를 반환하면(봇이 강퇴되거나 차단됨) 릴레이는 폴링 일정과 저장된 설정을 자동으로 제거합니다. 누수 없음.

하드 제한: 채팅당 릴레이 10개. 더 필요하면 기반 상수를 조정하세요.

ℹ️ About

ℹ️ About this chat

Chat ID: -1002593612414
Plan: PRO ✓
Schedule: daily 18:00 UTC
Project: MyToken

지원 요청을 위한 진단 패널입니다.

/setup이 슬래시 명령과 관계되는 방식

/setup은 추가적입니다 — 기존의 모든 슬래시 명령은 이전과 정확히 동일하게 작동합니다. 메뉴는 동일한 기본 구성 요소(buildQueryFromComponents, saveXBotSetting, createScheduleRule 등)를 감싸므로 두 방식 사이의 동작은 동일합니다. 파워 유저는 손에 익은 속도를 위해 /add_keywords DeFi airdrop처럼 계속 입력할 수 있고, 신규 사용자는 친절한 클릭형 인터페이스를 얻습니다.

세 가지 명령은 콜백이 전달하지 않는 일반 텍스트 + 텔레그램 메시지 엔터티 컨텍스트가 필요하기 때문에 메뉴 버튼으로 옮길 수 없습니다:

명령	남아있는 이유
/set_topic [name]	메시지가 전송된 토픽의 message_thread_id를 캡처합니다 — 버튼에는 스레드 컨텍스트가 없습니다
/add_admin @user	채팅 관리자 확인을 위해 텔레그램의 검증된 멘션 엔터티에 의존합니다
/set_x_filtering	명명된 필터를 추가하는 레거시 슬래시 명령입니다. 메뉴의 ⤴ Named filters → ➕ Add named filter가 동일한 작업을 합니다

설정 레시피

일반적인 목표 → 정확한 메뉴 경로. 각 레시피는 1~2분의 클릭이면 됩니다.

"원본 게시물만 추적(리트윗, 답글 없음)"

대부분의 커뮤니티는 재공유가 아니라 원본 콘텐츠에 보상하는 리더보드를 원합니다.

/setup → 🎯 Filters → 🚫 Excludes → Retweets와 Replies를 탭해 둘 다 ✅로 표시합니다. 끝입니다. 이후 가져오기는 X API에 -is:retweet -is:reply를 보내며 인용 트윗은 그대로 유지됩니다.

"좋아요보다 답글을 더 보상(커뮤니티 구축)"

기본 가중치: 좋아요 1×, 리트윗 2×, 답글 1.5×, 인용 3×, 조회수 0.001×. 대화를 우선하려면:

/setup → 🎨 Customization → 📈 Leaderboard customization → 🏆 Points → 전송:

1 1 5 3 0.001

답글이 이제 5×의 가중치를 가집니다 — 실질적인 토론이 단순 좋아요를 앞섭니다.

"하루 두 번 리포트 실행"

기본적으로 일정은 하루 최대 한 번 발동됩니다. 유럽 종료 시점과 미국 종료 시점 리포트를 모두 받으려면:

/setup → ⏰ Schedule → 🔧 Cron expression → 전송:

cron(0 14,22 ? * * *)

하루 두 번, 14:00 + 22:00 UTC에 발동됩니다. 최소 12시간 간격 검사가 자동으로 ≥ 12시간 간격을 강제합니다 — 더 좁은 간격은 명확한 오류와 함께 거부됩니다.

"한 그룹에서 여러 캠페인을 동시에 추적"

세 개의 동시 클라이언트 캠페인, 텔레그램 그룹 하나, 발동당 캠페인별 리포트 하나.

/setup → 🎯 Filters → ⤴ Named filters → ➕ Add named filter, 그런 다음 각 회차에 다음 중 하나를 전송:

campaign_a from:@kol1,@kol2 keywords:"#CampaignALaunch"
campaign_b from:@kol3,@kol4,@kol5 cashtags:$CBT
campaign_c from:@kol6 mention:@CampaignC_Official

각각 같은 일정에 발동되며 필터 이름이 태그된 별도의 리포트를 게시합니다.

"리포트 사이 실시간으로 계정 트윗 전달"

@MyTokenOfficial의 중요 소식은 22:00 UTC 리포트까지 기다릴 필요가 없습니다.

/setup → 📡 X Posts Auto-relay → ➕ Add Account → 전송:

@MyTokenOfficial 5

(선택적 5는 일일 한도이며 기본값은 10입니다.) 봇은 5분마다 폴링하며 새 게시물이 있으면 URL을 전달하고 텔레그램이 미리보기 카드를 렌더링합니다.

"캠페인 기간(예: 7일 푸시)으로 리포트 제한"

캠페인 이전의 노이즈가 리더보드를 오염시키는 것을 원하지 않습니다.

/setup → 📊 Reports → 📆 Set period → 전송:

01/05/2026 7days

이제 리포트는 해당 구간 안의 게시물만 가져옵니다. 🗑 Clear period는 롤링 24시간으로 되돌립니다.

"리포트를 메인 스레드가 아니라 포럼 토픽에 게시"

그룹이 토픽을 사용하며, 리포트는 전용 Reports 토픽에 게시되어야 합니다.

Reports 토픽을 연 다음, 그 안에서 전송:

/set_topic Reports

이후 리포트는 해당 토픽으로 라우팅됩니다. 되돌리려면: 그룹 어디서든 /set_topic clear.

"크레딧 소진 시 특정 관리자 두 명에게만 알림"

봇은 크레딧/가져오기/채팅-없음 오류에 대해 지정된 관리자에게 DM을 보냅니다. 기본적으로 모든 채팅 관리자에게 폴백되며, 이를 특정 목록으로 좁힐 수 있습니다.

/add_admin @alice @bob

이제 DM은 @alice와 @bob에게만 전송됩니다. 지우려면: /setup → 👥 Admins → 🗑 Clear notification list.

"공개 xbot.ninja 쇼케이스에서 채팅 숨기기"

솔로 KOL 포트폴리오는 자동으로 숨겨집니다(사용자 1명이 활성 사용자 ≥ 2명 기준을 통과하지 못함). 비공개로 유지해야 하는 커뮤니티 프로젝트라면:

명시적인 숨김 토글은 없습니다 — 공개 리스팅은 지표 기준으로 게이트됩니다. 비공개로 유지하는 두 가지 방법:

• 기준을 충족하지 않는 작고 조용한 채팅을 운영하세요(최고 사용자 점수 < 300, 게시물 < 5/월, 또는 활성 사용자 < 2).
• 지원팀에 연락해 채팅을 예외로 설정하세요 — 공개 대시보드는 지표와 무관하게 이를 건너뜁니다.

채팅의 직접 URL(https://xbot.ninja/?chatId=…)은 어쨌든 계속 접근 가능합니다. 데이터를 봐야 하는 사람에게만 공유하세요.

흔한 함정

증상	이유	해결 방법
FREQUENCY_ERROR로 일정이 "거부됨"	크론이 12시간보다 더 자주 발동하려고 시도	간격 검사 — 최소 12시간 간격을 선택하세요. 오류 메시지가 문제가 되는 시간 쌍을 알려줍니다.
/setup이 자동완성에 나타나지 않음	BotFather 명령 목록이 오래됨	봇은 자동완성과 무관하게 /setup을 받아들입니다. 발견 가능성이 중요하다면 BotFather → /setcommands를 업데이트하세요.
필터 미리보기에 빈 괄호나 이상한 쿼리 표시	일부 구성 요소가 비어 있음	/setup → 🎯 Filters가 실제 쿼리를 보여줍니다. 계정/캐시태그/키워드/멘션 중 최소 하나를 추가하세요.
X Posts Auto-relay가 스레드 전체를 한 번에 전달	자기 답글은 X API의 exclude=replies를 우회함	/setup → 📡 X Posts Auto-relay → @account → ☐ Thread continuations를 off로 전환. 그러면 봇은 스레드의 첫 트윗만 유지합니다.
일일 한도에 도달했는데 더 필요함	릴레이의 MAX_POSTS_PER_DAY에 도달	✏️ Cap을 탭해 올리세요. 전달된 게시물마다 크레딧 1개가 소모됩니다.
커스텀 제목/색상이 밤사이 되돌아감	설정 업데이트는 성공했지만 UPDATED_AT 갱신이 렌더 캐시를 무효화함. 다음 가져오기에서 새 값이 표시됨	리포트 주기 하나만 기다리세요. 렌더 캐시는 다음 가져오기에서 재구축됩니다.
리포트에 "게시물 0건"만 표시	설정된 기간 안에 필터에 일치하는 게시물이 없음	기간을 제거하세요(롤링 24시간이 더 관대함), 또는 필터를 넓히세요. 흔히 캐시태그 오타가 원인입니다.
봇은 "온라인"이지만 리포트가 오지 않음	봇이 조용히 관리자에서 강등되거나 강퇴됨	텔레그램 → 그룹 관리자를 확인하세요. 없다면 재승격하세요. 봇은 채팅-없음 오류 시 자동으로 스스로를 비활성화합니다.

완료

마법사의 마지막 화면은 저장된 모든 내용을 요약하고 즉시 미리보기를 위해 /setup → 📊 Reports → ⚡ Generate report now를 안내합니다:

투어는 여기까지입니다. 그룹에서 /setup을 입력해 시작하세요.

메뉴 항목 설정에서 문제가 발생했나요? 필터, 일정, 결제를 다루는 증상-해결 매트릭스는 Troubleshooting을 참고하세요.