텔레그램 봇

텔레그램 봇

1. 웹훅 URL 셋팅

   1. 등록
      • [POST] https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook
        • 파라미터
          • url
            • https://your.domain.com/telegram/webhook/<SECRET_KEY>
          • secret_token [optional]
            • <ANOTHER_SECRET_KEY>
              • 텔레그램이 서버로 요청 보낼 때 HTTP 헤더 X-Telegram-Bot-Api-Secret-Token: ANOTHER_SECRET_TOKEN 를 포함하므로 서버에서 헤더값을 검증.

                • @PostMapping("/telegram/webhook/{secret}")
                  public ResponseEntity<String> receive(@RequestHeader(value="X-Telegram-Bot-Api-Secret-Token", required=false) String headerToken,
                                                      @PathVariable String secret,
                                                      @RequestBody UpdateDto update) {
                      if (!configuredSecret.equals(secret) || !configuredHeaderToken.equals(headerToken)) {
                          return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
                      }
                      // 처리...
                      return ResponseEntity.ok("ok");
                  }

   2. 조회
      • [GET] https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo
   3. 삭제
      • [POST] https://api.telegram.org/bot<YOUR_BOT_TOKEN>/deleteWebhook

2. 텔레그램 요청

   • [POST] https://your.domain.com/telegram/webhook/<SECRET_KEY>
   • Content-Type: application/json
   • (만약 secret_token 사용 시) X-Telegram-Bot-Api-Secret-Token: MY_SECRET_TOKEN
   • Body(JSON 예시)

   •   {
           "update_id": 123456789,
           "message": {
                           "message_id": 11,
                           "from": { 
                                       "id": 987654321,
                                       "is_bot": false,
                                       "first_name": "흥수",
                                       "username": "heungsu" 
                                   },
                           "chat": { 
                                       "id": 987654321,
                                       "type": "private" 
                                   },
                           "date": 1700000000,
                           "text": "/start" 
                       } 
       }

3. 버튼 생성

   • sendMessage

   • 예시 JSON (간단한 목록 + 버튼): { "chat_id": 123456789, "text": "항목을 선택하세요.", "reply_markup": { "inline_keyboard": [ [ {"text": "열기", "callback_data": "action:open,id:42"}, {"text": "수정", "callback_data": "action:edit,id:42"}, {"text": "삭제", "callback_data": "action:delete,id:42"} ] ] } }

   •   Map<String,Object> btnOpen = Map.of("text","열기","callback_data","action:open,id:42");
       Map<String,Object> btnEdit = Map.of("text","수정","callback_data","action:edit,id:42");
       Map<String,Object> btnDelete = Map.of("text","삭제","callback_data","action:delete,id:42");
     
       List<List<Map<String,Object>>> keyboard = List.of(List.of(btnOpen, btnEdit, btnDelete));
       Map<String,Object> replyMarkup = Map.of("inline_keyboard", keyboard);
     
       telegramApiClient.sendMessage(chatId, "항목을 선택하세요.", replyMarkup).subscribe();

4. 버튼 클릭(사용자 상호작용) → 서버로 오는 이벤트

   • 사용자가 인라인 버튼을 클릭하면 텔레그램은 등록된 웹훅 URL로 callback_query 객체를 POST합니다.
     • callback_query 주요 필드:
       • callback_query.id: 콜백 식별자(답장 시 사용)
       • callback_query.from.id: 버튼 클릭한 사용자 id
       • callback_query.data: 버튼에 설정한 callback_data
       • callback_query.message: 버튼이 붙어 있던 메시지 정보(채팅 id, message_id 포함)
       • 예시 callback JSON 일부:

       • { "update_id": 9999, "callback_query": { "id": "1234567890", "from": {"id": 987654321, "username":"heungsu"}, "message": {"message_id": 111, "chat": {"id": 987654321}}, "data": "action:delete,id:42" } }