Bot API ​

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

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

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

( ( ( Telegram ) MTProto API ) Bot HTTP API ) <-- бот підключається тут

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

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

Виклик Bot API ​

Кожен окремий метод Bot API має еквівалент у grammY. Наприклад: sendMessage у довіднику Telegram Bot API і довіднику API grammY.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Виклики Raw API ​

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

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

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

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