Telegram Mini App — 단계별 가이드

무엇인가요?#

Telegram Mini App는 고객이 Telegram 내에서 레스토랑의 디지털 메뉴를 직접 열 수 있게 해줍니다 — 앱 설치나 브라우저 전환 없이. 메뉴는 Telegram의 네이티브 부분처럼 보이며, 사용자의 테마에 맞춰 조정되고, '뒤로' 버튼과 제스처를 지원합니다.

장점#

• 📱 Telegram 내에서 — 고객이 브라우저로 전환할 필요가 없습니다
• 🎨 네이티브 외관 — 색상, 글꼴 및 테마가 Telegram에 맞춰 조정됩니다
• 🔗 Deep Links — 특정 레스토랑 메뉴로의 직접 링크
• 🌍 자동 언어 — 사용자의 Telegram 설정에서 언어를 가져옵니다
• 🍪 쿠키 없음 — Telegram 내에서는 쿠키 배너가 표시되지 않습니다

빠른 시작#

1단계 — 봇 생성#

Telegram에서 @BotFather를 열고 다음을 입력하세요:

/newbot

1. 봇 이름을 입력하세요 (예: Cenaly Menu Bot)
2. 사용자 이름을 입력하세요 (예: MeniMenuBot) — Bot으로 끝나야 합니다
3. 받은 Bot Token을 저장하세요 (형식: 123456789:ABCdefGHI...)

Bot Token이 필요한 이유는?#

Bot Token은 Telegram Bot API를 통해 봇을 프로그래밍적으로 관리하기 위한 비밀 키입니다. Mini App의 기본 설정(2–4단계)에는 필요하지 않습니다 — 모든 것은 BotFather를 통해 이루어집니다. 그러나 다음을 원할 경우 필요합니다:

• 고객에게 메시지 보내기 — 주문 상태 알림, 프로모션, 환영 메시지
• 봇 메시지에 인라인 버튼 추가 (예: "📋 메뉴 열기" 버튼 — 아래 섹션 참조)
• 주문 수신을 위한 Telegram 봇 생성 — 봇이 주문을 수신하고 처리할 수 있습니다
• Webhook 설정 — Telegram에서 이벤트 수신(버튼 클릭, 사용자 명령)
• CRM 또는 POS 시스템과 통합 — 봇을 통한 주문 자동 처리

2단계 — Mini App 생성#

BotFather에 다음 명령을 보내세요:

/newapp

1. 목록에서 봇을 선택하세요
2. Title — 앱 이름 (예: Cenaly)
3. Description — 설명 (예: 디지털 레스토랑 메뉴)
4. Photo — 640×640 px 이미지를 업로드하세요 (앱 아이콘)
5. GIF — 애니메이션 (선택 사항). 건너뛰려면 /empty를 입력하세요
6. Web App URL — 클라이언트 앱의 주소를 입력하세요:

https://cenaly.com

7. Short Name — 링크의 짧은 이름 (예: menu)

이후 다음과 같은 작동 링크가 생성됩니다:

https://t.me/YourBot/menu

3단계 — 봇 채팅에 "메뉴" 버튼 추가#

BotFather에 다음을 보내세요:

/setmenubutton

1. 봇을 선택하세요
2. URL을 보내세요:

https://cenaly.com

3. 버튼 텍스트를 입력하세요 (예: Open Menu 또는 📋 메뉴)

이제 봇 채팅을 열면 화면 하단에 앱을 여는 버튼이 나타납니다.

4단계 — 도메인 허용#

BotFather에 다음을 보내세요:

/setdomain

봇을 선택하고 도메인을 입력하세요:

cenaly.com

이로써 Telegram Web App이 귀하의 도메인 및 모든 하위 도메인(예: locationid.cenaly.com)에서 작동할 수 있습니다.

Deep Links — 특정 레스토랑으로의 링크#

Telegram은 앱을 열 때 전달되는 startapp 매개변수를 지원합니다. 이를 사용하여 특정 레스토랑으로의 링크를 생성하세요:

예시#

레스토랑의 LOCATION_ID가 lnc2w74z인 경우:

https://t.me/YourBot/menu?startapp=lnc2w74z
https://t.me/YourBot/menu?startapp=lnc2w74z__ru
https://t.me/YourBot/menu?startapp=lnc2w74z__en

봇의 인라인 버튼#

봇이 고객에게 메시지를 보내는 경우, 메뉴를 여는 인라인 버튼을 추가할 수 있습니다:

옵션 1 — Web App 버튼 (즉시 열림)#

{
  "inline_keyboard": [[{
    "text": "📋 메뉴 열기",
    "web_app": {
      "url": "https://LOCATION_ID.cenaly.com/ru"
    }
  }]]
}

옵션 2 — Deep Link 버튼#

{
  "inline_keyboard": [[{
    "text": "📋 메뉴 열기",
    "url": "https://t.me/YourBot/menu?startapp=LOCATION_ID__ru"
  }]]
}

자동으로 작동하는 기능#

Telegram 내에서 연결 후 자동으로 활성화되는 기능:

레스토랑을 위한 QR 코드#

https://lnc2w74z.cenaly.com 형식의 기존 QR 코드는 브라우저를 통해 정상적으로 작동합니다.

Telegram과의 추가 통합을 위해 테이블에 봇 링크가 포함된 두 번째 QR 코드를 배치할 수 있습니다:

https://t.me/YourBot/menu?startapp=lnc2w74z

작동 확인#

1. 휴대폰에서 링크 https://t.me/YourBot/menu를 여세요
2. Start를 누르세요 (봇을 처음 여는 경우)
3. 채팅 하단 패널에서 📋 메뉴 버튼을 누르세요
4. 앱이 열리고 메뉴가 로드되는지 확인하세요
5. Deep Link를 열어보세요: https://t.me/YourBot/menu?startapp=LOCATION_ID

자주 발생하는 문제#

유용한 링크#

• Telegram Mini Apps 문서
• BotFather
• Telegram Bot API — Web App 버튼