팝업레이어 알림

팝업레이어 알림이 없습니다.

미니앱Mini Apps

텔레그램 미니앱 개발 입문 가이드 -- HTML/JS로 나만의 미니앱 만들기 (BotFather 설정부터 배포까지)

laptop_mac Developer Guide

HTML/JS로 나만의
텔레그램 미니앱 만들기

별도 앱 스토어 심사 없이, HTML과 JavaScript만으로 10억 명의 텔레그램 사용자에게 앱을 배포할 수 있습니다. BotFather 설정부터 첫 미니앱 배포까지 단계별로 안내합니다.

info OVERVIEW

텔레그램 미니앱이란?

미니앱은 텔레그램 채팅 안에서 실행되는 웹 애플리케이션입니다. 일반 웹사이트처럼 HTML, CSS, JS로 개발하되, 텔레그램이 제공하는 WebApp API를 통해 사용자 인증, 결제, 알림 등 네이티브 기능을 활용할 수 있습니다.

person사용자

arrow_forward

smart_toy텔레그램 봇

arrow_forward

laptop_macWebApp (HTML/JS)

앱 스토어 심사 없이 즉시 배포
HTML/CSS/JS만으로 개발
10억 명 사용자 즉시 접근
Stars/TON 결제 내장 지원

smart_toy STEP 1

BotFather로 봇 생성하기

미니앱은 반드시 봇을 통해 실행됩니다. 텔레그램에서 @BotFather를 검색하고 봇을 생성하세요.

봇 생성

텔레그램에서 @BotFather를 검색 -> /newbot 명령어 입력 -> 봇 이름과 사용자명(username) 설정. 사용자명은 반드시 bot으로 끝나야 합니다. (예: MyFirstMiniApp_bot)

API 토큰 저장

봇 생성이 완료되면 API Token(예: 123456:ABC-DEF...)이 발급됩니다. 이 토큰은 절대 공개하지 마세요. 메모장에 안전하게 저장합니다.

미니앱 URL 연결

BotFather에서 /newapp 명령어 입력 -> 방금 만든 봇 선택 -> 미니앱 URL 입력. 아직 URL이 없다면 다음 단계에서 만들겠습니다.

lightbulb 팁: /mybots -> 봇 선택 -> Bot Settings -> Menu Button에서 미니앱 URL을 봇의 메뉴 버튼으로 설정하면, 사용자가 채팅창 왼쪽 하단 버튼을 눌러 바로 미니앱을 열 수 있습니다.

edit STEP 2

미니앱 코드 작성하기

기본 HTML 파일 하나로 시작합니다. 텔레그램 WebApp JS SDK를 로드하면 사용자 정보와 테마 색상에 접근할 수 있습니다.

index.html

<!-- 기본 미니앱 템플릿 -->
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport"
        content="width=device-width, initial-scale=1.0">
  <!-- 텔레그램 WebApp SDK 로드 -->
  <script src="https://telegram.org/js/telegram-web-app.js"></script>
</head>
<body>
  <h1 id="greeting">Loading...</h1>
  <p id="info"></p>

  <script>
    // WebApp 객체 초기화
    const tg = window.Telegram.WebApp;
    tg.ready();  // 텔레그램에 "준비 완료" 알림

    // 사용자 정보 표시
    const user = tg.initDataUnsafe?.user;
    if (user) {
      document.getElementById('greeting')
        .textContent = `안녕하세요, ${user.first_name}님!`;
      document.getElementById('info')
        .textContent = `User ID: ${user.id}`;
    }

    // 테마 색상 자동 적용
    document.body.style.background =
      tg.themeParams.bg_color || '#ffffff';
  </script>
</body>
</html>

warning 주의: initDataUnsafe는 클라이언트 측 데이터로, 서버에서 검증 없이 신뢰하면 안 됩니다. 실제 서비스에서는 반드시 initData를 서버로 전송하여 HMAC-SHA256으로 검증해야 합니다.

settings STEP 3

WebApp API 핵심 기능

텔레그램 WebApp API가 제공하는 주요 기능들입니다. 이 기능들을 조합하면 네이티브 앱 수준의 경험을 만들 수 있습니다.

person

tg.initDataUnsafe.user

사용자의 ID, 이름, 언어, 프로필 사진 등에 접근합니다. 별도 로그인 없이 텔레그램 계정으로 자동 인증됩니다.

palette

tg.themeParams

사용자의 다크/라이트 모드 색상을 자동 감지합니다. 배경색, 텍스트 색상, 버튼 색상을 테마에 맞춰 적용할 수 있습니다.

expand_more

tg.MainButton

화면 하단에 고정 버튼을 표시합니다. 텍스트, 색상, 클릭 이벤트를 설정할 수 있으며, "주문하기", "결제하기" 등의 행동 버튼으로 사용합니다.

payments

tg.sendData() / Bot API Invoice

미니앱에서 봇으로 데이터를 전송하거나, Stars 결제 인보이스를 생성하여 인앱 결제를 처리합니다.

MainButton 예제

// 하단 메인 버튼 표시
tg.MainButton.setText("주문 완료");
tg.MainButton.show();

// 클릭 시 봇에게 데이터 전송
tg.MainButton.onClick(function() {
  tg.sendData(JSON.stringify({
    action: "order",
    item: "coffee",
    qty: 2
  }));
});

cloud_upload STEP 4

무료 호스팅에 배포하기

미니앱은 HTTPS로 서비스되어야 합니다. 무료 호스팅을 사용하면 비용 없이 배포할 수 있습니다.

GitHub Pages (가장 쉬움)

GitHub 저장소에 index.html을 푸시하고, Settings -> Pages에서 배포를 활성화하면 https://유저명.github.io/저장소명/ 주소가 생성됩니다. 완전 무료이며 SSL이 자동 적용됩니다.

Vercel / Netlify (프론트엔드 특화)

GitHub 연동만 하면 자동 빌드 및 배포. 커스텀 도메인, 서버리스 함수까지 무료로 지원합니다. React/Vue 등 프레임워크 사용 시 특히 추천합니다.

BotFather에 URL 등록

배포된 URL을 BotFather -> /myapps -> 봇 선택 -> Edit Web App URL에 입력합니다. 이제 봇을 통해 미니앱에 접근할 수 있습니다.

lightbulb 테스트 팁: 개발 중에는 @BotFather -> /mybots -> Bot Settings -> Menu Button에서 localhost를 ngrok 터널링하여 테스트할 수 있습니다. ngrok http 3000 명령으로 로컬 서버를 HTTPS로 노출하세요.

trending_up NEXT STEPS