Cơ sở kiến thức GetMyBot

Tin nhắn và nút

Tạo câu trả lời của bot bằng văn bản, ảnh, nút dưới tin nhắn và câu hỏi có lưu câu trả lời.

Trên trang này

Để bot gửi văn bản, ảnh và nút “Chọn”, thêm hành động Gửi tin nhắn. Câu trả lời được ghép từ các phần gọi là khối. Ví dụ, gửi ảnh sản phẩm rồi phần mô tả có nút bên dưới. Các nút gắn với tin nhắn còn được gọi là nút inline.

Trong cùng hành động, bạn cũng có thể đặt câu hỏi và chờ trả lời, chẳng hạn hỏi số điện thoại rồi lưu vào hồ sơ khách hàng. Dưới đây là cách dùng khối, nút và câu hỏi.

Các khối tin nhắn

Nhấn Thêm khối và chọn nội dung muốn gửi. Bạn có thể kết hợp lời chào bằng văn bản, ảnh và tệp giới thiệu lớp học.

  • Văn bản: nội dung có định dạng, biến thay thế và nút; tối đa 4.096 ký tự.
  • Ảnh: ảnh có chú thích.
  • Tệp: tài liệu có phần mô tả.
  • Voice (tin nhắn thoại): âm thanh OGG/OPUS, MP3 hoặc M4A, tối đa 50 MB, được Telegram hiển thị như tin nhắn thoại qua sendVoice.
  • GIF: ảnh động hoặc MP4 không tiếng, tối đa 50 MB (sendAnimation).
  • Video note: MP4 vuông dài tối đa 60 giây (sendVideoNote), không có chú thích. Mỗi lần gửi, tệp từ thư viện được tải lên lại: Telegram không nhận file_id có được theo cách khác trong sendVoice, sendAnimation hoặc sendVideoNote.
  • Carousel: từ 2 đến 10 thẻ, mỗi thẻ có ảnh, chú thích và nút riêng. Trong Telegram, thẻ được chuyển bằng nút “‹ ›” trong một tin nhắn chỉ khi mọi ảnh có file_id phù hợp, được khai báo trong thẻ hoặc lấy từ tệp trong thư viện. Nếu thiếu ID phù hợp của dù chỉ một ảnh, tất cả thẻ được gửi thành tin nhắn ảnh riêng. Các kênh khác như VK cũng gửi riêng. Chú thích và nút của từng thẻ được giữ.
  • Độ trễ: tạm dừng số giây đã nhập trước khối tiếp theo.
  • AI: câu trả lời do mô hình tạo từ lời nhắc.
  • Phản ứng: gọi phản ứng khác, có thể chờ nó xử lý xong.

Voice, GIF, Video note và Carousel hoạt động trong phản ứng như các khối khác và cũng được đưa vào lượt gửi nhanh phản ứng. Xem Gửi hàng loạt.

Bạn có thể kéo để đổi thứ tự khối. Chọn hiển thị Theo thứ tự hoặc Ngẫu nhiên để có nhiều biến thể. Menu chính của bot có thể giữ nguyên, đặt lại hoặc ẩn.

Tùy chọn của khối

Khối văn bản và đa phương tiện có các tùy chọn: ghim, gửi không tiếng, chống chuyển tiếp, ẩn nội dung (spoiler), không xem trước liên kết và tự xóa sau N giây.

Nút inline

Trong khối, đặt Văn bản nút và Loại nút:

  • Văn bản: gửi chữ trên nút như câu trả lời của người dùng. Telegram và VK dùng bàn phím trả lời; nhấn nút có thể trả lời câu hỏi hoặc chạy phản ứng theo văn bản. WhatsApp, Instagram, Messenger và tiện ích web dùng nút trả lời không phải bàn phím cố định.
  • Liên kết: mở URL.
  • Ứng dụng web: mở Telegram Mini App. Xem Mini App.
  • Phản ứng: nhấn nút để chạy phản ứng khác.
  • Inline query: điền “@bot truy vấn” vào ô nhập của chat hiện tại hoặc cho chọn chat khác (switch_inline_query / switch_inline_query_current_chat). Chỉ dùng trong Telegram sau khi bật chế độ inline qua /setinline ở @BotFather. GetMyBot chưa trả lời truy vấn loại này (answerInlineQuery chưa được triển khai), nên nút chỉ chuẩn bị chữ chứ không thực hiện tìm kiếm.
  • Prefilled text: mở https://t.me/<bot>?text=…, đặt văn bản sẵn trong ô nhập của bot và không gửi (prefill).
  • Liên kết thanh toán: mở URL thanh toán bắt buộc. Khoản thanh toán được tạo bằng hành động Xuất hóa đơn. Đây là trang thanh toán bên ngoài, không phải hóa đơn Telegram nguyên bản.
  • Thông báo: hiển thị văn bản khi nhấn, không chạy phản ứng và không truyền dữ liệu Carry của nút. Trong Telegram, đó là thông báo ngắn hoặc cửa sổ tối đa 200 ký tự; trong VK là thông báo ngắn tối đa 90 ký tự, không có cửa sổ.

Văn bản trả lời hay văn bản điền sẵn?

Mục đíchLoại nút và thiết lậpKhi nhấn
Chọn “Có” trong biểu mẫuVăn bản, nhãn “Có”; tin nhắn phải chờ câu trả lời“Có” được chuyển cho bước hội thoại
Chuẩn bị lời nhắnPrefilled text, nhãn “Viết”, nội dung “Tôi muốn đặt hàng”Ô nhập chat có bản nháp; người dùng tự sửa và gửi

Nhãn nút và nội dung được điền sẵn là hai ô khác nhau. Prefilled text không gửi tin hoặc tự chạy phản ứng.

Với nút Phản ứng, lượt nhấn trở thành một sự kiện riêng gửi cho bot, gọi là callback. Inline query và Prefilled text hoạt động trong ứng dụng Telegram nên không có sự kiện nhấn gửi cho bot. Vì vậy, chúng không hỗ trợ answerCallbackQuery hoặc truyền dữ liệu Carry.

Biểu tượng và màu của nút

Có thể hiển thị emoji Premium trước nhãn nút. Nhập ID của nó (icon_custom_emoji_id) dưới dạng số nguyên dương 64 bit. Ví dụ 007 được hiểu là 7. Chữ, số không, số âm hoặc số quá lớn bị bỏ qua và nút được lưu không có biểu tượng.

Telegram chỉ hiển thị biểu tượng nếu bot có quyền phù hợp: tên người dùng bổ sung qua Fragment, hoặc chủ bot có Telegram Premium khi gửi trực tiếp trong chat riêng hay nhóm. Với các bot khác, Telegram bỏ qua biểu tượng, không thay bằng emoji thường.

Kiểu nút quyết định màu: Thông thường không màu, Chính xanh lam, Thành công xanh lá, Nguy hiểm đỏ. Tên trường kỹ thuật là style.

Dùng một lần (đốt sau khi nhấn) (single_use) cho phép dùng dữ liệu đã lưu trên nút đúng một lần, chẳng hạn để xác nhận lựa chọn. Đổi nhãn nút hoặc xóa tin nhắn sau khi nhấn là các thiết lập riêng.

Các cờ của nút

Cờ là tùy chọn bật/tắt bằng dấu chọn:

  • Từ hàng mới: đặt nút ở hàng kế tiếp.
  • Kéo dài toàn bộ chiều rộng: nút chiếm một hàng riêng; nút tiếp theo cũng bắt đầu hàng mới.

Hình dung cách bố trí (dấu ngoặc vuông đại diện cho nút):

Cùng hàng:       [Danh mục] [Trợ giúp]

Từ hàng mới:     [Danh mục]
                 [Trợ giúp]

Toàn chiều rộng: [       Trợ giúp       ]

Hàng nút và màu dùng được trong Telegram, VK. Bố cục hàng vẫn được giữ khi mở và sửa lại. Emoji Premium cần kết nối Telegram phù hợp. Không có công tắc “Mở trong Telegram” để điều khiển hành vi này; Bot API không hỗ trợ tùy chọn như vậy.

Giới hạn theo kênh

Chọn kết nối cho từng khối hoặc nút. Khi chọn Tất cả kênh, trình chỉnh sửa chỉ cho dùng các tính năng chung. Loại nút không được hỗ trợ sẽ không thể lưu.

  • Telegram: URL, Mini App, phản ứng, thông báo/cửa sổ, hàng nút, màu và emoji tùy chỉnh nếu bot có quyền.
  • VK: URL, phản ứng, thông báo ngắn, hàng nút và màu. VK Mini App và VK Pay chỉ có khi chọn kết nối VK tương thích.
  • WhatsApp: một nút URL CTA, không kèm nút khác trong cùng tin. Tối đa 3 nút trả lời hiển thị thường; từ 4 đến 10 được hiển thị thành danh sách. Nhãn tối đa 20 ký tự. Không có hàng, màu, Mini App, thông báo.
  • Instagram / Messenger: bộ kết nối hiện tại chỉ truyền nút trả lời nhanh (quick replies), nhãn tối đa 20 ký tự. Không có URL, Mini App, thông báo, hàng hay màu.
  • Tiện ích web: URL và nút trả lời, không có hàng, màu hay thông báo.
  • Email: liên kết, kể cả liên kết thanh toán; không có nút trả lời hoặc thông báo.

Với nút tạo từ danh sách, chỉ kênh hỗ trợ hàng nút mới cho đặt số cột. Kênh khác tự bố trí. Số nút và độ dài nhãn được kiểm tra khi gửi.

Khi nhấn nút

Với nút gửi lượt nhấn tới bot, tùy kênh bạn có thể thay tin nhắn bằng văn bản hoặc nội dung từ phản ứng khác, xóa tin nhắn, gắn nhãn hoặc lưu tham số. Đổi chữ trên chính nút sau khi nhấn chỉ có trong Telegram, ví dụ đổi “Đặt chỗ” thành “Đã chọn”. VK có thể sửa tin nhắn nhưng không đổi nhãn nút.

Telegram chờ bot xác nhận lượt nhấn bằng answerCallbackQuery. Thông thường GetMyBot gửi xác nhận tự động và bỏ biểu tượng đang tải trên nút. Bật Bỏ qua answerCallbackQuery sẽ tắt xác nhận đó.

Trong ô Text on press (notification) của nút Phản ứng, nhập lời xác nhận ngắn như “Đã chọn lớp học” (tối đa 200 ký tự trong Telegram, 90 trong VK; có thể chèn biến). Telegram thường hiển thị thoáng qua trên chat. Show as a popup (alert) chỉ có trong Telegram và mở cửa sổ bằng answerCallbackQuery với show_alert. Để trống văn bản thì bot chỉ bỏ biểu tượng đang tải. Nếu bật Bỏ qua answerCallbackQuery, cả văn bản lẫn cửa sổ đều không được gửi.

Dữ liệu trên nút (Carry)

Carry giúp nút ghi nhớ mình thuộc đối tượng nào. Ví dụ, áo khoác và váy đều có nút “Mua”: lưu product_id=101 trên nút áo khoác, product_id=102 trên nút váy. Khi nhấn nút váy, phản ứng tiếp theo nhận {{ctx.product_id}} bằng 102.

Trong trình chỉnh sửa, mục này có tên Dữ liệu gửi khi nhấn. Khóa đặt tên giá trị; giá trị có thể là số, chữ hoặc biến thay thế. Bot lưu dữ liệu lúc gửi tin nhắn, rồi đặt nó vào ngữ cảnh tạm (ctx) của phản ứng khi nút được nhấn. Mỗi nút có dữ liệu riêng.

Thời hạn hiệu lực của dữ liệu nút, giây (ttl_seconds, TTL) được nhập bằng giây: 3600 là một giờ. 0 dùng mặc định 30 ngày. Hết hạn thì không dùng được dữ liệu. Dùng một lần (single_use) xóa dữ liệu ngay sau lượt nhấn đầu tiên. Giá đã lưu không tự cập nhật khi danh mục đổi; hãy kiểm tra giá mới theo ID sản phẩm trước khi thu tiền.

Xem Nút động và tham số để thiết lập từng bước và hiểu khác biệt với tham số lưu lâu dài.

Nút động

Nếu đã có danh sách sản phẩm hoặc lớp học, bạn không cần thêm nút từng cái. Khối Nút động từ danh sách tạo một nút cho mỗi phần tử. Chọn vị trí danh sách trong ctx, tên tạm của một phần tử (alias), số nút trên hàng và mẫu chữ. Ví dụ, {{item.name}} chèn tên của sản phẩm hiện tại. Xem Nút động và tham số.

Emoji Premium trong văn bản

Trong khối văn bản, nút định dạng Emoji Premium chèn <tg-emoji emoji-id="…">🙂</tg-emoji>. Người có Telegram Premium thấy emoji tùy chỉnh; người khác thấy emoji dự phòng bên trong thẻ. Dùng được với cả HTML lẫn Markdown. ID emoji là số tối đa 32 chữ số; có thể tra bằng getCustomEmojiStickers hoặc chuyển tiếp emoji đến bot như @idstickerbot.

Liên kết bot và văn bản điền sẵn

Liên kết t.me/<bot>?start=<tham_số> chạy lệnh /start <tham_số> trong Telegram. Không thể dùng liên kết đó để mở chat với tham số mà không chạy /start. Chọn cách phù hợp:

  • /start không có câu trả lời thấy rõ: với phản ứng có trình kích hoạt Lệnh /start và Nhãn trong liên kết bắt đầu, để hành động Gửi tin nhắn không có khối. Bot không gửi lời đáp riêng cho /start, nhưng giá trị của nhãn đã nằm trong ngữ cảnh sự kiện để dùng trong điều kiện hoặc hành động của cùng phản ứng.
  • Văn bản điền sẵn: https://t.me/<bot>?text=<văn_bản> (nút Prefilled text hoặc nút liên kết thường) mở chat và đặt nội dung vào ô nhập, không gửi gì. /start không chạy; người dùng tự nhấn Gửi.
  • Tự gửi tin “nhân danh người dùng” khi mở liên kết là điều Bot API không cho phép. Bot không thể gửi dưới tên người dùng. Cách gần nhất là dùng ?start= để phản ứng trả lời bằng tên bot.

Chờ câu trả lời (các bước hội thoại)

Khối văn bản có thể chờ câu trả lời của người dùng. Khi đó, tin nhắn trở thành một bước hội thoại và kịch bản tạm dừng đến lúc có câu trả lời. Nhiều bước liên tiếp tạo thành biểu mẫu ngay trong chat.

Loại nội dung cần chờ

Bot có thể chờ văn bản, chọn phương án qua nút, ảnh, video, video note, âm thanh, tài liệu, tin nhắn thoại, vị trí, liên hệ, lịch hoặc xúc xắc. Nếu người dùng gửi sai loại, bước sẽ coi câu trả lời không phù hợp.

Kiểm tra văn bản

Với câu trả lời bằng văn bản, có thể kiểm tra số điện thoại, email, liên kết, ngày, giờ hoặc khớp công thức. Ví dụ, khi chờ điện thoại, văn bản tùy ý bị từ chối và bot hiển thị thông báo lỗi. Kiểm tra bằng công thức dùng công thức mở rộng: trả chuỗi rỗng để chấp nhận hoặc văn bản lỗi để từ chối.

Lưu câu trả lời

Bạn có thể lưu câu trả lời vào tham số. Sau đó dùng nó trong biến thay thế như {{param.key}} hoặc trong điều kiện. Các bước hội thoại có thể tạo hồ sơ khách hàng đơn giản.

Lỗi, nhắc nhở và thời hạn

  • Tin nhắn khi lỗi kiểm tra: nội dung hiện khi câu trả lời không đạt.
  • Nhắc nhở nếu không có câu trả lời: nội dung gửi khi người dùng im lặng.
  • Hủy chờ câu trả lời theo thời gian chờ: sau bao lâu bot ngừng chờ. Có thể chạy phản ứng khi hết hạn, ví dụ kết thúc biểu mẫu nhẹ nhàng. Trong sơ đồ liên kết, phản ứng khi hết hạn là “Thời gian chờ câu trả lời”, còn phản ứng nhận câu trả lời là “Câu trả lời dự kiến”.

Thoát bước bằng lệnh

/cancel hoặc đúng chữ tiếng Nga отмена sẽ hủy trạng thái chờ và trả lời “Отменено.”; nếu có phản ứng hủy được cấu hình, bot chạy phản ứng đó. Từ tiếng Việt “hủy” không tự kích hoạt chức năng hủy tích hợp này.

Theo mặc định, các lệnh khác được coi như câu trả lời và vẫn phải qua kiểm tra giống văn bản thường. Nếu bật Lệnh bot (ví dụ /start) kết thúc chờ (escape_on_command), mọi lệnh như /start giữa biểu mẫu sẽ âm thầm kết thúc trạng thái chờ rồi chạy như bình thường.

Biến thay thế

Nút Biến thay thế chèn dữ liệu người gửi ({{first_name}}, {{username}}, {{user_id}}), sự kiện ({{text}}, {{chat_id}}, {{datetime}}) và tham số ({{param.key}}). Xem Biến thay thế và công thức để có danh sách và công thức.

Nút menu của bot

Hành động Nút menu chọn menu bot thông thường, menu lệnh hoặc nút Mini App có nhãn và URL. Có thể áp dụng cho chat hiện tại hoặc làm cài đặt chung của bot, chẳng hạn chỉ đặt Mini App riêng cho một khách hàng. Khả năng sử dụng tùy từng kênh.

Tiếp theo