Bot API
Загальні відомості
Боти Telegram спілкуються з серверами Telegram через HTTP запити. Telegram Bot API — це специфікація цього інтерфейсу, тобто довгий список методів і типів даних, який зазвичай називають довідкою. Він визначає все, що можуть робити боти Telegram. Посилання на нього можна знайти на вкладці «Ресурси».
Цю систему можна візуалізувати наступним чином:
( ( ( Telegram ) MTProto API ) Bot HTTP API ) <-- бот підключається тут
Пояснення: коли ваш бот надсилає повідомлення, воно надсилається як HTTP запит на сервер Bot API, розміщений командою Telegram або особисто вами. Цей сервер конвертує запит у власний протокол Telegram, який називається MTProto, і відправить запит до серверної частини Telegram, яка відповідає за надсилання повідомлення користувачеві.
Так само щоразу, коли користувач відповідає, відбувається зворотний процес.
Обхід обмежень на розмір файлу
Сервер Telegram дозволяє вашому боту надсилати файли розміром до 2000 МБ. Однак сервер Bot API, який відповідає за переклад запитів на протокол HTTP, обмежує розмір файлу до 20 МБ для завантаження з серверу та 50 МБ для завантаження на сервер.
Отже, якщо ви обійдете сервер Bot API, який Telegram запускає для вас, і просто розмістите свій власний сервер Bot API, ви можете дозволити своєму боту надсилати файли розміром до 2000 МБ.
Примітка: якщо ви працюєте з великими файлами через тривале опитування, вам варто використовувати плагін для конкурентності (runner).
Виклик Bot API
Кожен окремий метод Bot API має еквівалент у grammY. Наприклад: send
у довіднику Telegram Bot API і довіднику API grammY.
Виклик метода
Ви можете викликати методи API через bot
або так само через ctx
:
async function sendHelloTo12345() {
// Надсилаємо повідомлення користувачу з id 12345.
await bot.api.sendMessage(12345, "Привіт!");
// Надсилаємо повідомлення та зберегігаємо відповідь, яка містить інформацію про надіслане повідомлення.
const sentMessage = await bot.api.sendMessage(12345, "Привіт знову!");
console.log(sentMessage.message_id);
}
2
3
4
5
6
7
8
Хоча bot
покриває весь Bot API, він іноді дещо змінює сигнатури функцій, щоб зробити його зручнішим у використанні. Власне, усі методи Bot API очікують обʼєкт JSON із певними властивостями. Утім зверніть увагу, як send
у наведеному вище прикладі отримує два аргументи: ідентифікатор чату та текст повідомлення. grammY знає, що ці два значення належать властивостям chat
і text
відповідно, і створить для вас правильний обʼєкт JSON.
Як згадувалося раніше, ви можете вказати інші параметри в третьому аргументі типу Other
:
async function sendHelloTo12345() {
await bot.api.sendMessage(12345, "<i>Привіт!</i>", {
parse_mode: "HTML",
});
}
2
3
4
5
Крім того, grammY подбав про безліч технічних деталей, щоб спростити використання API. Наприклад, деякі властивості в певних методах потребують серіалізації за допомогою JSON
перед надсиланням. Це легко забути, важко налагодити та порушує виведення типів. grammY дозволяє вам узгоджено вказувати обʼєкти через API, а також гарантує, що відповідні властивості будуть серіалізовані перед їх надсиланням.
Визначення типів для API
grammY постачається з повним набором типів Bot API. Репозиторій @grammyjs
містить визначення типів, які grammY використовує для внутрішнього використання. Ці визначення типів також безпосередньо експортуються з основного пакета grammy
, щоб ви могли використовувати їх у власному коді.
Визначення типів у Deno
У Deno ви можете просто імпортувати визначення типів із types
, який знаходиться поруч із mod
:
import { type Chat } from "https://deno.land/x/grammy@v1.19.2/types.ts";
Визначення типів у Node.js
На Node.js це складніше. Вам потрібно імпортувати типи з grammy
. Наприклад, ви отримуєте доступ до типу Chat
таким чином:
import { type Chat } from "grammy/types";
Однак офіційно Node.js підтримує належний імпорт підшляхів, починаючи лише з Node.js 16. Отже, TypeScript вимагає, щоб module
було встановлено на node16
або nodenext
. Налаштуйте відповідно свій tsconfig
і додайте виділений рядок:
{
"compilerOptions": {
// ...
"moduleResolution": "node16"
// ...
}
}
2
3
4
5
6
7
У деяких випадках це також може працювати без налаштування конфігурації TypeScript.
Неправильне автодоповнення
Якщо ви не зміните свій файл tsconfig
, як описано вище, може статися так, що ваш редактор коду запропонує в автодоповненні імпортувати типи з grammy
або чогось подібного. Усі шляхи, що починаються з grammy
є внутрішніми. Не використовуйте їх. Вони можуть бути довільно змінені коли завгодно, тому ми наполегливо рекомендуємо вам імпортувати типи з grammy
.
Виклики Raw API
Бувають випадки, коли ви захочете використовувати оригінальні сигнатури функцій, але все одно покладаєтеся на зручність API grammY: наприклад, серіалізацію JSON, де це потребується. grammY підтримує це за допомогою властивостей bot
або ctx
.
Ви можете використовувати оригінальні методи наступним чином:
async function sendHelloTo12345() {
await bot.api.raw.sendMessage({
chat_id: 12345,
text: "<i>Привіт!</i>",
parse_mode: "HTML",
});
}
2
3
4
5
6
7
По суті, всі параметри з аргументів сигнатури функції обʼєднуються з обʼєктом параметрів методу, коли ви використовуєте оригінальний API.