Telegram Business

Telegram Business дозволяє керувати вашим приватним чатом з іншим користувачем (людиною) за допомогою бота. Це включає надсилання та отримання повідомлень від вашого імені. Загалом, це корисно, якщо ви ведете бізнес у Telegram, а інший користувач є вашим клієнтом.

Якщо ви ще не знайомі з Telegram Business, ознайомтеся з офіційною документацією від Telegram, перш ніж продовжити.

Звісно, grammY повністю підтримує це.

Обробка бізнес-повідомлень

Бот може керувати приватним чатом між двома користувачами через Telegram Business — акаунт, який підписаний на бізнес-підписку Telegram. Керування приватними чатами здійснюється через обʼєкт business connection, який виглядає ось так.

Отримання бізнес-повідомлень

Після встановлення бізнес-підключення бот буде отримувати повідомлення від обох учасників чату.

bot.on("business_message", async (ctx) => {
  // Отримуємо обʼєкт повідомлення.
  const message = ctx.businessMessage;
  // Скорочені методи працюють, як і очікувалося.
  const msg = ctx.msg;
});

Наразі незрозуміло, хто з двох учасників чату надіслав повідомлення. Це може бути повідомлення вашого клієнта, а може бути повідомлення, надіслане особисто вами (не вашим ботом)!

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

bot.on("business_message", async (ctx) => {
  // Отримуємо інформацію про бізнес-підключення.
  const conn = await ctx.getBusinessConnection();
  const employee = conn.user;
  // Перевіряємо, хто надіслав це повідомлення.
  if (ctx.from.id === employee.id) {
    // Це повідомлення надіслали ви.
  } else {
    // Це повідомлення надіслав ваш клієнт.
  }
});

Ви також можете пропустити виклик getBusinessConnection для кожного оновлення, виконавши це.

Надсилання повідомлень

Ваш бот може надсилати повідомлення до цього чату не будучи учасником чату. Це працює, як і очікувалося, за допомогою ctx.reply і всіх його варіантів. grammY перевіряє, чи доступний скорочений метод контексту ctx.businessConnectionId, щоб надіслати повідомлення до керованого бізнес-чату.

bot.on("business_message").filter(
  async (ctx) => {
    const conn = await ctx.getBusinessConnection();
    return ctx.from.id !== conn.user.id;
  },
  async (ctx) => {
    // Автоматично відповідаємо на всі запитання клієнтів.
    if (ctx.msg.text.endsWith("?")) {
      await ctx.reply("Скоро.");
    }
  },
);

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

Просунуті можливості

Є ще кілька речей, які слід враховувати при інтеграції вашого бота з Telegram Business. Тут ми коротко розглянемо кілька аспектів.

Редагування або видалення бізнес-повідомлень

Коли ви або ваш клієнт редагуєте або видаляєте повідомлення в чаті, ваш бот буде про це повідомлений. Зокрема, ви отримаєте оновлення edited_business_message або deleted_business_message. Ваш бот може обробляти їх звичайним способом, використовуючи bot.on і його незліченні запити фільтрування.

Однак ваш бот НЕ може редагувати або видаляти повідомлення в чаті. Аналогічно, ваш бот НЕ може пересилати повідомлення з чату або копіювати їх куди-небудь. Всі ці можливості залишаються за людиною.

Робота з бізнес-підключеннями

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

Наприклад, бот може або не може надсилати повідомлення в чати, якими він керує. Ви можете дізнатися про це за допомогою частини запиту :can_reply.

bot.on("business_connection:can_reply", async (ctx) => {
  // Підключення дозволяє надсилати повідомлення.
});

Має сенс зберігати обʼєкти бізнес-підключень у вашій базі даних. Так ви зможете уникнути виклику ctx.getBusinessConnection() при кожному оновленні лише для того, щоб зʼясувати, хто надіслав повідомлення.

Крім того, оновлення business_connection містить user_chat_id. Цей ідентифікатор чату може бути використаний для ініціювання розмови з користувачем, який підключив бота.

bot.on("business_connection:is_enabled", async (ctx) => {
  const id = ctx.businessConnection.user_chat_id;
  await ctx.api.sendMessage(id, "Дякую, що підключили мене!");
});

Це працюватиме, навіть якщо користувач ще не запустив вашого бота.

Керування індивідуальними чатами

Якщо ви підключите бота для керування своїм акаунтом, застосунки Telegram пропонуватимуть вам кнопку для керування цим ботом у кожному керованому чаті. Ця кнопка надсилає боту команду /start.

Ця команда запуску має спеціальні дані deep linking, визначені Telegram. Вони мають формат bizChatXXXXX, де XXXXX буде ідентифікатором чату, яким ви керуєте.

bot.command("start", async (ctx) => {
  const payload = ctx.match;
  if (payload.startsWith("bizChat")) {
    const id = payload.slice(7); // обрізаємо `bizChat`
    await ctx.reply(`Давайте керувати чатом #${id}!`);
  }
});

Це надає вашому боту важливий контекст і дозволяє йому керувати індивідуальними бізнес-чатами прямо з розмови з кожним клієнтом.