ESP32 Telegram 內嵌鍵盤 (Inline Keyboard)

 ESP32 Telegram 內嵌鍵盤 (Inline Keyboard)

/*******************************************************************

    An example of how to use a custom reply keyboard markup.

     written by Vadim Sinitski (modified by Brian Lough)

 *******************************************************************/

#include <WiFi.h>

#include <WiFiClientSecure.h>

#include <UniversalTelegramBot.h>

// Wifi network station credentials

#define WIFI_SSID "Wokwi-GUEST"

#define WIFI_PASSWORD ""

// Telegram BOT Token (Get from Botfather)

#define BOT_TOKEN "7738940254:AAHbrWu9ovb1BKPQyWsbNSjNxfCGCrEWU-o"

const unsigned long BOT_MTBS = 1000; // mean time between scan messages

WiFiClientSecure secured_client;

UniversalTelegramBot bot(BOT_TOKEN, secured_client);

unsigned long bot_lasttime;          // last time messages' scan has been done

void handleNewMessages(int numNewMessages)

{

  for (int i = 0; i < numNewMessages; i++)

  {

    // Inline buttons with callbacks when pressed will raise a callback_query message

    if (bot.messages[i].type == "callback_query")

    {

      Serial.print("Call back button pressed by: ");

      Serial.println(bot.messages[i].from_id);

      Serial.print("Data on the button: ");

      Serial.println(bot.messages[i].text);

      bot.sendMessage(bot.messages[i].from_id, bot.messages[i].text, "");

    }

    else

    {

      String chat_id = bot.messages[i].chat_id;

      String text = bot.messages[i].text;

      String from_name = bot.messages[i].from_name;

      if (from_name == "")

        from_name = "Guest";

      if (text == "/options")

      {

        String keyboardJson = "[[{ \"text\" : \"Go to Google\", \"url\" : \"https://www.google.com\" }],[{ \"text\" : \"Send\", \"callback_data\" : \"This was sent by inline\" }]]";

        bot.sendMessageWithInlineKeyboard(chat_id, "Choose from one of the following options", "", keyboardJson);

      }

      if (text == "/start")

      {

        String welcome = "Welcome to Universal Arduino Telegram Bot library, " + from_name + ".\n";

        welcome += "This is Inline Keyboard Markup example.\n\n";

        welcome += "/options : returns the inline keyboard\n";

        bot.sendMessage(chat_id, welcome, "Markdown");

      }

    }

  }

}

void setup()

{

  Serial.begin(115200);

  Serial.println();

  // attempt to connect to Wifi network:

  Serial.print("Connecting to Wifi SSID ");

  Serial.print(WIFI_SSID);

  WiFi.begin(WIFI_SSID, WIFI_PASSWORD);

  secured_client.setCACert(TELEGRAM_CERTIFICATE_ROOT); // Add root certificate for api.telegram.org

  while (WiFi.status() != WL_CONNECTED)

  {

    Serial.print(".");

    delay(500);

  }

  Serial.print("\nWiFi connected. IP address: ");

  Serial.println(WiFi.localIP());

  Serial.print("Retrieving time: ");

  configTime(0, 0, "pool.ntp.org"); // get UTC time via NTP

  time_t now = time(nullptr);

  while (now < 24 * 3600)

  {

    Serial.print(".");

    delay(100);

    now = time(nullptr);

  }

  Serial.println(now);

}

void loop()

{

  if (millis() - bot_lasttime > BOT_MTBS)

  {

    int numNewMessages = bot.getUpdates(bot.last_message_received + 1);

    while (numNewMessages)

    {

      Serial.println("got response");

      handleNewMessages(numNewMessages);

      numNewMessages = bot.getUpdates(bot.last_message_received + 1);

    }

    bot_lasttime = millis();

  }

}

這段程式碼展示了 Telegram 機器人最強大的功能之一：內嵌鍵盤 (Inline Keyboard)。與之前的程式不同，這次機器人會送出帶有「按鈕」的訊息，使用者點擊按鈕後會觸發特定的回饋。

以下是逐行詳細說明：

---

1. 核心邏輯：處理按鈕回傳 (callback_query)

在 handleNewMessages 函式中，新增了對按鈕點擊的判斷：

C++

if (bot.messages[i].type == "callback_query") {
  // 當使用者點擊帶有 callback_data 的按鈕時，會進入這裡
  Serial.print("Call back button pressed by: ");
  Serial.println(bot.messages[i].from_id); // 印出是誰按的
  Serial.print("Data on the button: ");
  Serial.println(bot.messages[i].text);    // 印出按鈕內藏的資料 (callback_data)
  
  // 機器人回應：把按鈕內藏的文字再傳回給使用者
  bot.sendMessage(bot.messages[i].from_id, bot.messages[i].text, "");
}

• callback_query：這是一種特殊的訊息類型。當按鈕被按下時，Telegram 會發送一個「請求」而不是普通文字，這讓機器人知道該執行哪個特定動作。

---

2. 建立內嵌鍵盤指令 (/options)

這是本範例的核心，展示如何撰寫 JSON 格式來產生按鈕：

C++

if (text == "/options") {
  // 定義鍵盤結構 (JSON 格式)
  // 第一排：一個按鈕，功能是開啟網址 (URL)
  // 第二排：一個按鈕，點擊後會發送隱藏的 "callback_data"
  String keyboardJson = "[ "
                        "[{ \"text\" : \"Go to Google\", \"url\" : \"https://www.google.com\" }], "
                        "[{ \"text\" : \"Send\", \"callback_data\" : \"This was sent by inline\" }]"
                        " ]";

  // 使用專門的函式傳送帶有鍵盤的訊息
  bot.sendMessageWithInlineKeyboard(chat_id, "Choose from one of the following options", "", keyboardJson);
}

• 鍵盤 JSON 結構：

  • text: 按鈕上顯示的文字。

  • url: 點擊後會跳轉到該網頁。

  • callback_data: 不會顯示在螢幕上，但點擊後機器人會收到這串文字，用來判斷使用者按了哪個按鈕。

---

3. 基礎設定與時間同步 (setup & loop)

這部分與前幾個範例類似，但有幾個重點：

• configTime: 機器人必須同步網路時間（NTP），因為 Telegram 的加密連線會檢查時間戳記。如果開發板時間不準，連線會被拒絕。

• bot.getUpdates: 在 loop 中持續詢問伺服器有沒有新訊息。如果有訊息（包含按鈕點擊），就會交給 handleNewMessages 處理。

---

4. 程式邏輯流程圖解

步驟	使用者動作	機器人反應
1	輸入 /start	傳送歡迎詞，告知有 /options 指令。
2	輸入 /options	彈出兩個按鈕：「Go to Google」與「Send」。
3	點擊 「Send」	手機端不會看到文字發出，但機器人會收到 callback_query，並回傳訊息。

---

為什麼這很有用？

內嵌鍵盤可以讓你的專案看起來非常專業。例如：

• 家電控制：不需要打字，直接按「開燈」或「關燈」按鈕。

• 選單導航：透過按鈕切換不同的感測器數據顯示（如：溫度、濕度、光照）。