텔레그램 봇 명령어 등록 — 범위·언어별 명령

명령어란

명령어는 / 로 시작하는 짧은 낱말입니다. 사용자가 입력창에 / 를 치거나 메뉴 버튼을 누르면 봇이 등록해 둔 명령 목록이 설명과 함께 뜹니다. 목록에 띄우는 일과 명령을 처리하는 일은 따로입니다 — 목록은 등록으로, 처리는 내 프로그램이 받은 메시지 글자를 보고 합니다.

규칙	내용
명령 이름	1~32자, 영문 소문자·숫자·밑줄(_)만
설명	최대 256자 — 목록에서 이름 옆에 보인다
개수	한 범위(scope)에 최대 100개
기본으로 둘 것	/start · /help · /settings — 공식 문서가 모든 봇에 권한다

이름은 뜻이 분명하게 짓습니다. /new 장소 처럼 뒤에 말을 붙이게 하기보다 /newlocation 처럼 한 낱말로 하나의 일을 하게 하는 편이 누르기 쉽습니다.

등록하는 두 가지 방법

1. @BotFather 에서 봇을 고르고 명령 편집으로 들어가 명령 - 설명 형식으로 한 줄에 하나씩 보냅니다. 코드 없이 바로 됩니다.
2. 봇 API 의 setMyCommands 로 프로그램에서 등록합니다. 범위와 언어를 나눌 수 있어 더 세밀합니다.

curl https://api.telegram.org/bot123456:ABC-EXAMPLE/setMyCommands \
  -H "Content-Type: application/json" \
  -d '{"commands":[
        {"command":"start","description":"시작하기"},
        {"command":"help","description":"도움말"}
      ],
      "language_code":"ko"}'

지금 등록된 목록은 getMyCommands, 지우기는 deleteMyCommands 입니다. 둘 다 같은 범위·언어 값을 받습니다.

범위(scope)와 언어로 나누기

범위	누구에게 보이나
default	따로 정한 목록이 없는 모든 곳
all_private_chats	모든 개인 대화
all_group_chats	모든 그룹·슈퍼그룹
all_chat_administrators	모든 그룹의 관리자
chat · chat_administrators · chat_member	특정 대화 하나, 그 대화의 관리자, 그 대화의 특정 사용자

한 사용자에게 여러 범위가 겹치면 더 좁은 범위의 목록이 보이고, 같은 범위 안에서는 사용자 앱 언어(language_code)에 맞춘 목록이 언어 없는 목록보다 먼저입니다. 한국어 목록과 언어 없는(영어) 목록을 함께 등록해 두면 언어에 따라 알아서 갈립니다.

그룹에서의 명령

그룹에 봇이 여럿이면 /help@내봇이름 처럼 봇 이름을 붙여 누구에게 보낸 명령인지 가립니다. 그룹 개인정보 모드가 켜진 봇도 자기에게 온 명령은 받습니다(그룹 개인정보 모드). 메뉴 버튼에 명령 목록 대신 미니 앱을 띄우는 방법은 봇 메뉴 버튼에 있습니다.