Phát triển bot

Tham chiếu Bot API

Toàn bộ phương thức mà HTTP Bot API của Pabal hỗ trợ, cùng các đối tượng trao đổi và lỗi. Tương thích với Telegram Bot API.

HTTP Bot API của Pabal dùng cùng định dạng địa chỉ, request, phản hồi và lỗi như Telegram Bot API. Tài liệu này chỉ ghi lại những gì Pabal thực sự hỗ trợ. Các phương thức không có ở đây sẽ trả về 404 Not Found: method not found. Nếu bạn mới bắt đầu, hãy xem hướng dẫn tạo bot trước.

Gửi request

https://pabal.me/bot<token>/<phương-thức>

Phương thức HTTP: dùng được cả GET và POST.
Bốn cách gửi tham số — chuỗi truy vấn (?chat_id=1&text=hi), application/x-www-form-urlencoded, application/json, và multipart/form-data khi tải tệp lên. Có thể kết hợp các cách với nhau.
Tham số dạng đối tượng (reply_markup, commands, allowed_updates) được truyền nguyên dạng đối tượng/mảng trong phần thân JSON, còn trong form hay chuỗi truy vấn thì truyền dưới dạng chuỗi JSON.
Tên phương thức không phân biệt chữ hoa chữ thường (sendMessage = sendmessage).
Kích thước phần thân tối đa 12MB (vượt quá thì trả về 413).
Tải tệp xuống dùng địa chỉ riêng https://pabal.me/file/bot<token>/<file_path> (getFile).

Phản hồi và lỗi

Phản hồi luôn là JSON. Nếu thành công thì là HTTP 200 kèm result; nếu thất bại thì là mã trạng thái HTTP tương ứng, kèm error_code trùng với mã đó và description để con người đọc.

{"ok": true, "result": { … }}

{"ok": false, "error_code": 400, "description": "Bad Request: chat not found"}

error_code	Khi nào	Ví dụ description
`400`	Tham số sai	`Bad Request: chat not found`, `Bad Request: message text is empty`, `Bad Request: message is not modified: …`, `Bad Request: message to edit not found`, `Bad Request: wrong file identifier/HTTP URL specified`, `Bad Request: query is too old and response timeout expired or query ID is invalid`
`401`	Token sai	`Unauthorized`
`403`	Không có quyền gửi	`Forbidden: bot can't initiate conversation with a user`, `Forbidden: bot is not a member of the group chat`
`404`	Phương thức hoặc tệp không tồn tại	`Not Found: method not found`
`409`	Gọi getUpdates khi đang có webhook	`Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first`
`413`	Phần thân vượt quá 12MB	`Request Entity Too Large`
`500`	Lỗi nội bộ máy chủ	`Internal Server Error`

Pabal hiện chưa giới hạn tốc độ request (429 Too Many Requests), nhưng điều này có thể thay đổi trong tương lai, vì vậy hãy viết mã sao cho khi nhận 429 thì đợi parameters.retry_after giây rồi gửi lại.

Nhận update

Dùng một trong hai cách. Không thể dùng cả hai cùng lúc.

getUpdates

POST/bot<token>/getUpdates

Lấy các update đang chờ (long polling). Nếu đang thiết lập webhook thì trả về 409.

Tham số	Kiểu	Bắt buộc	Mô tả
`offset`	Integer	Tùy chọn	Chỉ lấy các update có số từ giá trị này trở lên. Những update nhỏ hơn được coi là "đã nhận" và bị xóa. Hãy truyền `update_id + 1` của update cuối cùng đã xử lý.
`limit`	Integer	Tùy chọn	1–100, mặc định 100
`timeout`	Integer	Tùy chọn	Số giây chờ, 0–50, mặc định 0. Nên dùng 25–30.
`allowed_updates`	Array of String	Bỏ qua	Được nhận nhưng không dùng. Muốn lọc theo loại thì hãy lọc sau khi nhận.

Trả về: Array of Update

setWebhook

POST/bot<token>/setWebhook

Nhận update tại một địa chỉ HTTPS. Giải thích chi tiết có trong tài liệu Webhook.

Tham số	Kiểu	Bắt buộc	Mô tả
`url`	String	Có	Địa chỉ công khai https://. Chuỗi rỗng sẽ xóa webhook
`secret_token`	String	Tùy chọn	1–256 ký tự, `A-Z a-z 0-9 _ -`. Được gửi trong header request `X-Telegram-Bot-Api-Secret-Token`
`allowed_updates`	Array of String	Tùy chọn	Chọn trong `message`, `edited_message`, `callback_query`. Để trống là nhận tất cả
`drop_pending_updates`	Boolean	Tùy chọn	Bỏ các update đang chờ
`max_connections`	Integer	Tùy chọn	1–100, mặc định 40. Chỉ được lưu lại; mỗi bot được gửi từng update một
`certificate`	InputFile	Không hỗ trợ	400 — hãy dùng chứng chỉ công khai
`ip_address`	String	Bỏ qua

Trả về: True

deleteWebhook

POST/bot<token>/deleteWebhook

Xóa webhook và quay lại dùng getUpdates. Vẫn thành công kể cả khi không có webhook.

Tham số	Kiểu	Bắt buộc	Mô tả
`drop_pending_updates`	Boolean	Tùy chọn	Bỏ các update đang chờ

Trả về: True

getWebhookInfo

GET/bot<token>/getWebhookInfo

Trạng thái webhook. Không có tham số. Nếu không có webhook thì url là chuỗi rỗng.

Trả về: WebhookInfo

Phương thức

Phương thức	Tác dụng
`getMe`	Thông tin của chính bot
`sendMessage`	Gửi văn bản (kể cả nút bấm)
`sendPhoto`	Gửi ảnh
`editMessageText`	Sửa nội dung và nút của tin nhắn đã gửi
`editMessageCaption`	Sửa chú thích ảnh
`editMessageReplyMarkup`	Chỉ sửa nút
`deleteMessage`	Xóa tin nhắn
`answerCallbackQuery`	Trả lời lượt bấm nút
`sendChatAction`	Hiển thị "đang nhập" (chỉ nhận yêu cầu)
`getChat`	Thông tin cuộc trò chuyện
`getFile`	Đường dẫn tải xuống của ảnh đã nhận
`setMyCommands` · `getMyCommands` · `deleteMyCommands`	Menu lệnh
`logOut` · `close`	Để tương thích (không làm gì cả)
`getUpdates` · `setWebhook` · `deleteWebhook` · `getWebhookInfo`	Nhận update (ở trên)

Giá trị có thể dùng cho chat_id

Với trò chuyện 1:1 là ID của người dùng (số dương), với nhóm thường là ID nhóm (số âm), hoặc tên người dùng của người đó ("@hana_lee"). Tất cả đều có thể biết qua chat.id của update. ID của kênh và siêu nhóm (-100…) hiện chưa có (400 chat not found).

getMe

GET/bot<token>/getMe

Dùng để kiểm tra token có đúng không. Không có tham số.

Trả về: User — với bot có thêm can_join_groups (true), can_read_all_group_messages (true), supports_inline_queries (false), can_connect_to_business (false), has_main_web_app (false).

sendMessage

POST/bot<token>/sendMessage

Tham số	Kiểu	Bắt buộc	Mô tả
`chat_id`	Integer hoặc String	Có	Cuộc trò chuyện cần gửi đến (xem khung ở trên)
`text`	String	Có	1–4.096 ký tự. Được gửi nguyên văn
`reply_markup`	InlineKeyboardMarkup · ReplyKeyboardMarkup · ReplyKeyboardRemove · ForceReply	Tùy chọn	Nút bấm
`disable_notification`	Boolean	Tùy chọn	Gửi không kèm âm thanh
`parse_mode`, `entities`, `reply_parameters`, `link_preview_options` …		Bỏ qua	Được nhận nhưng không dùng. Định dạng không được áp dụng

Trả về: Message đã gửi

Muốn gửi cho một người thì người đó phải nhắn cho bot trước (403 Forbidden: bot can't initiate conversation with a user). Muốn gửi vào nhóm thì bot phải là thành viên của nhóm đó.

sendPhoto

POST/bot<token>/sendPhoto

Tham số	Kiểu	Bắt buộc	Mô tả
`chat_id`	Integer hoặc String	Có	Cuộc trò chuyện cần gửi đến
`photo`	InputFile hoặc String	Có	Tệp tải lên bằng `multipart/form-data` (tối đa 10MB, JPEG, PNG, GIF), hoặc `file_id` của ảnh đã nhận trước đó. Chưa hỗ trợ URL
`caption`	String	Tùy chọn	0–1.024 ký tự
`reply_markup`	Giống sendMessage	Tùy chọn
`disable_notification`	Boolean	Tùy chọn

Trả về: Message đã gửi (có file_id mới trong photo)

editMessageText

POST/bot<token>/editMessageText

Tham số	Kiểu	Bắt buộc	Mô tả
`chat_id`	Integer hoặc String	Có	Cuộc trò chuyện chứa tin nhắn
`message_id`	Integer	Có	Tin nhắn cần sửa (do bot gửi)
`text`	String	Có	Nội dung mới, 1–4.096 ký tự
`reply_markup`	InlineKeyboardMarkup	Tùy chọn	Nút mới. Nếu bỏ đi thì nút sẽ biến mất (giống Telegram)
`inline_message_id`	String	Không hỗ trợ	Chưa có chế độ inline nên trả về 400

Trả về: Message đã sửa. Thay đổi hiện ngay trong ứng dụng; tin nhắn do người dùng sửa sẽ đến bot dưới dạng edited_message.

Nếu nội dung và nút giống hệt trước thì trả về 400 Bad Request: message is not modified: …; nếu cố sửa tin nhắn của người khác thì là 400 Bad Request: message can't be edited.

editMessageCaption

POST/bot<token>/editMessageCaption

Tham số gồm chat_id, message_id, caption (0–1.024 ký tự, bỏ đi thì chú thích bị xóa), reply_markup. Trả về: Message đã sửa.

editMessageReplyMarkup

POST/bot<token>/editMessageReplyMarkup

Giữ nguyên nội dung, chỉ đổi nút. Tham số gồm chat_id, message_id, reply_markup (bỏ đi thì nút bị xóa). Trả về: Message đã sửa.

deleteMessage

POST/bot<token>/deleteMessage

Tham số gồm chat_id, message_id. Xóa tin nhắn ở cả hai phía của cuộc trò chuyện. Nếu tin nhắn không tồn tại thì trả về 400 Bad Request: message to delete not found. Trả về: True.

answerCallbackQuery

POST/bot<token>/answerCallbackQuery

Trả lời nút mà người dùng đã bấm (CallbackQuery). Chỉ có thể trả lời trong vòng 10 giây và một lần duy nhất.

Tham số	Kiểu	Bắt buộc	Mô tả
`callback_query_id`	String	Có	`callback_query.id` của update
`text`	String	Tùy chọn	Dòng chữ hiện thoáng qua ở đầu màn hình
`show_alert`	Boolean	Tùy chọn	Nếu true thì hiện hộp thoại có nút xác nhận
`url`	String	Tùy chọn	Địa chỉ để ứng dụng mở
`cache_time`	Integer	Tùy chọn	Số giây ứng dụng ghi nhớ câu trả lời này

Trả về: True. Nếu quá muộn hoặc đã trả lời rồi thì là 400 Bad Request: query is too old and response timeout expired or query ID is invalid.

sendChatAction

POST/bot<token>/sendChatAction

Được nhận để tương thích và trả về True, nhưng hiện chưa hiển thị "đang nhập…" trong ứng dụng.

getChat

GET/bot<token>/getChat?chat_id=…

Tham số là chat_id (số). Nếu là người thì trả về người đó; nếu là nhóm thì chỉ những nhóm mà bot là thành viên. Trả về: Chat. Nếu không tồn tại hoặc không được xem thì trả về 400 Bad Request: chat not found.

getFile

GET/bot<token>/getFile?file_id=…

Dùng file_id của ảnh đã nhận để lấy đường dẫn tải xuống. Trả về: File. Sau đó tải xuống từ địa chỉ này.

https://pabal.me/file/bot<token>/<file_path>

file_id cũng chính là quyền lấy ảnh đó. Nếu giá trị không hợp lệ thì trả về 400 Bad Request: wrong file identifier/HTTP URL specified.

setMyCommands

POST/bot<token>/setMyCommands

Tham số	Kiểu	Bắt buộc	Mô tả
`commands`	Array of BotCommand	Có	Tối đa 100 lệnh
`language_code`	String	Tùy chọn	Lưu thành danh sách riêng cho ngôn ngữ đó. Hiện ứng dụng chỉ hiển thị danh sách mặc định (không có mã ngôn ngữ)
`scope`	BotCommandScope	Bỏ qua

Trả về: True. Nếu không đúng quy tắc đặt lệnh thì trả về 400 Bad Request: BOT_COMMAND_INVALID.

getMyCommands

GET/bot<token>/getMyCommands

Tham số là language_code (tùy chọn). Trả về: Array of BotCommand.

deleteMyCommands

POST/bot<token>/deleteMyCommands

Tham số là language_code (tùy chọn). Làm trống danh sách đó. Trả về: True.

logOut · close

Trên Telegram, đây là các phương thức dùng khi chuyển sang máy chủ Bot API cục bộ. Pabal không có nơi nào để chuyển sang, nên chỉ nhận yêu cầu và trả về True. Muốn vô hiệu hóa token, hãy dùng /revoke của BotFather.

Đối tượng

tùy chọn bên cạnh một trường nghĩa là trường đó có thể không có. Những trường khác của Telegram không được liệt kê ở đây thì Pabal không gửi.

Update

Một tin mới. Chứa update_id và một trong ba trường dưới đây.

Trường	Kiểu	Mô tả
`update_id`	Integer	Số tăng dần thêm 1. Dùng cho `offset` của getUpdates
`message` tùy chọn	Message	Tin nhắn mới gửi đến bot (1:1, hoặc mọi tin nhắn trong nhóm mà bot là thành viên)
`edited_message` tùy chọn	Message	Tin nhắn đã được sửa
`callback_query` tùy chọn	CallbackQuery	Lượt bấm nút inline

User

Trường	Kiểu	Mô tả
`id`	Integer	ID người dùng (chỉ có nghĩa bên trong máy chủ này)
`is_bot`	Boolean	true nếu là bot
`first_name`	String	Tên. Với tài khoản đã bị xóa là `Deleted Account`
`last_name` tùy chọn	String	Họ
`username` tùy chọn	String	Tên người dùng (không có `@`)

Chat

Trường	Kiểu	Mô tả
`id`	Integer	Với người là ID của người đó (số dương), với nhóm thường là số âm
`type`	String	`private` hoặc `group`
`title` tùy chọn	String	Tên nhóm (group)
`first_name`, `last_name`, `username` tùy chọn	String	Tên và tên người dùng của người kia (private)

Message

Trường	Kiểu	Mô tả
`message_id`	Integer	Số hiệu tin nhắn trong cuộc trò chuyện này
`from` tùy chọn	User	Người gửi
`chat`	Chat	Cuộc trò chuyện chứa tin nhắn
`date`	Integer	Thời điểm gửi (giây Unix)
`edit_date` tùy chọn	Integer	Thời điểm sửa gần nhất
`text` tùy chọn	String	Nội dung văn bản (luôn có nếu không phải tin nhắn ảnh)
`entities` tùy chọn	Array of MessageEntity	Lệnh, lượt nhắc, URL, hashtag trong văn bản
`photo` tùy chọn	Array of PhotoSize	Ảnh (Pabal chỉ có một ảnh gốc)
`caption` tùy chọn	String	Chú thích ảnh
`caption_entities` tùy chọn	Array of MessageEntity	Lệnh, lượt nhắc, URL, hashtag trong chú thích
`reply_markup` tùy chọn	InlineKeyboardMarkup	Các nút inline gắn trên tin nhắn

MessageEntity

Trường	Kiểu	Mô tả
`type`	String	`bot_command`, `mention`, `url`, `hashtag`
`offset`	Integer	Vị trí bắt đầu (tính theo đơn vị mã UTF-16)
`length`	Integer	Độ dài (tính theo đơn vị mã UTF-16)

Máy chủ tự tìm trong văn bản và gắn vào. Các entity định dạng như in đậm, in nghiêng hiện chưa có.

PhotoSize

Trường	Kiểu	Mô tả
`file_id`	String	ID dùng để tải xuống (getFile) và gửi lại (sendPhoto)
`file_unique_id`	String	Cùng một ảnh thì giá trị như nhau dù là bot khác. Không dùng để tải xuống được
`width`, `height`	Integer	Kích thước tính bằng pixel
`file_size`	Integer	Byte

File

Trường	Kiểu	Mô tả
`file_id`, `file_unique_id`	String	Giống PhotoSize
`file_size`	Integer	Byte
`file_path`	String	Có dạng `photos/<file_id>.jpg`. Ghép vào sau `/file/bot<token>/` để tải xuống

CallbackQuery

Trường	Kiểu	Mô tả
`id`	String	ID truyền cho answerCallbackQuery
`from`	User	Người đã bấm nút
`message` tùy chọn	Message	Tin nhắn có gắn nút
`chat_instance`	String	Giá trị đại diện cho cuộc trò chuyện đó
`data` tùy chọn	String	`callback_data` của nút

InlineKeyboardMarkup

inline_keyboard: Array of Array of InlineKeyboardButton — mảng bên ngoài là các hàng, mảng bên trong là các nút của một hàng. Mỗi tin nhắn tối đa 100 hàng và 100 nút.

InlineKeyboardButton

Trường	Kiểu	Mô tả
`text`	String	Chữ trên nút
`callback_data` một trong hai	String	Giá trị gửi đến bot khi bấm, 1–64 byte
`url` một trong hai	String	Địa chỉ mở ra khi bấm

Các loại khác như switch_inline_query, web_app, login_url, pay hiện chưa có (400).

ReplyKeyboardMarkup

Trường	Kiểu	Mô tả
`keyboard`	Array of Array of KeyboardButton	Bảng nút bên dưới ô nhập
`resize_keyboard`, `one_time_keyboard`, `is_persistent`, `selective` tùy chọn	Boolean	Vừa kích thước · ẩn sau một lần dùng · luôn hiển thị · chỉ cho một số người
`input_field_placeholder` tùy chọn	String	Chữ gợi ý trong ô nhập

KeyboardButton

Một chuỗi, hoặc một đối tượng có text cùng các trường tùy chọn request_contact (gửi liên hệ của tôi) và request_location (gửi vị trí của tôi, Boolean).

ReplyKeyboardRemove

{"remove_keyboard": true} — ẩn bảng nút. selective là tùy chọn.

ForceReply

{"force_reply": true} — ứng dụng mở ô nhập ở trạng thái trả lời tin nhắn này. selective, input_field_placeholder là tùy chọn.

BotCommand

Trường	Kiểu	Mô tả
`command`	String	1–32 ký tự gồm chữ Latin thường, chữ số, dấu gạch dưới (không có `/`)
`description`	String	1–256 ký tự

WebhookInfo

Trường	Kiểu	Mô tả
`url`	String	Địa chỉ webhook, chuỗi rỗng nếu không có
`has_custom_certificate`	Boolean	Luôn là false
`pending_update_count`	Integer	Số update đang chờ được chuyển
`ip_address` tùy chọn	String	IP đã gửi đến lần gần nhất
`last_error_date` tùy chọn	Integer	Thời điểm thất bại gần nhất (giây Unix)
`last_error_message` tùy chọn	String	Lý do thất bại gần nhất (danh sách)
`max_connections` tùy chọn	Integer	Giá trị đã truyền cho setWebhook
`allowed_updates` tùy chọn	Array of String	Giá trị đã truyền cho setWebhook

Khác biệt so với Telegram Bot API

Loại update: chỉ có message, edited_message, callback_query. Không có bài đăng kênh, truy vấn inline, thanh toán, bình chọn, thay đổi thành viên (my_chat_member)…
Định dạng: bỏ qua parse_mode và entities, gửi nguyên văn. Chỉ lệnh, lượt nhắc, URL và hashtag được đánh dấu tự động.
Loại cuộc trò chuyện: chỉ có 1:1 và nhóm thường. Không có kênh, siêu nhóm, chủ đề diễn đàn.
Phương tiện: chỉ có ảnh. Không có tài liệu, video, âm thanh, sticker, album, cũng như gửi bằng URL.
Bot trong nhóm: không có chế độ riêng tư, nên bot nhận mọi tin nhắn của nhóm.
Hàng đợi: update chưa lấy được giữ trong bộ nhớ, tối đa 1.000 update gần nhất cho mỗi bot, và mất khi máy chủ khởi động lại (Telegram giữ 24 giờ).
Webhook: gửi lần lượt từng update theo thứ tự (max_connections chỉ được lưu lại), không nhận chứng chỉ tự ký, không giới hạn cổng.
ID: ID người dùng, tin nhắn và tệp chỉ có nghĩa bên trong máy chủ này. Vì không có kênh và siêu nhóm nên cũng không có ID dạng -100….
Phương thức không có: những phương thức không có trong danh sách trên (forwardMessage, copyMessage, sendDocument, sendPoll, getChatMember, banChatMember, answerInlineQuery …) đều trả về 404 Not Found: method not found.