API cho bot
AHV Chat nói đúng ngôn ngữ của Telegram Bot API: cùng địa chỉ, cùng tham số, cùng khuôn trả lời.
Bot anh/chị đã viết cho Telegram chạy được ở đây bằng cách đổi đúng một dòng: địa chỉ máy chủ. Thư viện nào cũng dùng được
(python-telegram-bot, aiogram, grammY, telegraf, node-telegram-bot-api…), hoặc chỉ cần curl.
Giới thiệu
Một bot là một tài khoản do chương trình của anh/chị điều khiển. Người dùng AHV Chat tìm bot theo @username, nhắn cho nó,
và chương trình của anh/chị nhận tin qua getUpdates, trả lời qua sendMessage. Mọi thứ đi qua HTTPS, không cần mở cổng,
không cần tên miền, không cần webhook: máy tính ở nhà, một VPS nhỏ hay một script trên điện thoại đều chạy được.
https://ahvchat.com/bot<token>/<phương thức>;
(2) tin đến lấy bằng getUpdates với timeout tới 50 giây (long polling); (3) chat_id là ID của người
(số dương) hoặc của nhóm (số âm), lấy từ chính update nhận được.Tạo bot và lấy token
- Đăng nhập ahvchat.com (hoặc app), mở menu Tài khoản → Bot của tôi → Tạo bot, đặt tên hiển thị và
@username. - Token hiện đúng một lần, dạng
100123:AbCdEf…. Máy chủ chỉ giữ mã băm, mất token thì bấm Đổi token để lấy token mới (token cũ chết ngay). - Ai cũng nhắn được cho bot của anh/chị khi tìm đúng
@username; bot chỉ có thể nhắn cho người đã từng nhắn cho nó (giống Telegram).
Token là chìa khoá: không đưa vào mã nguồn công khai, không dán lên chat. Đổi token bất cứ lúc nào trong Bot của tôi.
Cách gọi
Mọi phương thức nhận cả GET lẫn POST; tham số đi bằng query string, application/json,
application/x-www-form-urlencoded hoặc multipart/form-data (khi gửi tệp). Tên phương thức không phân biệt hoa thường.
curl "https://ahvchat.com/bot<token>/getMe"
curl -X POST "https://ahvchat.com/bot<token>/sendMessage" -H "Content-Type: application/json" -d '{"chat_id": 100004, "text": "Xin chào từ bot của tôi"}'
Khuôn trả lời luôn là {"ok": true, "result": …}; lỗi là {"ok": false, "error_code": 400, "description": "…"},
kèm parameters.retry_after khi bị giới hạn tần suất.
Với thư viện có sẵn, chỉ đổi địa chỉ gốc:
# python-telegram-bot
Application.builder().token(TOKEN).base_url("https://ahvchat.com/bot").base_file_url("https://ahvchat.com/file/bot").build()
# aiogram
Bot(TOKEN, session=AiohttpSession(api=TelegramAPIServer.from_base("https://ahvchat.com")))
# grammY (Node)
new Bot(TOKEN, { client: { apiRoot: "https://ahvchat.com" } })
# node-telegram-bot-api
new TelegramBot(TOKEN, { polling: true, baseApiUrl: "https://ahvchat.com" })
Nhận tin: getUpdates
Gọi getUpdates với timeout=50: máy chủ giữ kết nối tới khi có update mới rồi trả ngay, nên bot phản ứng
trong vài chục mili giây mà không phải gọi liên tục. Sau khi xử lý, gọi lại với offset = update_id lớn nhất + 1 để
xác nhận; update đã xác nhận sẽ bị xoá khỏi hàng đợi. Update chưa xác nhận được giữ lại và giao lại ở lần gọi sau, kể cả sau khi bot khởi động lại.
offset = 0
while True:
r = requests.get(f"https://ahvchat.com/bot{TOKEN}/getUpdates", params={"offset": offset, "timeout": 50}, timeout=60).json()
for u in r["result"]:
offset = u["update_id"] + 1
if "message" in u and "text" in u["message"]:
chat_id = u["message"]["chat"]["id"]
requests.post(f"https://ahvchat.com/bot{TOKEN}/sendMessage", json={"chat_id": chat_id, "text": "Đã nhận: " + u["message"]["text"]})
Webhook không có: setWebhook với url trả lỗi 400, getWebhookInfo trả pending_update_count
để anh/chị biết còn bao nhiêu update chưa lấy.
Ví dụ đầy đủ: bot echo có nút bấm (Python, 30 dòng)
import requests
API = "https://ahvchat.com/bot" + TOKEN
offset = 0
while True:
for u in requests.get(API + "/getUpdates", params={"offset": offset, "timeout": 50}, timeout=60).json()["result"]:
offset = u["update_id"] + 1
if "message" in u:
m = u["message"]
requests.post(API + "/sendChatAction", json={"chat_id": m["chat"]["id"], "action": "typing"})
requests.post(API + "/sendMessage", json={
"chat_id": m["chat"]["id"],
"text": "Bạn vừa nói: " + m.get("text", "(tệp)"),
"reply_parameters": {"message_id": m["message_id"]},
"reply_markup": {"inline_keyboard": [[
{"text": "Đồng ý", "callback_data": "yes"}, {"text": "Thôi", "callback_data": "no"},
]]},
})
elif "callback_query" in u:
q = u["callback_query"]
requests.post(API + "/answerCallbackQuery", json={"callback_query_id": q["id"], "text": "Đã chọn " + q["data"]})
requests.post(API + "/editMessageText", json={
"chat_id": q["message"]["chat"]["id"], "message_id": q["message"]["message_id"],
"text": "Bạn chọn: " + q["data"],
})
Update
| Trường | Kiểu | Ý nghĩa |
|---|---|---|
update_id | Integer | Tăng dần cho từng bot. Xác nhận bằng offset = update_id + 1. |
message | Message | Tin mới tới bot: chat riêng, hoặc trong nhóm khi bot được @gọi, được trả lời, hoặc nhận lệnh /lenh@bot. |
callback_query | CallbackQuery | Người dùng bấm một nút inline_keyboard dưới tin của bot. |
edited_message | Message | Người dùng sửa một tin đã gửi (có edit_date) — thường là tin bot còn đang xếp hàng; gói bot AHV từ v0.0.395 thay nội dung việc đang chờ bằng tin mới. |
recalled_message | Object | Mở rộng riêng của AHV Chat: người dùng xoá một tin đã gửi (message_id, chat, from, date). Tin chưa tới bot thì bị rút khỏi hàng, bot không thấy; tin đã tới thì bot nên bỏ việc đang xếp hàng cho tin đó. Xoá lịch sử chat thì bot nhận update này cho tối đa 100 tin gần nhất của người dùng trong 24 giờ qua (id không có việc thì bỏ qua). Không có update này cho tin của bot, cho tin trong nhóm hay tin bot chép từ Telegram: xem Tin đã bị xoá. Thư viện Telegram bỏ qua trường lạ (python-telegram-bot để ở update.api_kwargs). |
ahv_host_clean | Object | Mở rộng riêng của AHV Chat: lệnh ngầm, không phải tin nhắn — người xem thẻ máy chủ của bot bấm nút dọn. Chỉ có request_id, from.id, owner, date; không có chữ nào của người bấm. Máy chủ chỉ xếp update này cho bot đã báo can_clean: true bằng setMyHost. Không vào lịch sử chat, không hiện cho người dùng. Xem Máy chủ của bot. |
Message
| Trường | Kiểu | Ý nghĩa |
|---|---|---|
message_id | Integer | Duy nhất trong cuộc trò chuyện. |
date | Integer | Giây Unix. |
chat | Chat | Nơi tin nằm: người (type: "private") hoặc nhóm (type: "supergroup", id âm). |
from | User | Người viết (hoặc chính bot). |
text, entities | String, [MessageEntity] | Nội dung; entities có bot_command cho /lenh và mention cho @tên (offset/length tính theo UTF-16 như Telegram). |
voice / audio | Voice / Audio | Tin thoại và tệp âm thanh, xem Tin thoại; voice.ahv_transcript là chữ của tin; ahv_voice_mode báo tin nói khi đang Gọi thoại. |
photo / document | [PhotoSize] / Document | Tệp đính kèm; caption là lời chú. |
reply_to_message | Message | Tin được trả lời, chỉ một cấp: tin gốc không chứa tiếp reply_to_message. |
reply_markup | InlineKeyboardMarkup | Nút bấm dưới tin của bot. |
media_group_id | String | Các tin cùng một album. |
edit_date | Integer | Có khi tin đã sửa. |
Trả lời một tin không còn (không có, đã bị xoá hoặc thuộc chat khác): allow_sending_without_reply vắng mặt hoặc true thì bỏ phần trả lời và vẫn gửi tin, như trước; bot đặt allow_sending_without_reply bằng false tường minh thì nhận 400 Bad Request: message to be replied not found và không có gì được gửi (xem Tin đã bị xoá). Số sai dạng vẫn trả lỗi cũ. Trường reply của API app không thay đổi đối tượng Message của Bot API.
User và Chat
User: id, is_bot, first_name, username. Chat: id, type
(private hoặc supergroup), title (nhóm), username, first_name. ID người dùng là số dương từ 100001; ID nhóm là số âm
(-1000000000001…). Bot chỉ nhắn được cho người đã nhắn cho nó và nhóm nó là thành viên.
PhotoSize và Document
photo là một mảng một phần tử (ảnh gốc, có width/height) — bot viết cho Telegram lấy photo[-1] là đúng.
document có file_name, mime_type, file_size. Tải tệp về: gọi getFile lấy file_path,
rồi GET https://ahvchat.com/file/bot<token>/<file_path>.
CallbackQuery
id, from (User), message (tin có nút), data (chuỗi callback_data của nút, tối đa 64 byte). Trả lời bằng
answerCallbackQuery trong vòng vài giây, nếu không nút hiện quay mãi cho người dùng.
Phương thức
getMe
Thông tin của chính bot.
Không có tham số.
Trả về: User (kèm can_join_groups: true và ahv_platform; limits.text là trần tin chữ, limits.caption là trần chú thích tệp, xem Bắt đầu trò chuyện).
getUpdates
Lấy update mới, chờ tới timeout giây khi chưa có gì.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
offset | Integer | Xác nhận mọi update có id nhỏ hơn; chúng bị xoá khỏi hàng đợi. |
limit | Integer | 1–100, mặc định 100. |
timeout | Integer | 0–50 giây long polling; 0 = trả ngay. |
Trả về: Mảng Update theo thứ tự update_id.
sendMessage40 tin/giây
Gửi văn bản.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | Người hoặc nhóm. |
text | String | Nội dung. |
parse_mode | String | Markdown, MarkdownV2 hoặc HTML — app hiển thị đậm, mã, khối ```mã``` và liên kết. |
reply_parameters | Object | {"message_id": …} để trả lời một tin (hoặc reply_to_message_id kiểu cũ). Thêm "allow_sending_without_reply": false (trong reply_parameters hoặc ở gốc, như Telegram) để tin được trả lời đã bị xoá trả 400 Bad Request: message to be replied not found thay vì gửi tin không trích; vắng mặt hoặc true thì tin vẫn tới, bỏ trích. Mọi phương thức gửi (sendPhoto, sendVoice, sendMediaGroup…) cũng vậy. Xem Tin đã bị xoá. |
reply_markup | InlineKeyboardMarkup | Nút bấm, xem Nút bấm. |
ahv_choice | ChoiceCard hoặc String JSON | Tuỳ chọn, mở rộng của AHV Chat: thẻ lựa chọn, xem Thẻ lựa chọn. |
ahv_plan_card | String | Tuỳ chọn, mở rộng của AHV Chat, chỉ chat riêng: plan_id của kế hoạch hiện tại — app vẽ tin thành thẻ kế hoạch, chữ vẫn lưu đủ cho app cũ. Không khớp thì bị bỏ qua lặng lẽ, tin vẫn gửi. Xem Kế hoạch sống. |
ahv_kind | String | Tuỳ chọn, mở rộng của AHV Chat: receipt (biên nhận) hoặc status (dòng trạng thái) — app hiện nhỏ, mờ và không bao giờ đọc to. Giá trị khác bị bỏ qua. Tin bắt đầu bằng “Em đã nhận. Vị trí hàng đợi: N” được coi là receipt khi bot không đánh dấu. |
Trả về: Message vừa gửi.
sendPhoto
Gửi ảnh: tải lên trực tiếp (multipart) hoặc dùng lại file_id bot đã gửi/nhận.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | |
photo | InputFile hoặc String | Phần multipart tên photo, attach://tên, hoặc file_id. |
caption | String | Lời chú, có parse_mode. |
reply_parameters | Object | |
reply_markup | InlineKeyboardMarkup |
Trả về: Message.
curl -F chat_id=100004 -F caption="Ảnh chụp màn hình" -F photo=@shot.png "https://ahvchat.com/bot<token>/sendPhoto"sendDocument
Gửi tệp bất kỳ (tên và kiểu MIME giữ nguyên).
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | |
document | InputFile hoặc String | Như photo. |
caption | String | |
ahv_file_receipt | String | Mở rộng của AHV Chat: biên nhận kho của tệp lớn (thay cho tệp/file_id), xem Tệp lớn qua kho. |
Trả về: Message.
sendVideo
Gửi video (.mp4, .mov, .m4v, .webm): app hiện khung video có nút ▶ và phát ngay trong tin, như Telegram. Được lưu như một tệp: Message trả về có document. Gửi .mp4 bằng sendDocument cũng phát được.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | |
video | InputFile hoặc String | Như photo. |
caption | String | |
ahv_file_receipt | String | Mở rộng của AHV Chat: biên nhận kho của tệp lớn (thay cho tệp/file_id), xem Tệp lớn qua kho. |
Trả về: Message.
sendVoice
Gửi tin nhắn thoại, như Telegram: OGG/Opus, hoặc MP3/M4A/WAV/FLAC/WebM — máy chủ đổi về OGG/Opus 48 kHz mono. Tối đa 15 phút và 20 MB (lớn hơn: 413; không phải âm thanh hay dài quá: 400). file_id dùng lại được nếu là tin thoại/âm thanh trong các chat của chính bot. Không kèm ahv_transcript thì máy chủ tự chuyển chữ ở nền để người dùng đọc lướt.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | |
voice | InputFile hoặc String | Như photo. |
caption | String | |
duration | Integer | Bỏ qua: máy chủ tự đo. |
ahv_transcript | String hoặc Object | Tuỳ chọn, mở rộng của AHV Chat: chữ của tin (≤ 10 000 ký tự), chuỗi hoặc {"text", "language"}; có thì máy chủ không tự chuyển chữ. |
Trả về: Message có voice (duration, mime_type audio/ogg, ahv_transcript khi đã có chữ).
sendAudio
Gửi tệp âm thanh (nhạc, bản ghi dài): giữ nguyên tệp, tối đa 60 phút và 20 MB; không tự chuyển chữ.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | |
audio | InputFile hoặc String | Như photo. |
caption | String | |
title | String | ≤ 64 ký tự. |
performer | String | ≤ 64 ký tự. |
ahv_file_receipt | String | Mở rộng của AHV Chat: biên nhận kho của tệp lớn (thay cho tệp/file_id), xem Tệp lớn qua kho. |
Trả về: Message có audio. Nhiều tệp âm thanh cùng lúc: album sendMediaGroup với "type": "audio".
ahvCreateUploadmở rộng
Mở rộng của AHV Chat: xin vé tải một tệp trên 50 MB tới 500 MB thẳng lên kho tệp của người nhận. Gửi JSON. Chỉ chat riêng với người đã nhắn bot (như sendDocument; nhóm → 400); người nhận chưa có kho → 404 “Người nhận chưa có kho tệp; tối đa 50 MB”; ≤ 50 MB → 400 (gửi multipart như thường); quá 500 MB hoặc người nhận hết hạn mức → 413; kho của người nhận vừa đổi trong lúc xin vé → 409, gọi lại.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | |
size | Integer | Số byte của tệp. |
name | String | Tên tệp. |
mime | String | Kiểu MIME. |
kind | String | document, video (lưu như tệp) hoặc audio (dùng với sendAudio). |
Trả về: {"upload_id", "url", "ticket", "chunk": 8388608, "expires_in": 1800}.
ahvRenewUploadmở rộng
Mở rộng của AHV Chat: vé mới cho lượt tải bot này đã tạo (vé sống 30 phút). Kho giữ phần đã nhận: hỏi HEAD để biết tải tiếp từ đâu.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
upload_id | String | Từ ahvCreateUpload. |
Trả về: Như ahvCreateUpload. Lượt tải của bot khác hay của app → 404.
ahvSetVoiceTranscript
Mở rộng của AHV Chat: bot trả chữ của một tin thoại người dùng gửi mà chưa có chữ (máy chủ chưa chuyển được). Chỉ bot của chat đó; tin đã có chữ hoặc người dùng đã tự sửa chữ → 409. App hiện chữ ngay; bot không nhận update nào vì việc này.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | |
message_id | Integer | Tin thoại của người dùng. |
text | String | 1–10 000 ký tự. |
language | String | Tuỳ chọn: vi, en… |
Trả về: True.
sendMediaGroup
Gửi album 2–10 ảnh/video/tệp, người dùng thấy chúng cạnh nhau như Telegram.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | |
media | [InputMedia] | Mỗi phần tử {"type": "photo"|"video"|"document", "media": "attach://p1", "caption": …}; tệp đi kèm là phần multipart p1… Video được lưu như tệp (như sendVideo) và phát ngay trong tin. {"type": "audio", "media": …, "caption": …, "title": …, "performer": …} (InputMediaAudio) là một tệp âm thanh, giữ và kiểm như sendAudio (≤ 60 phút, title/performer ≤ 64 ký tự, thời lượng và mime_type do máy chủ đo); như Telegram, audio chỉ gộp với audio — trộn với ảnh/video/tệp trả 400 Bad Request. App hiện mỗi tệp một hàng trình phát trong cùng bong bóng. |
Trả về: Mảng Message cùng một media_group_id (album âm thanh: mỗi Message có audio). Album chỉ được lưu khi mọi tệp hợp lệ và còn chỗ.
editMessageText
Sửa văn bản tin của bot. Không gửi kèm reply_markup thì nút bấm bị gỡ (như Telegram). Đổi chữ một tin bot luôn nhớ thì trả 400 (đổi nút thì được). Xem Bot luôn nhớ.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | |
message_id | Integer | |
text | String | |
parse_mode | String | |
reply_markup | InlineKeyboardMarkup | |
ahv_choice | ChoiceCard hoặc String JSON | Tuỳ chọn, mở rộng của AHV Chat: thẻ lựa chọn, xem Thẻ lựa chọn. |
ahv_kind | String | Tuỳ chọn: receipt hoặc status, như ở sendMessage; không gửi thì giữ như cũ. |
Trả về: Message đã sửa (app hiện “đã sửa” khi chữ đổi).
editMessageReplyMarkup
Chỉ đổi nút bấm — không hiện “đã sửa”.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | |
message_id | Integer | |
reply_markup | InlineKeyboardMarkup | Bỏ trống để gỡ nút. |
ahv_choice | ChoiceCard hoặc String JSON | Tuỳ chọn, mở rộng của AHV Chat: thẻ lựa chọn, xem Thẻ lựa chọn. |
Trả về: Message.
deleteMessage
Xoá tin của bot; biến mất ngay trên mọi thiết bị của người dùng. Tin đã bị xoá trả 400 Bad Request: message to delete not found. Người dùng cũng xoá được tin của bot (nhóm: chủ nhóm và quản trị viên); không có update khi người dùng xoá tin của bot, xem Tin đã bị xoá. Tin bot luôn nhớ thì trả 400, chỉ người dùng gỡ được. Xem Bot luôn nhớ.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | |
message_id | Integer |
Trả về: true.
sendChatActionmở rộng
Ba dấu chấm “đang soạn” trong 5 giây. Mở rộng của AHV Chat: bot làm việc lâu có thể nói rõ đang làm gì và từ lúc nào.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | |
action | String | typing, upload_photo, upload_document… |
ahv_status | String | Tuỳ chọn, tới 160 ký tự: dòng trạng thái hiện cạnh ba dấu chấm, ví dụ “Đang chạy test 12/40”. |
ahv_started_at | Integer | Tuỳ chọn, giây Unix lúc bắt đầu việc: app hiện đồng hồ đếm thời gian đã làm. |
ahv_jobs | [Job] hoặc String JSON | Tuỳ chọn, tới 12 việc bot chạy độc lập ngoài lượt chat, cũ nhất trước (gửi nhiều hơn thì 12 việc đầu vẫn hiện, việc thứ 13 trở đi bị cắt): {"id": …, "title": …≤60, "status": …≤160, "started_at": giây Unix}; id tuỳ chọn, theo ^[A-Za-z0-9_-]{1,16}$ (id sai thì chỉ bỏ id, việc vẫn hiện) — app dùng nó để ghép bước hiện tại vào đúng việc trong kế hoạch. Cả trường ≤ 65 536 ký tự: chuỗi đếm đúng từng ký tự như gửi; mảng trong thân JSON đếm như json.dumps mặc định viết ra, chữ ngoài ASCII thành \uXXXX — đúng cách python-telegram-bot viết, nên mảng và chuỗi PTB cho cùng kết quả. Đủ cho 12 mục dài nhất kể cả toàn emoji và số token; quá trần thì cả trường bị bỏ qua, không đọc. App hiện mục “Làm độc lập” dưới ba dấu chấm; phần tử sai kiểu bị bỏ qua. |
ahv_turn | Boolean | Đi cùng ahv_jobs: 1 khi lượt chat đang chạy (ahv_status là việc của lượt), 0 khi chỉ còn việc độc lập. |
Trả về: true.
Mỗi việc trong ahv_jobs có thể thêm model (nhãn, gộp khoảng trắng, ≤ 24 ký tự),
fam (claude, gpt, grok, gemini, ahv) và tok (object).
Trong tok: i là mọi token vào gồm cache; o là token ra gồm suy nghĩ; cr đọc cache, cw ghi cache, r phần suy nghĩ.
Các số này là số nguyên 0…1013; n là số lượt gọi 0…107, không nhận bool, chuỗi hay số thập phân. Chỉ giữ số được gửi, không tự thêm số 0; không có số thì không gửi ba khoá mới.
at là giờ cập nhật Unix, cùng luật đồng hồ: không quá 120 giây trong tương lai và không cũ hơn 7 ngày; sai thì bỏ riêng giờ, giữ số.
Metadata trong tok: mid (id model gốc, ≤ 48 ký tự), eff (effort/Fast, ≤ 24), sub (số model agent phụ, số nguyên 0…99).
Khoá lạ bị bỏ; nhãn/hãng/metadata sai chỉ mất trường đó. Số đếm hoặc kiểu tok sai thì chỉ bỏ tok, việc vẫn còn. Máy chủ cũ và app cũ bỏ qua khoá mới.
Mỗi việc có thể thêm eta (object): dự kiến xong do bot tính từ lịch sử đo được trên máy của bot; máy chủ chỉ lọc và giữ, không nhận lịch sử.
m bắt buộc là range (cần a ≤ c ≤ b), before (chỉ có b),
wait (cần wait; có thể không kèm giờ, chỉ kèm b hoặc đủ a, c, b),
late hoặc run (không có a, c, b).
a, c, b là giây Unix đã làm tròn ở bot (đầu xuống 5 phút, giữa gần nhất 5 phút, cuối lên 5 phút),
trong khoảng từ started_at − 60 tới giờ máy chủ + 7 ngày; thiếu giờ bắt đầu hợp lệ thì cận dưới là giờ máy chủ − 30 ngày.
at bắt buộc là giây Unix lúc tính, trong ±1 giờ quanh giờ máy chủ.
Các số đều là số nguyên, không nhận bool, chuỗi hay số thập phân. Các trường sau tuỳ chọn, chỉ giữ khi được gửi:
typ (trung vị thời lượng), tl/th (P25/P75, để hiện “thường mất X – Y”) trong 0…30 ngày; các giá trị có mặt phải theo thứ tự tl ≤ typ ≤ th;
n là số việc giống 0…10 000; src là hist, hist+step, hist+hint hoặc hint;
step là hai số nguyên [k, n] với 0 ≤ k ≤ n ≤ 999; why là chuỗi, gộp khoảng trắng và cắt còn 80 ký tự;
wait là thời gian chờ còn lại, lớn hơn 0 và không quá 7 ngày.
Khoá lạ bị bỏ. Một khoá đã biết sai kiểu/giá trị thì bỏ cả eta, việc và tok vẫn còn. Bot không gửi eta thì sự kiện giữ y như trước.
Chỉ lịch sử → before; bot chỉ gửi range khi có bước/gợi ý và bậc hiệu chỉnh đã đạt ≥ 70 %. Bong bóng, dòng kế hoạch và Telegram giữ nguyên.
{"id": "3f2a91c0", "title": "Tóm tắt tài liệu", "status": "xong phần 3", "started_at": 1790869800,
"tok": {"i": 12000, "o": 3000},
"eta": {"m": "range", "a": 1790870400, "c": 1790871000, "b": 1790871900,
"typ": 1440, "tl": 900, "th": 2400, "n": 23, "src": "hist+step", "step": [3, 5], "why": "", "at": 1790869920}}setMessageReaction
Gắn một biểu tượng cảm xúc lên tin.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | |
message_id | Integer | |
reaction | [ReactionType] | [{"type": "emoji", "emoji": "👍"}]; mảng rỗng để gỡ. |
Trả về: true.
answerCallbackQuery
Trả lời một cú bấm nút.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
callback_query_id | String | |
text | String | Tới 200 ký tự, hiện thoáng qua. |
show_alert | Boolean | Hiện thành hộp thoại thay vì thoáng qua. |
Trả về: true.
setMyCommands
Danh sách lệnh: người dùng gõ / trong ô soạn là thấy gợi ý. getMyCommands và deleteMyCommands đi kèm.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
commands | [BotCommand] | Tới 100 mục {"command": "help", "description": "Hướng dẫn"}. |
Trả về: true.
setMyDescription
Mô tả bot — dòng chữ người dùng thấy trên thẻ giới thiệu bot, trước khi bấm Bắt đầu (thẻ giới thiệu từ app 0.0.33; hôm nay app hiện bản mặc định). Như Telegram: một bản mặc định (không có language_code, cũng chính là mô tả bot hiện trong app; sau này chủ bot sửa được ngay trong app) và tới 16 bản riêng theo ngôn ngữ. Từ app 0.0.33, app hiện bản đúng ngôn ngữ người dùng (vi/en), thiếu thì bản mặc định; hôm nay app hiện bản mặc định. Chữ có từ ngữ không phù hợp (cùng bộ lọc với tên bot và mô tả nhóm) bị từ chối: 400 Bad Request: description contains objectionable words, không ghi gì. AHV Chat hiện đúng chữ bot đặt, không chèn thêm gì.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
description | String | Tới 512 ký tự (đếm theo ký tự, chữ có dấu vẫn là một). Bỏ trống hoặc chuỗi rỗng: xoá bản của ngôn ngữ đó (không có language_code thì xoá bản mặc định). Dài hơn → 400 Bad Request: description is too long, không cắt lặng lẽ. |
language_code | String | Tuỳ chọn: hai chữ thường ISO 639-1 (vi, en…); bỏ trống là bản mặc định. Sai dạng (VI, vie…) → 400 Bad Request: language_code is invalid; quá 16 ngôn ngữ → 400 Bad Request: too many description languages. |
Trả về: true.
curl https://ahvchat.com/bot<token>/setMyDescription -d language_code=en \
-d description="The assistant that connects AHV Chat to every AI platform"getMyDescription
Đọc lại mô tả của một ngôn ngữ. Không lùi về bản mặc định (như Telegram): ngôn ngữ chưa đặt trả chuỗi rỗng — bot đặt mô tả lúc khởi động nên hỏi từng ngôn ngữ và chỉ đặt khi đang trống, để không ghi đè chữ chủ bot đã sửa.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
language_code | String | Tuỳ chọn, như setMyDescription; bỏ trống là bản mặc định. |
Trả về: {"description": "…"} (BotDescription), chưa đặt thì "".
curl "https://ahvchat.com/bot<token>/getMyDescription?language_code=vi"
{"ok": true, "result": {"description": ""}}getFile
Đường dẫn tải một tệp bot đã nhận hoặc gửi.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
file_id | String |
Trả về: {file_id, file_unique_id, file_size, file_path}; tải tại https://ahvchat.com/file/bot<token>/<file_path>.
getChat
Thông tin một người hoặc một nhóm bot đang ở.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer |
Trả về: Chat (nhóm có thêm description). Người hoặc nhóm có ảnh đại diện thì kèm photo {small_file_id, small_file_unique_id, big_file_id, big_file_unique_id} (128 và 512 px) như Telegram. pinned_message: tin ghim mới nhất (Message), không có thì không có khoá — như Telegram.
setChatPhoto
Như Telegram về tên, nhưng bot không bao giờ đổi được ảnh chat: ảnh nhóm chỉ chủ nhóm (một người) đổi trong app, kể cả bot trưởng nhóm cũng không. setChatPhoto và deleteChatPhoto luôn trả 400 Bad Request: not enough rights to change chat photo. Đọc ảnh nhóm bằng getChat (photo).
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | |
photo | InputFile | Chỉ setChatPhoto; không được dùng. |
Trả về: Không bao giờ thành công.
pinChatMessage
Ghim một tin trong chat riêng. Như Telegram: bot ghim được mọi tin của chat, của người dùng hay của chính bot; ghim lại tin đã ghim đưa nó lên đầu. Trong nhóm bot không ghim được. Ghim lại một tin bot luôn nhớ thì dấu nhớ vẫn giữ; bot không đặt được dấu. Xem Bot luôn nhớ.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | |
message_id | Integer | |
disable_notification | Boolean | Nhận nhưng không có tác dụng: AHV Chat không báo khi ghim. |
Trả về: true.
unpinChatMessage
Bỏ ghim một tin. Không có message_id thì bỏ tin ghim mới nhất không phải tin bot luôn nhớ (không có tin nào để bỏ vẫn trả true); có message_id mà là tin nhớ thì trả 400. Xem Bot luôn nhớ.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | |
message_id | Integer | Tuỳ chọn. |
Trả về: true.
unpinAllChatMessages
Bỏ mọi tin ghim của chat, trừ tin bot luôn nhớ (bot không bỏ được tin nhớ). Xem Bot luôn nhớ.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer |
Trả về: true.
getChatPinsmở rộng
Danh sách tin ghim, mới nhất trước (với remember_only: cũ nhất trước).
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | Chat riêng hoặc nhóm (số âm). |
remember_only | Boolean | Chỉ tin người dùng đánh “Bot luôn nhớ” (nhóm luôn rỗng). |
offset | Integer | Mặc định 0. |
limit | Integer | 1–100, mặc định 100. |
if_etag | String | Khớp etag hiện tại thì chỉ trả {"etag":…,"not_modified":true}, không kèm danh sách (chỉ chat riêng; nhóm luôn trả đủ). Etag so với cả danh sách theo bộ lọc, không theo trang (offset/limit). |
Trả về: {"etag","total","remember_count","remember_chars","pins":[{"message","pinned_by","pinned_date","ahv_remember"}]}. etag: 16 ký tự hex, đổi khi ghim, bỏ ghim, ghim lại, đổi cờ nhớ hay sửa chữ một tin ghim. total đếm theo bộ lọc. Trong nhóm pinned_by là User của người ghim (đã rời nhóm: chỉ id, tên "Thành viên cũ").
setChatPlanmở rộng · 30 lần mỗi phút mỗi chat
Đặt kế hoạch sống của một chat riêng. Mỗi chat có một kế hoạch; mỗi lần gửi mang toàn bộ kế hoạch kèm revision tăng dần, nên gửi lại hay gửi trùng đều an toàn. Quy tắc ghi, khuôn và lỗi: xem Kế hoạch sống.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | Chat riêng (id người dùng). Nhóm trả 400 Bad Request: plans are only for private chats. |
plan | Plan hoặc String JSON | Kế hoạch ahv_plan phiên bản 1, sau chuẩn hoá tới 256 KiB. |
Trả về: {"plan_id", "revision", "applied"}. applied: false khi cùng plan_id mà revision không mới hơn bản đang lưu (không phải lỗi; revision trả về là bản đang lưu). Bot bị người dùng chặn nhận 403 Forbidden: bot was blocked by the user.
getChatPlanmở rộng · 60 lần mỗi phút
Kế hoạch đang lưu của một chat riêng — đúng khuôn máy chủ đã chuẩn hoá. Bot bị chặn vẫn đọc được.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | Chat riêng (nhóm trả 400). |
Trả về: Plan, hoặc null khi chat chưa có kế hoạch.
getUserProfilePhotos
Ảnh đại diện của một người hoặc bot, như Telegram.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
user_id | Integer | |
offset | Integer | Không bắt buộc, mặc định 0. |
Trả về: {total_count, photos}: 0 hoặc 1 ảnh (ảnh đang dùng), mỗi ảnh là mảng PhotoSize 128 và 512 px; tải bằng getFile như tệp thường. Ảnh cũng công khai ở https://ahvchat.com/avatars/<khoá>-<128|512>.<jpg|png>.
getChatMember
Vai trò của một thành viên trong nhóm (creator, administrator, member). Kèm getChatAdministrators và getChatMemberCount.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
chat_id | Integer | ID nhóm (âm). |
user_id | Integer |
Trả về: ChatMember.
setMyUsagemở rộng · 6 lần mỗi phút
Báo hạn mức của tài khoản AI mà bot đang chạy (gói, phần đã dùng của từng cửa sổ, lúc đặt lại). App hiện nó trong trang thông tin bot, chỉ cho chủ bot và những người bot liệt kê. Mỗi lần gọi thay toàn bộ lần trước. getMyUsage (không tham số) trả lại đúng những gì đã lưu, hoặc null. Xem Hạn mức tài khoản.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
usage | Usage hoặc String JSON | Báo cáo hạn mức, tới 4 KB. Bỏ trống, null hoặc chuỗi rỗng = gỡ báo cáo. |
visible_to | [Integer] | Tuỳ chọn, tới 20 người: id tài khoản AHV Chat được xem, ngoài chủ bot. Mặc định rỗng — chỉ chủ bot thấy. |
Trả về: true; getMyUsage trả {usage, visible_to} hoặc null.
setMyHostmở rộng · 6 lần mỗi phút
Báo CPU và ổ đĩa của máy đang chạy bot, và việc dọn máy bot đang làm. App hiện nó trong trang thông tin bot, chỉ cho chủ bot và những người bot liệt kê. Mỗi lần gọi thay toàn bộ lần trước. getMyHost (không tham số) trả lại đúng những gì đã lưu, hoặc null. Xem Máy chủ của bot.
| Tham số | Kiểu | Ý nghĩa |
|---|---|---|
host | Host hoặc String JSON | Báo cáo máy, tới 2048 byte. Bỏ trống, null hoặc chuỗi rỗng = gỡ báo cáo. |
visible_to | [Integer] | Như setMyUsage: tới 20 id tài khoản AHV Chat được xem, ngoài chủ bot. Mặc định rỗng. |
Trả về: true; getMyHost trả {host, visible_to} hoặc null.
Các phương thức còn lại
getWebhookInfo (số update đang chờ), deleteWebhook (với drop_pending_updates=true xoá sạch hàng đợi),
setWebhook (chỉ chấp nhận url rỗng), logOut, close (trả true, để thư viện không lỗi).
Phương thức chưa có trả 404 Not Found: method not found.
Nút bấm dưới tin
reply_markup.inline_keyboard là mảng các hàng, mỗi hàng là mảng nút. Nút có text và một trong hai:
callback_data (tới 64 byte → bot nhận callback_query) hoặc url (mở liên kết). Người dùng bấm xong, bot
answerCallbackQuery rồi thường editMessageText để ghi lại lựa chọn. Trong app, ngoài bấm nút, người dùng còn có thể
chọn rồi viết thêm lời nhắn — bot nhận một tin văn bản có nội dung nút kèm ghi chú.
{"inline_keyboard": [
[{"text": "Triển khai ngay", "callback_data": "deploy"}, {"text": "Chờ sau 22 giờ", "callback_data": "later"}],
[{"text": "Xem hướng dẫn", "url": "https://ahvchat.com/docs/api"}]
]}
Thẻ lựa chọn
Tham số mở rộng ahv_choice của sendMessage, editMessageText, editMessageReplyMarkup (chat riêng lẫn nhóm): đi kèm
reply_markup, không thay cho nó — bàn phím vẫn là thứ chính, bấm thẻ đi qua đúng callback_data của nút; app vẽ mỗi phương án
thành một thẻ có thể kèm % gợi ý. Telegram và app cũ bỏ qua tham số này: nó không có trong Message kiểu Telegram (thư viện Telegram để trường lạ
sang một chỗ riêng hoặc bỏ hẳn), chỉ app AHV Chat mới đọc và vẽ thẻ.
{"v": 1,
"options": [{"data": "clpick:3f9a0c2e71b4:0", "label": "Rải theo đợt"},
{"data": "clpick:3f9a0c2e71b4:1", "label": "Rải cả đội một lượt"}],
"recommended": 0, "state": "scored", "scores": [66, 34], "source": "AHVjev", "picked": null, "listed": false}
| Trường | Kiểu | Ý nghĩa (sai → bỏ trường, không bao giờ làm hỏng lời gọi) |
|---|---|---|
v | Integer | Luôn 1; khác → bỏ cả ahv_choice. |
options | [Option] | 2–8 phương án {"data", "label"}. data: chuỗi ≤ 64 byte, phải trùng callback_data của một nút đứng riêng một hàng trong reply_markup của chính tin (lúc gửi, hoặc lúc sửa nếu có kèm bàn phím); thiếu, thừa hay trùng data thì bỏ cả ahv_choice. label: chữ phương án sạch (không ⭐, không số thứ tự, không %), các khoảng trắng liên tiếp gộp còn một, cắt còn ≤ 512 ký tự. |
recommended | Integer hoặc null | Chỉ số trong options, hoặc null. |
state | String | Một trong pending, scored, off, picked; giá trị lạ → off. |
scores | [Integer] | Đúng số phần tử của options, mỗi số nguyên 0–100, tổng đúng 100; sai → bỏ scores, và state: "scored" hạ thành "off". |
source | String | Tới 32 ký tự; dài hơn 32 ký tự hoặc rỗng (kể cả thiếu) thì về mặc định AHVjev nguyên vẹn — không bị cắt còn 32 ký tự đầu. |
picked | Integer | Chỉ số phương án đã chọn; chỉ có nghĩa khi state: "picked" — thiếu, hoặc state khác, thì bị bỏ. state: "picked" mà picked thiếu hoặc sai thì state tự hạ thành "scored" (còn scores hợp lệ) hoặc "off". |
listed | Boolean | true khi bot đã tự viết "1. … 2. …" vào cuối chữ của tin. |
| Cả trường | — | Gửi dạng object hoặc chuỗi JSON thô; chuỗi thô dài quá 65 536 ký tự thì không đọc. Sau khi lọc, object viết gọn (không khoảng trắng thừa, ensure_ascii=False) đo được quá 8 192 byte UTF-8 thì bỏ cả ahv_choice. |
Sửa một tin đã có thẻ
Không gửi ahv_choice khi sửa → giữ nguyên thẻ đã lưu. Gửi ahv_choice hợp lệ mà chữ và bàn phím không đổi → vẫn là một lần sửa
hợp lệ (không trả lỗi "message is not modified"), và không đặt edit_date — chỉ chữ đổi mới đặt edit_date
(app hiện "đã sửa"). So danh sách data với thẻ đã lưu là so theo đúng thứ tự: thêm, bớt, đổi phương án,
hay chỉ đổi chỗ hai phương án cho nhau cũng đều là khác danh sách →
bỏ phần sửa ahv_choice, chữ và bàn phím vẫn sửa bình thường, thẻ giữ nguyên bản cũ. Sửa mà gỡ hẳn bàn phím (không còn
reply_markup, ví dụ bước "đã chọn") trong khi tin chưa có thẻ nào được lưu từ trước thì cũng bỏ luôn phần ahv_choice
của lần sửa này — không có gì để đối chiếu. Tin do ahv_mirror_from ghi sang (tin người dùng chép từ kênh phụ)
không bao giờ mang ahv_choice.
curl -X POST "https://ahvchat.com/bot<token>/sendMessage" -H "Content-Type: application/json" -d '{
"chat_id": 100004, "text": "Rải việc thế nào?",
"reply_markup": {"inline_keyboard": [[{"text": "Theo đợt", "callback_data": "clpick:3f9a0c2e71b4:0"}],
[{"text": "Cả đội một lượt", "callback_data": "clpick:3f9a0c2e71b4:1"}]]},
"ahv_choice": {"v": 1, "options": [{"data": "clpick:3f9a0c2e71b4:0", "label": "Theo đợt"},
{"data": "clpick:3f9a0c2e71b4:1", "label": "Cả đội một lượt"}],
"state": "pending"}
}'
curl -X POST "https://ahvchat.com/bot<token>/editMessageReplyMarkup" -H "Content-Type: application/json" -d '{
"chat_id": 100004, "message_id": 501,
"reply_markup": {"inline_keyboard": [[{"text": "Theo đợt", "callback_data": "clpick:3f9a0c2e71b4:0"}],
[{"text": "Cả đội một lượt", "callback_data": "clpick:3f9a0c2e71b4:1"}]]},
"ahv_choice": {"v": 1, "options": [{"data": "clpick:3f9a0c2e71b4:0", "label": "Theo đợt"},
{"data": "clpick:3f9a0c2e71b4:1", "label": "Cả đội một lượt"}],
"recommended": 0, "state": "scored", "scores": [66, 34]}
}'
Trạng thái đang làm việc
Bot AI thường làm việc nhiều phút. Gửi sendChatAction mỗi 4–5 giây với ahv_status (đang làm gì) và
ahv_started_at (bắt đầu lúc nào): người dùng thấy ba dấu chấm, dòng trạng thái và đồng hồ đếm — biết bot còn sống và đang ở bước nào,
thay vì một màn hình im lặng. Việc chạy riêng ngoài lượt chat (bản dựng, tác vụ dài) gửi kèm trong ahv_jobs, mỗi việc một dòng
tên, thời gian đã chạy và bước hiện tại; ahv_turn=0 khi lượt chat đã xong mà việc vẫn chạy.
Bot Telegram thuần gửi action như cũ, không cần đổi gì.
Hạn mức tài khoản
Bot chạy bằng một tài khoản AI (Claude, Codex, Grok…) có hạn mức theo phiên và theo tuần. Bot báo con số đó bằng setMyUsage;
người được xem bấm vào tên bot trong chat là thấy thẻ “Hạn mức tài khoản đang chạy”: mỗi cửa sổ một thanh (xanh / vàng từ 80% / đỏ khi đầy 100%, khớp trạng thái “gần hết” / “hết”),
còn bao lâu thì đặt lại, và cập nhật cách đây bao lâu — số cũ hơn 30 phút thì mờ đi và ghi rõ. Nên báo lúc khởi động, sau mỗi việc, khi đổi tài khoản
và vài phút một lần; lấy số từ chỗ bot đã có sẵn, đừng hỏi nhà cung cấp mỗi lần báo (họ trả 429).
Usage — mọi trường khác bị từ chối kèm tên trường, để gõ nhầm không lọt âm thầm:
| Trường | Kiểu | Ý nghĩa |
|---|---|---|
provider | String | Bắt buộc, một trong claude, codex, grok, antigravity, gemini, ahv, other. |
plan | String | Tuỳ chọn, tới 32 ký tự: tên gói, ví dụ “Max 20x”. |
account | String | Tuỳ chọn, tới 64 ký tự: tài khoản đã che, ví dụ va•••@gmail.com (tên hiện tối đa 3 chữ). E-mail đầy đủ bị từ chối. |
status | String | ok, warning, exhausted, error (mặc định ok): bình thường, gần hết, hết, không đọc được hạn mức. |
note | String | Tuỳ chọn, tới 120 ký tự: ghi chú ngắn, ví dụ lý do không đọc được. |
windows | [Window] | Tới 6 cửa sổ hạn mức, hiện theo đúng thứ tự gửi. |
updated_at | Integer | Giây Unix lúc số liệu được đọc (không phải lúc gửi); mặc định bây giờ. Sau giờ máy chủ (đồng hồ máy bot chạy nhanh) thì được tính là bây giờ; không cũ hơn 30 ngày. |
Window: label (bắt buộc, tới 32 ký tự: “Phiên 5 giờ”, “Tuần”, “Tuần · Fable”), used_percent (bắt buộc, số 0–100; lưu một chữ số thập phân, chưa đầy thì không bao giờ làm tròn lên 100),
resets_at (tuỳ chọn, giây Unix, trong 90 ngày tới), note (tuỳ chọn, tới 60 ký tự).
curl -H 'Content-Type: application/json' "https://ahvchat.com/bot<token>/setMyUsage" -d '{
"usage": {"provider": "claude", "plan": "Max 20x", "account": "va•••@gmail.com", "status": "ok",
"windows": [{"label": "Phiên 5 giờ", "used_percent": 42, "resets_at": 1790008000},
{"label": "Tuần", "used_percent": 61, "resets_at": 1790300000}],
"updated_at": 1790000000},
"visible_to": [100002]}'
visible_to thấy báo cáo; người khác nhận
null như thể bot chưa báo gì. Máy chủ từ chối mọi chuỗi trông như khoá hay token (sk-…, xai-…, JWT,
chuỗi liền từ 24 ký tự chữ-số trở lên, kể cả viết bằng chữ toàn khổ), ký tự điều khiển hay vô hình, và e-mail không che (kể cả viết liền mà thiếu đuôi tên miền, ten@gmail, hay nấp sau một tên đã che, x•@ten@gmail.com; Hỏi @bot, (@ahv_support) thì không phải e-mail). Đây là lưới an toàn, không phải bộ lọc tuyệt đối (chữ na ná của bảng chữ khác, e-mail viết thành chữ “at”… vẫn có thể lọt): bot tự che trước khi gửi và không bao giờ đưa token hay khoá vào báo cáo. Báo cáo nằm ở máy nhà của bot
và đi theo bot khi chuyển nhà. App đọc nó ở GET /api/v1/chats/<bot_id>/usage (máy nhà của bot, như lịch sử chat), trả
{usage, host, now} (host xem ở Máy chủ của bot).Máy chủ của bot
Bot báo CPU và ổ đĩa của máy mà nó chạy bằng setMyHost (tách khỏi setMyUsage); getMyHost đọc lại. Cả hai là phương thức mở rộng của AHV Chat,
cùng hạn mức với phần hạn mức tài khoản: 6 lần mỗi phút (setMyHost) và 30 lần mỗi phút (getMyHost) mỗi bot, quá thì 429 với parameters.retry_after: 10.
Chủ bot và người trong visible_to thấy thẻ “Máy chủ của bot”; người khác không phân biệt được bot có báo hay không. Báo cáo nằm ở máy nhà của bot và đi theo bot khi chuyển nhà.
App đọc ở GET /api/v1/chats/<bot_id>/usage, trả {usage, host, now}.
Host — chỉ có số, giá trị đúng/sai và giá trị thuộc danh sách đóng, tới 2048 byte; không có tên máy, địa chỉ mạng, tên người dùng hệ điều hành, đường dẫn, tên tệp hay số tiến trình. Trường lạ bị từ chối kèm tên trường (host.<trường>):
| Trường | Kiểu | Ý nghĩa |
|---|---|---|
v | Integer | Bắt buộc, bằng 1. |
cpu | Object | Bắt buộc: percent (0–100, một chữ số thập phân), cores (1–4096). |
disk | Object | Bắt buộc: used_bytes, total_bytes (số nguyên byte), percent (0–100). |
sampled_at | Integer | Bắt buộc, giây Unix lúc đo; sau giờ máy chủ thì được tính là bây giờ; không cũ hơn 30 ngày. |
can_clean | Boolean | Bắt buộc: bot này nhận được lệnh dọn. Bot không báo true thì nút dọn không bao giờ có hiệu lực. |
clean | Object | Tuỳ chọn (vắng = idle), chỉ state bắt buộc: state idle, running, done, failed, stuck; trigger manual, auto95, cpu90;
reason timeout, ai_unavailable, nothing_safe, interrupted, updating, error (ở failed, stuck và ở done khi lượt xong nhưng thiếu một phần);
request_id, by_other, started_at, finished_at, freed_bytes, disk_before_percent, disk_after_percent, dry. |
clean.items | [Item] | Tới 8 mục {kind, bytes}, không lặp kind; kind thuộc pkg_cache, build_cache, old_logs, tmp_files, old_cli, old_work, sys_cache, containers, bot_procs, other. Riêng bot_procs: bytes = 0, thêm count (1–9999, bắt buộc) và cpu (0–100, tuỳ chọn). |
clean.left | [Left] | Tới 5 mục {kind, bytes} bot để lại; kind thuộc owner_data, database, media, other_user, in_use, unknown. |
Máy chủ trả cho app đúng thứ bot gửi, cộng ba giá trị do máy chủ tính (bot gửi lên thì bị từ chối như trường lạ): stale: true khi báo cáo cũ hơn 15 phút;
clean_wait (số giây còn phải chờ mới bấm lại được, 0 = bấm được); và clean thành requested khi có lệnh chưa được bot nhận trong 2 phút (quá 2 phút thì failed với reason: not_received).
Bot được coi là đã nhận lệnh khi clean.request_id trùng, hoặc clean.started_at không cũ hơn lệnh, hoặc clean.state là running.
curl -H 'Content-Type: application/json' "https://ahvchat.com/bot<token>/setMyHost" -d '{
"host": {"v": 1, "cpu": {"percent": 37.5, "cores": 4},
"disk": {"used_bytes": 126701535232, "total_bytes": 207232647168, "percent": 61.1},
"sampled_at": 1790000000, "can_clean": true},
"visible_to": [100002]}'
Lệnh dọn: ahv_host_clean
Người xem bấm nút dọn thì bot nhận một update ahv_host_clean qua getUpdates: lệnh ngầm, không phải tin nhắn, chỉ có request_id,
from.id, owner, date. Không có chữ tự do nào từ người bấm tới bot; máy chủ không đọc thân yêu cầu. Máy chủ chỉ xếp update cho bot đang báo can_clean: true,
báo cáo còn mới, không đang dọn và đã qua thời gian chờ; có cờ tắt khẩn cấp thì không xếp gì. Bot gắn request_id vào clean của lượt dọn để máy chủ biết đã nhận.
Tin thoại
AHV Chat có tin thoại như Telegram, thêm chữ dưới bong bóng và nút loa 🔊 trên tin trả lời. Bot cũ không cần sửa gì: tin thoại của người dùng tới bot
đúng như Telegram (message.voice), thư viện bot Telegram hiểu sẵn.
Bot nhận tin thoại của người dùng
Người dùng ghi âm trong app. Máy chủ lưu một khuôn duy nhất, OGG/Opus 48 kHz mono, rồi tự chuyển chữ. Update tới bot sau khi có chữ hoặc sau tối đa 15 giây,
nên bot khỏi tự chuyển chữ; hết 15 giây mà chưa có chữ thì update không kèm ahv_transcript hoặc kèm status failed, bot có thể tự chuyển rồi gọi ahvSetVoiceTranscript.
Người dùng sửa chữ dưới tin của mình, hoặc bấm “Thử lại” và có chữ, thì bot nhận edited_message với ahv_transcript mới, xử lý như tin chữ bị sửa.
{"message_id": 812, "chat": {"id": 100002, "type": "private"}, "from": {"id": 100002, "is_bot": false, "first_name": "Hiếu"},
"voice": {"file_id": "AHVvo1c…", "file_unique_id": "AQADvo1c…", "duration": 12, "mime_type": "audio/ogg", "file_size": 46213,
"ahv_transcript": {"status": "ok", "text": "Nhờ bot xem giúp lỗi deploy tối qua", "language": "vi"}},
"ahv_voice_mode": true}
| Trường | Ý nghĩa |
|---|---|
voice.duration | Giây, làm tròn. Tệp tối đa 15 phút và 20 MB. |
voice.ahv_transcript | Mở rộng của AHV Chat. status: ok (có text, thường có language), empty (không có lời), failed (chưa chuyển được), off (máy chủ tắt chuyển chữ hoặc người dùng tắt tự chuyển chữ). Không có trường này = máy chủ chưa biết chữ: bot tự chuyển như với Telegram. |
ahv_voice_mode | true nếu người dùng nói tin này khi đang Gọi thoại: nên trả lời ngắn, dễ nghe; mã, đường dẫn, bảng gửi riêng. Bot bỏ qua cũng không sao. ahv_platform.features liệt kê voice và voice_mode. |
Tải tệp: getFile trả file_path dạng voices/<file_id> (tin thoại) hoặc audios/<file_id> (tệp âm thanh), rồi GET https://ahvchat.com/file/bot<token>/<file_path>.
Bot gửi tin thoại
curl https://ahvchat.com/bot<token>/sendVoice -F chat_id=100002 -F voice=@tra-loi.ogg -F caption="Đã xong" -F 'ahv_transcript={"text": "Đã xong, lỗi do thiếu biến môi trường", "language": "vi"}'
voice: OGG/Opus (như Telegram) hoặc MP3, M4A, WAV, FLAC, WebM; máy chủ đổi về OGG/Opus. Dài quá 15 phút hoặc không phải âm thanh →400; quá 20 MB (hoặc người dùng hết hạn mức lưu trữ) →413; máy chủ chưa cài ffmpeg →503“Máy chủ chưa cài ffmpeg.”; đĩa máy chủ sắp đầy →507. Mộtfile_iddùng lại được nếu là tin thoại/âm thanh trong các chat của chính bot (tin thoại của người dùng gửi lại cho họ không bị chuyển chữ lại).- Không kèm
ahv_transcriptthì máy chủ tự chuyển chữ ở nền (không chặn lời gọi): app hiện chữ khi xong. Cóahv_transcript(chuỗi, hoặc{"text", "language"}, ≤ 10 000 ký tự) thì máy chủ dùng chữ đó, không gọi AI. sendAudiocho nhạc và bản ghi dài (≤ 60 phút, giữ nguyên tệp, cótitle/performer≤ 64 ký tự): phát bằng cùng trình phát, không có sóng âm và không tự chuyển chữ. Bot nhận lại làmessage.audio.ahvSetVoiceTranscript(chat_id, message_id, text, language?): trả chữ cho tin thoại của người dùng mà máy chủ chưa chuyển được. Không tạo update cho bot. Chỉ chat riêng (nhóm → “message not found”) và chỉ bot của chat đó.409nếu tin đã có chữ hoặc người dùng đã tự sửa.
Nút loa 🔊 và tin không đọc
Khi người dùng gửi tin thoại, máy chủ tự gắn nút loa vào mọi tin chữ bot gửi sau đó cho tới tin kế tiếp của người dùng (cờ voice_reply nằm ở API của app; bot không phải làm gì).
Bấm loa thì máy chủ đọc to nội dung tin đó, bỏ khối mã, bảng, đường dẫn và mọi thứ trông như bí mật. Tin đánh dấu ahv_kind là receipt (biên nhận) hoặc status (dòng trạng thái)
được vẽ nhỏ, mờ và không có loa (tham số của sendMessage và editMessageText). Tin bắt đầu bằng “Em đã nhận. Vị trí hàng đợi: N” tự được coi là receipt.
Tin nhắn thoại N giây.ogg (hoặc Tin nhắn thoại M phút SS giây.ogg từ 1 phút). Chữ được chuyển bằng dịch vụ AI riêng của AHV Chat, nên đừng đọc bí mật vào tin thoại như bạn vẫn không nên gõ nó vào tin chữ.Tệp lớn qua kho
Một yêu cầu multipart tối đa 95 MB và mỗi tệp tối đa 50 MB. Tệp/video/âm thanh lớn hơn, tới 500 MB, bot tải thẳng lên kho tệp của người nhận
(như app vẫn làm), từng khúc 8 MiB, rồi gửi tin bằng biên nhận kho. Máy chủ có đường này thì ahv_platform.features có store_upload và
limits.big_file_bytes = 524288000; không có thì giữ trần 50 MB.
ahvCreateUpload(JSON{"chat_id", "size", "name", "mime", "kind"}) →{"upload_id", "url", "ticket", "chunk": 8388608, "expires_in": 1800}.PUT urltừng khúc ≤chunkbyte, theo thứ tự, đầuAuthorization: AHV-Upload <ticket>vàContent-Range: bytes <đầu>-<cuối>/<size>. Đứt giữa chừng:HEAD url(cùngAuthorization) trảUpload-Offsetlà số byte kho đã nhận, tải tiếp từ đó. Vé hết hạn (401):ahvRenewUpload. Khúc cuối trả{"receipt": "…"}.sendDocument/sendVideo/sendAudiovớiahv_file_receiptthay cho tệp, kèmcaption,parse_mode,reply_parameters,reply_markupnhư thường. Biên nhận chỉ dùng được một lần, chỉ cho đúng người nhận và đúng bot đã tạo lượt tải (khác →403; dùng lại →409; sai/hết hạn →400); tệp âm thanh chỉ quasendAudio.
import httpx
API = "https://ahvchat.com/bot<token>"
data = open("phim.mp4", "rb").read()
up = httpx.post(f"{API}/ahvCreateUpload", json={"chat_id": 100004, "size": len(data), "name": "phim.mp4",
"mime": "video/mp4", "kind": "video"}).json()["result"]
for start in range(0, len(data), up["chunk"]):
piece = data[start:start + up["chunk"]]
r = httpx.put(up["url"], content=piece, timeout=120, headers={"Authorization": "AHV-Upload " + up["ticket"],
"Content-Range": f"bytes {start}-{start + len(piece) - 1}/{len(data)}"})
httpx.post(f"{API}/sendVideo", json={"chat_id": 100004, "ahv_file_receipt": r.json()["receipt"], "caption": "Bản dựng"})
Tệp lớn gửi kiểu này không dùng lại được bằng file_id (trần 50 MB của đường thường vẫn áp dụng) và chưa gửi được vào nhóm. Bot ở máy chủ theo vùng gọi qua https://ahvchat.com như mọi lệnh chat riêng.
Bắt đầu trò chuyện và ahv_platform
Khi người dùng bấm Bắt đầu (hoặc gõ /start) trong chat riêng với bot, tin /start tới bot mang thêm trường ahv_platform
ngay trong message; getMe cũng trả trường này (không có language, vì getMe không gắn với người dùng nào), nên bot đang chạy từ trước biết mình ở AHV Chat mà không cần đợi ai bấm.
Tin trong nhóm, tin trả lời lồng bên trong, tin đã sửa và mọi tin khác không có trường này. Đối tượng chỉ nói về AHV Chat: không có gì về người dùng ngoài language
(vi hoặc en, tiếng người dùng đang dùng trong app; không rõ thì vi).
{
"v": 1,
"name": "AHV Chat",
"docs": "https://ahvchat.com/docs/api",
"language": "vi",
"markdown": [
"bold",
"code",
"pre",
"heading",
"link"
],
"limits": {
"text": 32768,
"caption": 4096,
"file_bytes": 52428800,
"big_file_bytes": 524288000,
"album": 10,
"callback_data_bytes": 64,
"choice_options": 8,
"commands": 100,
"pins": 1000
},
"features": [
"files",
"albums",
"inline_buttons",
"choice",
"edit",
"delete",
"chat_action",
"work_status",
"reactions",
"commands",
"reply",
"pins",
"remember",
"plans",
"groups",
"recall",
"usage",
"host",
"voice",
"voice_mode",
"store_upload"
]
}
Khoá features | Ứng với |
|---|---|
files | sendDocument, sendPhoto, sendVideo, getFile |
albums | sendMediaGroup |
inline_buttons | answerCallbackQuery |
choice | ahv_choice |
edit | editMessageText, editMessageReplyMarkup |
delete | deleteMessage |
chat_action | sendChatAction |
work_status | ahv_status, ahv_jobs |
reactions | setMessageReaction |
commands | setMyCommands, getMyCommands, deleteMyCommands |
reply | sendMessage |
pins | pinChatMessage, unpinChatMessage, unpinAllChatMessages, getChatPins |
remember | getChatPins |
plans | setChatPlan, getChatPlan |
groups | getChat, getChatMember, getChatAdministrators, getChatMemberCount |
recall | recalled_message |
usage | setMyUsage, getMyUsage |
host | setMyHost, getMyHost, ahv_host_clean |
voice | sendVoice, sendAudio, ahvSetVoiceTranscript, ahv_transcript, ahv_kind |
voice_mode | ahv_voice_mode |
store_upload | ahvCreateUpload, ahvRenewUpload, ahv_file_receipt |
remember: máy chủ có Bot luôn nhớ (getChatPins nhận remember_only/if_etag; bot không gỡ được tin nhớ).
v đổi khi một khoá đổi nghĩa; thêm khoá mới thì v giữ nguyên, nên bot hãy bỏ qua khoá lạ. markdown là những dấu app thật sự vẽ
(chữ nghiêng, bảng và danh sách hiện thành chữ thường). limits là các trần máy chủ đang áp dụng.
Khoá limits | Trần | Ý nghĩa |
|---|---|---|
text | 32768 | Tin chữ của bot. |
caption | 4096 | Chú thích tệp của bot. |
Giới hạn chữ đếm theo điểm mã Unicode (một emoji như 😀 = 1), trên chữ thô gửi lên, kể cả dấu Markdown và thẻ HTML.
Thư viện Telegram bỏ qua trường lạ. python-telegram-bot để trường này ở update.message.api_kwargs["ahv_platform"], và ở context.bot.bot.api_kwargs
sau khi gọi get_me; aiogram và grammY bỏ qua nó, không lỗi. Bot Telegram thuần không cần đổi gì.
language để chào đúng tiếng khi nhận /start. Đừng in lại đối tượng cho người dùng:
đó là thông tin cho bot, không phải lời chào. Địa chỉ tài liệu luôn là https://ahvchat.com/docs/api.Nhóm
Người dùng tạo nhóm trong app và thêm bot vào. Bot nhận tin trong nhóm khi được @username gọi, khi tin trả lời một tin của bot,
hoặc khi có lệnh /lenh@username; chat.id âm và chat.type là supergroup. Bot trả lời vào nhóm bằng đúng
chat_id đó. getChat, getChatMember, getChatAdministrators, getChatMemberCount cho biết nhóm và thành viên.
Một bot gọi bot khác trong nhóm phải @tên — trả lời không @ thì bot kia không nhận, để hai bot không nhại nhau vô tận.
Máy chủ theo vùng
Bot có thể được đặt “nhà” ở máy chủ gần người dùng (ví dụ Singapore). Gọi https://ahvchat.com luôn đúng: máy gốc tự chuyển tiếp tới nhà của bot.
Muốn nhanh hơn, hỏi GET https://ahvchat.com/api/v1/bothome/<bot_id> để biết địa chỉ nhà rồi gọi thẳng vào đó; nếu bot chuyển nhà,
máy chủ trả 421 kèm parameters.home là nhà mới (gọi lại qua https://ahvchat.com là luôn đúng). Trong lúc chuyển (vài giây) máy chủ trả 503 với Retry-After: 5.
Lệnh nêu tên một nhóm luôn gọi https://ahvchat.com: nhóm chỉ sống ở máy gốc. Đó là các lệnh có chat_id của nhóm (số âm bắt đầu bằng -100) trong
sendMessage, editMessageText, editMessageReplyMarkup, deleteMessage, sendChatAction, getChat, getChatMemberCount,
pinChatMessage, unpinChatMessage, unpinAllChatMessages, getChatPins, và mọi lời gọi getChatMember, getChatAdministrators.
answerCallbackQuery cũng gọi máy gốc khi callback_query_id có tiền tố group:: đó là nút inline trong nhóm, câu hỏi được giữ ở máy gốc dù bot chuyển nhà. ID câu hỏi chat riêng giữ nguyên và được trả lời ở nhà bot.
Gọi thẳng máy nhà ở vùng thì nhận 421 kèm parameters.home là https://ahvchat.com — lệnh chưa chạy, gọi lại qua https://ahvchat.com.
Ghim tin
pinChatMessage, unpinChatMessage, unpinAllChatMessages, getChatPins (xem bốn phương thức ở trên) hoạt động
như Telegram. Ai ghim được gì, rút gọn từ đặc tả:
| Ai | Chat riêng người–bot | Nhóm |
|---|---|---|
| Người dùng của chat | Ghim hoặc bỏ ghim mọi tin. | Chủ nhóm, quản trị viên (owner, admin): ghim hoặc bỏ ghim. Thành viên: chỉ xem. |
| Bot của chat | Ghim hoặc bỏ ghim mọi tin của chat, của người dùng hay của chính bot, trừ tin bot luôn nhớ (xem Bot luôn nhớ): bot không bỏ ghim được tin nhớ. | Bot không ghim được trong nhóm, kể cả bot trưởng nhóm (leader) — chỉ đọc bằng getChatPins/getChat. Cố ghim hay bỏ ghim trả
400 Bad Request: not enough rights to manage pinned messages in the chat. |
Bot bị người dùng chặn vẫn đọc tin ghim được (getChatPins), nhưng ghim hoặc bỏ ghim trả 403 Forbidden: bot was blocked by the user.
Trong nhóm, bot chỉ thấy tin ghim do một bot viết, hoặc do người đã đồng ý chia sẻ với chính bot ấy (hay không cần đồng ý: bot của họ).
Tin ghim khác coi như không có với bot đó: không có trong getChatPins, không tính vào total/etag, và getChat.pinned_message
là tin ghim mới nhất mà bot ấy được thấy.
Mỗi chat (riêng hoặc nhóm) tối đa 1.000 tin ghim; vượt trần trả 400 Bad Request: too many pinned messages. Ghim một tin không còn tồn tại trả
400 Bad Request: message to pin not found; bỏ ghim một tin không đang ghim trả 400 Bad Request: message to unpin not found.
pinChatMessage, unpinChatMessage, unpinAllChatMessages tính chung 20 lần mỗi phút mỗi bot; getChatPins riêng
60 lần mỗi phút mỗi bot. Quá thì 429 kèm parameters.retry_after.
total trong kết quả getChatPins đếm theo đúng bộ lọc của lần gọi đó (cả chat hoặc chỉ remember_only), không phải tổng cả chat.
Trường ahv_remember của mỗi tin cho biết người dùng có đánh dấu "Bot luôn nhớ" hay không (xem ngay dưới).
Không có thông báo đẩy khi ghim, và cũng không có tin dịch vụ "đã ghim" như Telegram.
Ghim, bỏ ghim hay đọc tin ghim của nhóm luôn gọi https://ahvchat.com, kể cả khi bot có nhà ở máy chủ vùng (xem trên); chat riêng thì gọi đâu cũng được.
curl https://ahvchat.com/bot<token>/pinChatMessage -d chat_id=123 -d message_id=456
Bot luôn nhớ
Người dùng có thể đánh dấu một tin ghim là "Bot luôn nhớ": bot đọc lại tin ấy ở đầu mỗi lượt gọi mô hình, dù nó đã trôi khỏi 100 tin ghim gần nhất.
Chỉ người dùng đặt và gỡ được dấu này, và chỉ trong chat riêng người–bot. Tối đa 10 tin nhớ mỗi chat, tổng cộng 4.000 ký tự (tính theo chữ hiện tại của tin);
tin không có chữ thì không đánh dấu được. Nhóm không có tin nhớ: remember_only trong nhóm luôn trả danh sách rỗng.
Bot đọc bằng getChatPins với remember_only=true (cũ nhất trước) và if_etag: giữ etag lần trước, lần sau gửi lại, nếu không có gì đổi thì
nhận not_modified và dùng bản đã lưu. Sửa chữ một tin nhớ cũng đổi etag.
Bot không đặt và không gỡ được. pinChatMessage không nhận tham số nào để đặt dấu (có gửi cũng bị bỏ qua), ghim lại một tin nhớ thì dấu vẫn còn.
unpinAllChatMessages bỏ mọi tin ghim trừ tin nhớ; unpinChatMessage không có message_id bỏ tin mới nhất không phải tin nhớ. Các việc dưới đây trả 400:
| Bot làm | Lỗi |
|---|---|
unpinChatMessage có message_id, hoặc deleteMessage, một tin nhớ | 400 Bad Request: message is pinned with ahv_remember; only the user can unpin it |
editMessageText đổi chữ một tin nhớ | 400 Bad Request: message is pinned with ahv_remember; only the user can change it |
Đổi nút hay ahv_choice mà giữ nguyên chữ thì vẫn được. Gói bot hay bot bên thứ ba gặp 400 này khi sửa chữ một tin người dùng đã đánh dấu nhớ
(ví dụ thêm dòng "✅ Đã chọn" vào tin đó) thì nên bỏ qua, hoặc chỉ đổi nút. Người dùng vẫn bỏ ghim và bỏ nhớ được mọi tin, và xoá được tin của mình.
Ví dụ khối đệm phía bot (python, gọn):
cache = {} # chat_id -> (etag, nho)
def doc_nho(chat_id):
etag, nho = cache.get(chat_id, (None, []))
r = api("getChatPins", chat_id=chat_id, remember_only=True, if_etag=etag or "")
if not r.get("not_modified"):
etag, nho = r["etag"], [p["message"].get("text", "") for p in r["pins"]]
cache[chat_id] = (etag, nho)
return nho # dán vào đầu mỗi lượt gọi mô hình
Kế hoạch sống
Bot làm việc dài (dựng, review, lên máy…) cho người dùng thấy mình đang làm gì, còn gì chờ, cái gì vừa xong bằng một kế hoạch: app vẽ nó đứng đầu
thanh ghim và trong một bảng riêng, với màu trạng thái, đồng hồ sống và bước hiện tại. Mỗi chat riêng có một kế hoạch tổng chạy liên tục, chia nhóm
theo luồng việc (vd “Gói bot”, “App”, “iPhone”); việc đóng (xong/huỷ) app tự thu gọn vào mục “Đã xong” sau 24 giờ. Chỉ có ở chat riêng, không có ở nhóm.
Là mở rộng của AHV Chat: gọi setChatPlan / getChatPlan.
Vì sao là một đối tượng, không phải một tin ghim. (1) Kế hoạch đổi hàng chục lần mỗi giờ: là tin thì mỗi lần đổi thành một lần sửa tin, lịch sử bẩn và bộ đếm chưa đọc bị động tới.
(2) Máy chủ giữ dữ liệu có kiểu (trạng thái, mốc giờ, id việc), app vẽ đúng mà không phải đoán từ chữ. (3) Mỗi lần gửi mang cả kế hoạch kèm revision tăng dần,
nên mất hay lặp một lần gửi cũng tự lành — không cần vá từng việc theo đúng thứ tự.
{
"v": 1,
"plan_id": "p7f3a2c1",
"revision": 214000000,
"created_at": 1790346520,
"updated_at": 1790456530,
"groups": [
{"id": 1, "title": "Gói bot"},
{"id": 2, "title": "App AHV Chat"}
],
"items": [
{"id": 41, "group": 1, "title": "Dựng gói 0.0.405", "status": "doing",
"created_at": 1790455900, "started_at": 1790456280,
"job": {"id": "3f09aa12", "state": "running", "started_at": 1790456280}},
{"id": 44, "group": 1, "title": "Review độc lập gói 0.0.405", "status": "pending", "created_at": 1790455900},
{"id": 45, "group": 1, "title": "Publish canary + thử thật", "status": "pending",
"note": "chờ review ĐẠT", "created_at": 1790455900},
{"id": 36, "group": 1, "title": "Log hạn mức flush", "status": "done",
"created_at": 1790430000, "started_at": 1790436000, "ended_at": 1790440600},
{"id": 34, "group": 2, "title": "Thư mục chat: duyệt đặc tả", "status": "pending",
"note": "chờ anh duyệt", "created_at": 1790440000}
],
"unfiled": [
{"title": "Chạy trọn bộ test", "job": {"id": "7c1e90ab", "state": "running", "started_at": 1790455770}}
]
}
Plan — máy chủ chuẩn hoá theo đúng thứ tự khoá dưới đây, bỏ khoá lạ, và getChatPlan trả lại bản đã chuẩn hoá:
| Trường | Kiểu | Quy tắc |
|---|---|---|
v | Integer | Luôn là 1; khác thì 400 Bad Request: unsupported plan version. |
plan_id | String | 8 ký tự a-z0-9, cố định suốt đời sổ kế hoạch của chat. Gửi một plan_id khác nghĩa là bot đã lập sổ lại: bản mới thay bản cũ. |
revision | Integer | 1 … 253−1, tăng mỗi lần kế hoạch đổi. |
created_at, updated_at | Integer | Tuỳ chọn, giây Unix. Mốc sai (trước năm 2020, hay quá 2 phút sau giờ máy chủ) bị bỏ lặng lẽ, không báo lỗi — như mọi mốc giờ trong kế hoạch. |
groups | [Group] | Tới 20 nhóm, thứ tự mảng là thứ tự trên bảng. Group: id (1…999, không trùng), title (tới 40 ký tự, không rỗng). |
items | [Item] | Tới 400 việc (mở + đóng còn giữ), trong đó tới 200 việc mở (pending, doing, review, deployed). Trong mỗi nhóm, thứ tự mảng là thứ tự làm. |
unfiled | [{title, job}] | Tuỳ chọn: việc chạy độc lập của bot chưa gắn vào việc nào (app hiện trong nhóm “Chưa xếp”). Tới 30 mục, thừa thì cắt; title tới 60 ký tự; mục thiếu job hợp lệ bị bỏ. |
Item: id (1…999 999, không trùng), group (bắt buộc, id của một nhóm trong groups), title (tới 120 ký tự, không rỗng),
status (bảng dưới), note (tuỳ chọn, tới 200 ký tự — với việc chờ, ghi chờ gì: “chờ anh duyệt”), created_at, started_at, ended_at
(tuỳ chọn; app dùng ended_at để thu gọn việc đóng sau 24 giờ — việc đóng không có ended_at coi như đã quá 24 giờ), job (tuỳ chọn).
Job: id (theo ^[A-Za-z0-9_-]{1,16}$, cùng id bot gửi trong ahv_jobs của sendChatAction),
state — một trong running, done, failed, lost, stopped — và tuỳ chọn started_at, ended_at, exit_code (số hoặc null).
Job còn nhận model, fam, tok theo cùng quy tắc của việc độc lập, cả trong items và unfiled; số cuối được lưu cùng kế hoạch, việc xong vẫn giữ số chốt.
eta theo cùng quy tắc dự kiến xong, chỉ giữ khi state là running, cả trong items và unfiled.
Mọi chữ một dòng: khoảng trắng được gộp, quá dài thì cắt, không báo lỗi.
status | Nghĩa | Khi nào |
|---|---|---|
pending | Chờ | Chưa bắt đầu (kể cả việc đang chờ người dùng — ghi lý do vào note). |
doing | Đang làm | Bot đang làm, hoặc việc chạy độc lập gắn với việc này đang chạy. Có job.state là failed/lost/stopped thì app hiện nhãn đỏ “Lỗi”. |
review | Đang review | Chờ hoặc đang review độc lập. |
deployed | Đã lên máy | Đã lên máy thật, còn chờ kiểm hay thử thật. |
done | Xong | Xong và đã kiểm. |
cancelled | Huỷ | Không làm nữa. |
Quy tắc ghi của setChatPlan (mỗi chat đúng một kế hoạch):
- Chat chưa có kế hoạch → lưu,
applied: true. - Cùng
plan_id,revisionlớn hơn bản đang lưu → thay,applied: true. - Cùng
plan_id,revisionnhỏ hơn hoặc bằng → không ghi,applied: falsekèmrevisionđang lưu. Đây không phải lỗi: gửi lại an toàn. plan_idkhác → bản mới thay bản cũ bất kểrevision, và kế hoạch hiện lại nếu người dùng đã ẩn nó khỏi thanh ghim (hidden).
Mỗi lần applied: true app của người dùng nhận kế hoạch mới ngay. Người dùng ẩn hay hiện kế hoạch trên thanh ghim là việc của app; bot không nhận update nào về chuyện đó.
Thẻ kế hoạch trong chat. sendMessage với ahv_plan_card=<plan_id> (chat riêng) gửi một tin mà app vẽ thành thẻ của kế hoạch — nên gửi kèm chữ tóm tắt
(“📋 Kế hoạch · 2 đang làm · 5 chờ”) vì app cũ và thư viện khác chỉ thấy chữ. Máy chủ chỉ nhận khi plan_id đúng là kế hoạch hiện tại của chính chat đó; không khớp thì bỏ
tham số lặng lẽ, tin vẫn gửi như tin chữ thường.
Bước hiện tại của một việc không nằm trong kế hoạch (nó đổi vài giây một lần): gửi nó trong ahv_jobs của sendChatAction với cùng id như job.id
— app ghép bước đó vào đúng việc, hoặc vào mục của nó trong “Chưa xếp”.
Lỗi của setChatPlan / getChatPlan | Khi nào |
|---|---|
400 Bad Request: plans are only for private chats | chat_id là nhóm (cả hai phương thức). |
400 Bad Request: chat not found | Người này chưa từng nhắn với bot, hoặc là chat của bot khác (cả hai phương thức). |
403 Forbidden: bot was blocked by the user | Người dùng đã chặn bot: setChatPlan không ghi gì; getChatPlan vẫn đọc được. |
400 Bad Request: can't parse plan | plan gửi dạng chuỗi mà không phải JSON đọc được. |
400 Bad Request: plan is invalid: <trường> | Một trường sai, kèm vị trí: plan_id, revision, groups[0].title, items[3].group… |
400 Bad Request: unsupported plan version | v khác 1. |
400 Bad Request: plan has too many open items | Quá 200 việc mở. |
400 Bad Request: plan has too many items | Quá 400 việc. |
400 Bad Request: plan has too many groups | Quá 20 nhóm. |
400 Bad Request: plan is too big | Kế hoạch sau chuẩn hoá quá 256 KiB (262 144 byte UTF-8), hoặc plan gửi dạng chuỗi dài quá 1048576 ký tự (từ chối, không đọc). Kế hoạch thường 10–30 KiB; bớt việc đóng cũ hay rút gọn ghi chú. |
429 kèm parameters.retry_after | setChatPlan quá 30 lần mỗi phút cho một chat; getChatPlan quá 60 lần mỗi phút mỗi bot. setChatPlan còn tính chung trần 40 lần mỗi giây mỗi bot với các lệnh gửi (429 Too Many Requests: retry after 1). |
Nên gửi kế hoạch khi nó thật sự đổi, giãn ít nhất vài giây giữa hai lần. setChatPlan/getChatPlan không nêu tên nhóm nên, như mọi lệnh chat riêng, không phải gọi riêng https://ahvchat.com: gọi https://ahvchat.com thì máy gốc chuyển tiếp tới máy nhà của bot; gọi thẳng máy nhà cũng được (Máy chủ theo vùng). Bot vừa chuyển nhà nhận 421 kèm parameters.home; đang chuyển thì 503.
import httpx, json
API = "https://ahvchat.com/bot<token>"
plan = {"v": 1, "plan_id": "p7f3a2c1", "revision": 2,
"groups": [{"id": 1, "title": "Gói bot"}],
"items": [{"id": 1, "group": 1, "title": "Dựng gói", "status": "doing"},
{"id": 2, "group": 1, "title": "Review độc lập", "status": "pending", "note": "chờ bản dựng"}]}
r = httpx.post(f"{API}/setChatPlan", data={"chat_id": 100004, "plan": json.dumps(plan)}).json()
print(r["result"]) # {'plan_id': 'p7f3a2c1', 'revision': 2, 'applied': True}
httpx.post(f"{API}/sendMessage", data={"chat_id": 100004, "text": "📋 Kế hoạch · 1 đang làm · 1 chờ", "ahv_plan_card": "p7f3a2c1"})
Giới hạn và mã lỗi
| Giới hạn | Giá trị |
|---|---|
| Gửi tin / hành động | 40 lần mỗi giây mỗi bot; quá thì 429 với parameters.retry_after: 1. |
| Kích thước một yêu cầu | 95 MB (tệp đính kèm tính chung). |
| Mỗi tệp | Tối đa 50 MB gửi multipart (tải lên và gửi đi); tới 500 MB qua kho của người nhận (Tệp lớn qua kho). |
| Album | 2–10 tệp. |
callback_data | 64 byte. |
| Dung lượng lưu trữ | Theo từng người dùng (mặc định 2 GB cho mọi cuộc trò chuyện của người đó); đầy thì 507 Insufficient Storage. |
getUpdates | timeout tới 50 giây, limit tới 100. |
setMyUsage / getMyUsage | 6 lần mỗi phút / 30 lần mỗi phút mỗi bot; quá thì 429 với parameters.retry_after: 10. |
setMyHost / getMyHost | 6 lần mỗi phút / 30 lần mỗi phút mỗi bot; quá thì 429 với parameters.retry_after: 10. |
| Ghim / bỏ ghim | 20 lần mỗi phút mỗi bot (tính chung ba phương thức); tối đa 1.000 tin ghim mỗi chat. |
getChatPins | 60 lần mỗi phút mỗi bot. |
Bot luôn nhớ (ahv_remember) | 10 tin nhớ / 4.000 ký tự mỗi chat riêng; bot không đặt và không gỡ được. |
setChatPlan / getChatPlan | 30 lần mỗi phút cho mỗi chat / 60 lần mỗi phút mỗi bot; kế hoạch tới 256 KiB, 200 việc mở, 400 việc, 20 nhóm. |
Lỗi riêng của tin nhớ: 400 Bad Request: message is pinned with ahv_remember; only the user can unpin it (bỏ ghim hoặc xoá một tin nhớ) và
400 Bad Request: message is pinned with ahv_remember; only the user can change it (đổi chữ một tin nhớ) — xem Bot luôn nhớ.
Mã lỗi: 400 tham số sai hoặc chat không tồn tại/bot không được nhắn; 401 token sai hoặc đã đổi; 404 phương thức chưa có;
413 yêu cầu quá lớn; 421 bot ở máy chủ khác (xem trên); 429 quá nhanh; 503 bot đang chuyển nhà.
Tin đã bị xoá
Người dùng xoá được tin của mình và tin của bot (chat riêng; trong nhóm chủ nhóm và quản trị viên xoá được cả tin người khác và tin bot), và xoá được cả lịch sử chat. Như Telegram, không có update khi người dùng xoá tin của bot: bot biết tin đã mất khi gọi tới nó.
| Bot làm với tin đã bị xoá | Kết quả |
|---|---|
editMessageText, editMessageReplyMarkup | 400 Bad Request: message to edit not found |
deleteMessage | 400 Bad Request: message to delete not found |
Gửi tin trả lời tin đó, có allow_sending_without_reply: false (trong reply_parameters hoặc ở gốc) | 400 Bad Request: message to be replied not found, không có gì được gửi |
Gửi tin trả lời tin đó, allow_sending_without_reply vắng mặt hoặc true | Tin vẫn tới, bỏ phần trả lời (như trước; bot cũ không đổi gì) |
answerCallbackQuery cho nút bot đã lấy về | true như Telegram; nút chưa tới bot thì bị rút khỏi hàng cùng tin |
Gặp các lỗi trên thì bỏ qua: đừng sửa lại, đừng gửi một bản thay. Việc bot đang chạy không bị dừng; bot gửi tiếp thì đó là tin mới, không phải tin cũ hiện lại.
Người dùng xoá tin của mình trong chat riêng thì bot nhận recalled_message (xem Update); update chưa tới bot thì bị rút khỏi hàng.
Trong nhóm không có recalled_message: update chưa tới bot bị rút, update đã tới thì bot vẫn làm.
Khác Telegram ở đâu
- Không webhook — chỉ long polling. Vì thế bot chạy ở bất cứ đâu, không cần địa chỉ công khai.
- Không inline mode, không sticker — ảnh và tệp phủ đủ; tin thoại gửi bằng
sendVoice, tệp âm thanh bằngsendAudio. Video gửi bằngsendVideohoặcsendDocumentđều phát ngay trong tin; bot nhận lạidocument, không cóvideo. - Có thêm
ahv_status/ahv_started_atcho trạng thái làm việc,setMyUsagecho hạn mức tài khoản AI của bot,ahv_choicecho thẻ lựa chọn đi kèm bàn phím, và người dùng có thể vừa bấm nút vừa viết thêm. - Kế hoạch sống (
setChatPlan,getChatPlan,ahv_plan_card) là của AHV Chat; thư viện Telegram gọi được quado_api_request(python-telegram-bot) hayapi_kwargscho tham số thêm. - Có thêm
ahv_platformtrong tin/startvà tronggetMe: bot biết mình đang ở AHV Chat, ngôn ngữ người dùng và những gì làm được (xem Bắt đầu trò chuyện). - Mô tả bot theo ngôn ngữ:
setMyDescription/getMyDescriptionnhư Telegram (tới 512 ký tự); từ app 0.0.33 app hiện bảnvihoặcentheo ngôn ngữ người dùng, thiếu thì bản mặc định (hôm nay app hiện bản mặc định). Chưa cósetMyShortDescription,setMyName. - Riêng tư mặc định: bot chỉ nhắn được cho người đã nhắn cho nó; không có bot công khai nhắn trước.
- Tệp ảnh trả về đúng một cỡ (ảnh gốc), không có bản thu nhỏ.
- Bot luôn nhớ:
ahv_remember,remember_onlyvàif_etagcủagetChatPinslà của AHV Chat, Telegram không có; bot không đặt và không gỡ được tin nhớ. - Ghim: không có tin dịch vụ khi ai đó ghim (bot không nhận update
pinned_message); bot không ghim được trong nhóm, kể cả bot trưởng nhóm.
Còn thắc mắc? Nhắn cho @ahvchat_bot trong app hoặc xem trang tải để cài app trên máy tính và điện thoại.