grammY

Вигляд

Bot API ​

Загальні відомості ​

Боти Telegram спілкуються з серверами Telegram через HTTP запити. Telegram Bot API — це специфікація цього інтерфейсу, тобто довгий список методів і типів даних, який зазвичай називають довідкою. Він визначає все, що можуть робити боти Telegram. Посилання на нього можна знайти на вкладці «Ресурси» в розділі «Telegram».

Цю систему можна візуалізувати наступним чином:

asciiart
ваш бот на grammY <———HTTP———> Bot API <———MTProto———> Telegram

Пояснення: повідомлення бота надсилається як HTTP запит до серверу Bot API. Цей сервер знаходиться за адресою api.telegram.org. Він конвертує запит у власний протокол Telegram, який називається MTProto, і відправить запит до серверної частини Telegram, яка відповідає за надсилання повідомлення користувачеві.

Так само щоразу, коли користувач відповідає, відбувається зворотний процес.

Коли ви запускаєте бота, вам потрібно визначитися з тим, як оновлення будуть надсилатися через HTTP зʼєднання. Це можна зробити за допомогою тривалого опитування або вебхуків.

Ви також можете розмістити сервер Bot API на своєму сервері. Це в основному корисно при надсиланні великих файлів або для зменшення затримок.

Виклик Bot API ​

Bot API — це те, що визначає, що можуть і чого не можуть робити боти. Кожен метод Bot API має еквівалент у grammY, і ми стежимо за тим, щоб бібліотека завжди була синхронізована з останніми та найкращими можливостями ботів. Наприклад, sendMessage у довіднику Telegram Bot API і довіднику API grammY.

Виклик метода ​

Ви можете викликати методи API через bot.api або так само через ctx.api:

ts
import { Api, Bot } from "grammy";

const bot = new Bot("");

async function sendHelloTo12345() {
  // Надсилаємо повідомлення користувачу з id 12345.
  await bot.api.sendMessage(12345, "Привіт!");

  // Надсилаємо повідомлення та зберегігаємо відповідь, яка містить інформацію про надіслане повідомлення.
  const sentMessage = await bot.api.sendMessage(12345, "Привіт знову!");
  console.log(sentMessage.message_id);

  // Надіслати повідомлення без обʼєкта `bot`.
  const api = new Api(""); // <-- помістіть токен свого бота між ""
  await api.sendMessage(12345, "Йоу!");
}
js
const { Api, Bot } = require("grammy");

const bot = new Bot("");

async function sendHelloTo12345() {
  // Надсилаємо повідомлення користувачу з id 12345.
  await bot.api.sendMessage(12345, "Привіт!");

  // Надсилаємо повідомлення та зберегігаємо відповідь, яка містить інформацію про надіслане повідомлення.
  const sentMessage = await bot.api.sendMessage(12345, "Привіт знову!");
  console.log(sentMessage.message_id);

  // Надіслати повідомлення без обʼєкта `bot`.
  const api = new Api(""); // <-- помістіть токен свого бота між ""
  await api.sendMessage(12345, "Йоу!");
}
ts
import { Api, Bot } from "https://deno.land/x/grammy@v1.33.0/mod.ts";

const bot = new Bot("");

async function sendHelloTo12345() {
  // Надсилаємо повідомлення користувачу з id 12345.
  await bot.api.sendMessage(12345, "Привіт!");

  // Надсилаємо повідомлення та зберегігаємо відповідь, яка містить інформацію про надіслане повідомлення.
  const sentMessage = await bot.api.sendMessage(12345, "Привіт знову!");
  console.log(sentMessage.message_id);

  // Надіслати повідомлення без обʼєкта `bot`.
  const api = new Api(""); // <-- помістіть токен свого бота між ""
  await api.sendMessage(12345, "Йоу!");
}

Зауважте, що bot.api — це просто екземпляр Api, який попередньо сконструйовано для вашої зручності. Зауважте також, що якщо ви маєте доступ до обʼєкта контексту, тобто перебуваєте всередині обробника повідомлень, краще завжди викликати ctx.api або одну з доступних дій.

Хоча Api покриває весь Bot API, він іноді дещо змінює сигнатури функцій, щоб зробити його зручнішим у використанні. Власне, усі методи Bot API очікують обʼєкт JSON із певними властивостями. Утім зверніть увагу, як sendMessage у наведеному вище прикладі коду отримує два аргументи: ідентифікатор чату та текст повідомлення. grammY знає, що ці два значення належать властивостям chat_id і text відповідно, і створить для вас правильний обʼєкт JSON.

Як згадувалося раніше, ви можете вказати інші параметри в третьому аргументі типу Other:

ts
async function sendHelloTo12345() {
  await bot.api.sendMessage(12345, "<i>Привіт!</i>", {
    parse_mode: "HTML",
  });
}

Крім того, grammY подбав про безліч технічних деталей, щоб спростити використання API. Наприклад, деякі властивості в певних методах потребують серіалізації за допомогою JSON.stringify перед надсиланням. Це легко забути, важко налагодити та порушує виведення типів. grammY дозволяє вам узгоджено вказувати обʼєкти через API, а також гарантує, що відповідні властивості будуть серіалізовані перед їх надсиланням.

Визначення типів для Bot API ​

grammY постачається з повним набором типів Bot API. Репозиторій @grammyjs/types містить визначення типів, які grammY використовує для внутрішнього використання. Ці визначення типів також безпосередньо експортуються з основного пакета grammy, щоб ви могли використовувати їх у власному коді.

Визначення типів у Deno ​

У Deno ви можете просто імпортувати визначення типів із types.ts, який знаходиться поруч із mod.ts:

ts
import { type Chat } from "https://deno.land/x/grammy@v1.33.0/types.ts";

Визначення типів у Node.js ​

На Node.js це складніше. Вам потрібно імпортувати типи з grammy/types. Наприклад, ви отримуєте доступ до типу Chat таким чином:

ts
import { type Chat } from "grammy/types";

Однак офіційно Node.js підтримує належний імпорт підшляхів, починаючи лише з Node.js 16. Отже, TypeScript вимагає, щоб moduleResolution було встановлено на node16 або nodenext. Налаштуйте відповідно свій tsconfig.json і додайте виділений рядок:

json
{
  "compilerOptions": {
    // ...
    "moduleResolution": "node16"
    // ...
  }
}

У деяких випадках це також може працювати без налаштування конфігурації TypeScript.

Неправильне автодоповнення у Node.js

Якщо ви не зміните свій файл tsconfig.json, як описано вище, може статися так, що ваш редактор коду запропонує в автодоповненні імпортувати типи з grammy/out/client або чогось подібного. Усі шляхи, що починаються з grammy/out є внутрішніми. Не використовуйте їх. Вони можуть бути довільно змінені коли завгодно, тому ми наполегливо рекомендуємо вам імпортувати типи з grammy/types.

Виклики Raw API ​

Бувають випадки, коли ви захочете використовувати оригінальні сигнатури функцій, але все одно покладаєтеся на зручність API grammY: наприклад, серіалізацію JSON, де це потребується. grammY підтримує це за допомогою властивостей bot.api.raw або ctx.api.raw.

Ви можете використовувати оригінальні методи наступним чином:

ts
async function sendHelloTo12345() {
  await bot.api.raw.sendMessage({
    chat_id: 12345,
    text: "<i>Привіт!</i>",
    parse_mode: "HTML",
  });
}

По суті, всі параметри з аргументів сигнатури функції обʼєднуються з обʼєктом параметрів методу, коли ви використовуєте оригінальний API.

Вибір місця розташування дата-центру ​

Пропустити решту сторінки, якщо ви тільки починаєте роботу.

Якщо ви хочете зменшити мережеву затримку вашого бота, має значення, де ви його розмістите.

Сервер Bot API за адресою api.telegram.org знаходиться в Амстердамі, Нідерланди. Тому найкращим місцем для запуску бота є Амстердам.

Порівняння постачальників хостингу

Можливо, вас зацікавить наше порівняння постачальників хостингу.

Однак, ймовірно, є ще краще місце для запуску бота, хоча це потребує значно більших зусиль.

Памʼятайте, що сервер Bot API насправді не містить вашого бота. Він лише передає запити, перекладає між HTTP і MTProto тощо. Сервер Bot API може знаходитися в Амстердамі, але сервери Telegram розподілені між трьома різними місцями:

  • Амстердам, Нідерланди;
  • Маямі, штат Флорида, США;
  • Сінгапур.

Отже, коли сервер Bot API надсилає запит до серверів Telegram, йому, можливо, доведеться надіслати дані через півсвіту. Відбудеться це чи ні, залежить від дата-центру самого бота. Дата-центр бота — це той самий дата-центр, що й у користувача, який створив бота. Дата-центр користувача залежить від багатьох факторів, у тому числі від місця розташування користувача.

Отже, ось що ви можете зробити, якщо хочете ще більше зменшити затримку.

  1. Зверніться до @where_is_my_dc_bot і надішліть зі свого облікового запису будь-який файл. Він покаже вам місцезнаходження вашого облікового запису. Це також місцезнаходження вашого бота.
  2. Якщо ваш дата-центр знаходиться в Амстердамі, вам нічого не потрібно робити. В іншому випадку, продовжуйте читати.
  3. Орендуйте VPS у місці розташування вашого дата-центру.
  4. Запустіть локальний сервер Bot API на цьому VPS.
  5. Розмістіть бота в тому ж місці, що і ваш дата-центр.

Так кожен запит буде проходити лише найкоротший шлях між Telegram і вашим ботом.

Запуск локального сервера Bot API ​

Запуск власного сервера Bot API має дві основні переваги:

  1. Ваш бот може надсилати та отримувати великі файли.
  2. Ваш бот може зменшити мережеві затримки (дивіться вище).

Інші незначні переваги перераховані тут.

Ви повинні запустити сервер Bot API на VPS. Якщо ви спробуєте запустити його де-небудь в іншому місці, він буде виходити з ладу або втрачати повідомлення.

Ви також повинні скомпілювати сервер Bot API з нуля. Це корисно, якщо у вас є досвід компіляції великих проектів на C++, але якщо у вас його немає, ви можете просто скопіювати інструкції по збірці і сподіватися, що вони працюватимуть.

Найпростіший спосіб запустити сервер Bot API — скористатися генератором інструкцій по збірці, наданим Telegram..

Більше варіантів можна знайти в репозиторії сервера Bot API.

Зібравши сервер, ви отримаєте виконуваний файл, який можна запустити.

Ви отримали цей виконуваний файл? Тепер ви можете перемістити свого бота на локальний сервер Bot API!

Вихід з сервера розміщеного Bot API ​

По-перше, вам потрібно вийти з сервера, на якому розміщено Bot API. Візьміть цю URL-адресу і вставте її в браузер (не забудьте замінити <токен> на токен вашого бота):

text
https://api.telegram.org/bot<токен>/logOut

Ви повинні побачити {"ok":true, "result":true}.

Налаштування grammY для використання локального сервера Bot API ​

Далі ви можете вказати grammY використовувати ваш локальний сервер Bot API замість api.telegram.org. Припустимо, ваш бот працює на localhost на порту 8081. Тоді вам слід використовувати наступну конфігурацію.

ts
const bot = new Bot("", { // <-- використовуйте той самий токен, що й раніше
  client: { apiRoot: "http://localhost:8081" },
});

Тепер ви можете запустити бота знову. Він буде використовувати локальний сервер Bot API.

Якщо щось пішло не так, і ви не знаєте, як це виправити, скільки б ви не гуглили, не соромтеся приєднатися до нашого чату спільноти і попросити про допомогу! Ми знаємо про вашу помилку ще менше, ніж ви, але, ймовірно, зможемо відповісти на ваші запитання.

Памʼятайте, що ви також повинні налаштувати свій код для роботи з локальними шляхами до файлів замість URL-адрес, що вказують на ваші файли. Наприклад, виклик getFile дасть вам шлях до файлу, який вказує на ваш локальний диск, а не на файл, який спочатку потрібно завантажити з Telegram. Аналогічно, плагін файлів має метод getUrl, який повертає не URL-адресу, а абсолютний шлях до файлу.

Якщо ви коли-небудь захочете змінити цю конфігурацію і перенести свого бота на інший сервер, обовʼязково прочитайте цей розділ README репозиторію серверу Bot API.