TGbot

Google Apps Script Library для работы с API Telegram.
Работайте удобнее в GAS используя Google Таблицы.

ID библиотеки:

1LyGnqsaphk-K_EB8ZxqcBRiKXRE2TY8oSHWlZn4HBje1WlmoNk51wGeg

Актуальная версия: 76 от 20 мар., 04:39

Поддерживает работу только через Webhook (doPost(e)).

Пример бота
Баги отправлять сюда
Канал автора ExceLifeHack
Телеграмм канал про Google Таблицы
Помощь Google Apps & API. Скрипты, Таблицы, BigQuery, Отчеты, Автоматизация

Подключение

Откройте редактор скриптов: Расширения -> Apps Script -> Библиотеки.

Заполните поля формы Добавление библиотеки:

• вставьте Идентификатор скрипта библиотеки;
• Нажмите Найти;
• выберите последнюю версию и Добавить.

Инициализация бота

// токен Telegram бота от \@BotFather.
const botToken = "<botToken>"

// ссылка на WebApp Google для работы с ответами doGet(e).
const webAppUrl = "Optional[<webAppUrl>]"

// печать URL и OPTIONS запроса при выполнении, по умочанию false.
const logRequest = "Optional[<logRequest>]"

const Bot = TGbot.bot(botToken, webAppUrl, logRequest);

Использование методов

const chat_id = "123456" // chat_id получателя

// отправка сообщения
const response = Bot.sendMessage({ chat_id: chat_id, text: "Какой-то текст 😁" });

console.log(JSON.stringify(response, null, 7));

const message_id = response?.result?.message_id;

// изменение сообщения
Bot.editMessageText({
  chat_id: chat_id,
  message_id: message_id ,
  text: "Изменили сообщение",
});

// удаление сообщения
Bot.deleteMessage({
  chat_id: chat_id,
  message_id: message_id,
});

// отправка фото
Bot.sendPhoto({
    chat_id: chat_id,
    photo: "url фото",
    caption: "Отправка фото",
  });

// отправка группы медиа (фото)
const data = [
  ["url фото", "Подпись 1"],
  ["url фото", "Подпись 2"],
  ["url фото", "Подпись 3"],
].map((item) => TGbot.inputMediaPhoto({ media: item[0], caption: item[1] }));

console.log(JSON.stringify(data, null, 7));
Bot.sendMediaGroup({ chat_id: chat_id, media: data });

// отправка изображения или документа с использованием Blob
const ss = SpreadsheetApp.getActiveSpreadsheet();
const sheet = ss.getSheetByName("Название листа");
// пример, отправка графика (фото .png) с листа Google Sheets
const blob = sheet.getCharts()[0].getBlob();

Bot.sendPhoto({
  chat_id: chat_id,
  photo: blob,
  contentType: "multipart/form-data" // указать обязательно
});

Bot.sendDocument({
  chat_id: chat_id,
  document: blob,
  contentType: "multipart/form-data" // указать обязательно
});

// отправка архива с данными
// название файла передавать только на латинице, используйте для транслитерации TGbot.translit(filename);
const filename = 'Test';
// [blob, ...] можно указать несколько файлов Blob (используйте разные имена для blob)
const zip = Utilities.zip([blob], `${filename}.zip`);

Bot.sendDocument({
  chat_id: chat_id,
  document: zip,
  contentType: "multipart/form-data" // указать обязательно
});

// отправка опросов
// регулярный
Bot.sendPoll({
  chat_id: chat_id,
  question: "Как выходные?",
  options: ["Фантастично", "Пойдёт", "Бывало лучше"],
});

// викторина
Bot.sendPoll({
  chat_id: chat_id,
  question: "Попугай и хомяк ели овес и орехи.\nХомяк не ел овес, кто ел орехи?",
  options: ["Попугай", "Хомяк", "Никто"],
  type: "quiz",
  is_anonymous: false,
  correct_option_id: 1, // правилтный ответ в массиве, если 0 то не передавать
  explanation: "Интересные загадки для 10 лет!!!"
});

// остановка опроса
Bot.stopPoll({
  chat_id: chat_id,
  message_id: message_id, // ID сообщения с опросом который нужно остановить
});

/**
 * Сохранение файла xlsx отправленного в бот Webhook - doPost(e)
 * на Goole Drive (необходимо подключить к проекту Drive API).
 * @param {Message} message полученное сообщение.
 * @param {string} folderId ID папки куда будет сохранен файл.
 * @return {string} file id сохранённого файла.
 */
function saveXlsxFileToDrive(message, folderId) {
  const blob = UrlFetchApp.fetch(
    Bot.getFile(message.document.file_id)
  ).getBlob();
  // const blob = UrlFetchApp.fetch(Bot.getFileDownloadUrl(Bot.getPath(message.document.file_id))).getBlob(); // или так
  const file_name = message.document.file_name.replace(
    `${
      message.document.file_name.split(".")[
        message.document.file_name.split(".").length - 1
      ]
    }.`,
    ""
  );

  const resource = {
    title: file_name,
    mimeType: MimeType.GOOGLE_SHEETS, // если параметр не указать, то сохранится в исходном формате
    parents: [{ id: folderId }],
  };

  const file = Drive.Files.insert(resource, blob);
  return file.id;
}

Кнопки клавиатуры

const Keyboard = TGbot.keyboard();
const Key = TGbot.key();

const keys = ["1", "2", "3", "4"];
const KEYBOARD_REPLY = Keyboard.make([keys, "5"], { columns: 2 }).reply();

Bot.sendMessage({
  chat_id: chat_id,
  text: "Отправили клавиатуру 👇",
  reply_markup: KEYBOARD_REPLY,
});

const KEYBOARD_INLINE = Keyboard.make(
  [Key.url("✅ Нажми меня", "https://www.google.ru")],
  { columns: 1 }
).inline();

Bot.sendMessage({
  chat_id: chat_id,
  text: "А вот inline клавиатура 👇",
  reply_markup: KEYBOARD_INLINE,
});

Bot.sendMessage({
  chat_id: chat_id,
  text: "Удалить клавиатуру 😎",
  reply_markup: Keyboard.remove(),
});

Webhook - doPost(e)

const botToken = "<botToken>"
const webAppUrl = "<webAppUrl>"
const Bot = TGbot.bot(botToken, webAppUrl);

function doPost(e) {
  if (e?.postData?.contents) {
    // парсим объет, который пришёл
    const contents = JSON.parse(e.postData.contents);
    const debug =
      ss.getSheetByName("Debug") || ss.insertSheet("Debug").setTabColor("RED");
    debug.getRange(1, 1).setValue(JSON.stringify(contents, null, 7));

    try {
      if (contents.message) {
        /**
         * Копируйте содержимое из файла Types.js в свой проект.
         * Позволяет использовать JSDoc для уточнения типов переменных, что
         * открывает возможности для подсказок в онлайн-редакторе.
        */

        /** @type {Message}*/
        const msg = contents.message;
        const text = msg.text;
        const chat_id = msg.from.id;

        if (TGbot.isBotCommandMessage(msg)) {
          if (["/start"].includes(text))
            Bot.sendMessage({ chat_id: chat_id, text: `Привет!` });
          else if (["/myid"].includes(text))
            Bot.replyMessage({
              message: msg,
              text: `Твой Telegram ID: ${chat_id}`,
            });
          else if (!["/start", "/myid"].includes(text))
            Bot.answerMessage({
              message: msg,
              text: `Я не знаю такой команды ${text} 😕, попробуй еще раз.`,
            });
        } else if (["фото"].includes(text.toLowerCase())) {
          const data = [
            ["url фото", "Подпись 1"],
            ["url фото", "Подпись 2"],
            ["url фото", "Подпись 3"],
          ].map((item) =>
            TGbot.inputMediaPhoto({ media: item[0], caption: item[1] })
          );

          return Bot.sendMediaGroup({ chat_id: chat_id, media: data });
        } else if (["видео"].includes(text.toLowerCase()))
          return Bot.sendVideo({ chat_id: chat_id, video: "url видео" });
        else
          return Bot.sendMessage({
            chat_id: chat_id,
            text: `Не понимаю ¯\_(ツ)_/¯`,
          });
      }
    } catch (err) {
      console.log(err.stack);
    }
  }
}

Обновление:

28.01.2023 Добавлен файл Types.js, автор Alexander Ivanov.
Копируйте содержимое из файла Types.js в свой проект.
После добавления, вы можете использовать JSDoc для уточнения типов переменных, что открывает возможности для подсказок в онлайн-редакторе.

Добавлены новые методы:

• exportChatInviteLink
• createChatInviteLink
• editChatInviteLink
• sendAnimation
• sendVoice
• sendVideoNote
• sendLocation
• editMessageLiveLocation
• stopMessageLiveLocation
• sendVenue
• sendContact
• sendDice

Методы библиотеки (официальные):

• setWebhook метод, для указания URL-адреса и получения входящих обновлений через исходящий веб-перехватчик.
• deleteWebhook метод, для удаления интеграции с веб-перехватчиком.
• getWebhookInfo метод, для получения текущего статуса веб-перехватчика.
• getMe метод проверки токена аутентификации вашего бота.
• logOut метод выхода из сервера API облачного бота перед локальным запуском бота.
• close метод чтобы закрыть экземпляр бота перед его перемещением с одного локального сервера на другой.
• setMyDefaultAdministratorRights метод, для измения прав администратора по умолчанию, запрашиваемые ботом, когда он добавляется в качестве администратора в группы или каналы.
• getMyDefaultAdministratorRights метод, для получения текущих прав администратора бота по умолчанию.
• setMyCommands метод, для установки списока команд бота.
• getMyCommands метод, для получения списка команд бота.
• deleteMyCommands метод, для удаления списока команд бота.
• getChat используйте этот метод для получения актуальной информации о чате (текущее имя пользователя для разговоров один на один, текущее имя пользователя, группы или канала и т. д.).
• getChatAdministrators метод, для получения списка администраторов в чате.
• setChatAdministratorCustomTitle метод, для установики пользовательского титула для администратора в супергруппе, продвигаемой ботом.
• getChatMemberCount метод, для получения количества участников в чате.
• getChatMember метод, получения информации об участнике чата.
• banChatMember метод, для блокировки пользователя в группе, супергруппе или канале.
• unbanChatMember метод, для разблокировки ранее забаненного пользователя в супергруппе или канале.
• setChatPermissions метод, для установки разрешений чата по умолчанию для всех участников.
• exportChatInviteLink метод, для создания новой основной ссылки-приглашения для чата.
• createChatInviteLink метод, , чтобы создать дополнительную ссылку для приглашения в чат.
• editchatinvitelink метод, для редактирования неосновной ссылки-приглашения, созданной ботом.
• restrictChatMember метод, чтобы ограничить пользователя в супергруппе.
• setChatPhoto метод, чтобы установить новую фотографию профиля для чата.
• deleteChatPhoto метод, чтобы удалить фотографию чата.
• setChatTitle метод, чтобы изменить название чата.
• setChatDescription метод, чтобы изменить описание группы, супергруппы или канала.
• setChatMenuButton метод, изменения кнопки меню бота в приватном чате или кнопки меню по умолчанию.
• getChatMenuButton метод, получения текущего значения кнопки меню бота в приватном чате или кнопки меню по умолчанию.
• pinChatMessage метод, чтобы добавить сообщения в список закрепленных сообщений в чате.
• unpinChatMessage метод, для удаления закрепленного сообщения в чате.
• unpinAllChatMessages метод, для очистки списка закрепленных сообщений в чате.
• sendChatAction метод, когда вам нужно сообщить пользователю, что что-то происходит на стороне бота.
• getUserProfilePhotos метод, для получения списока изображений профиля для пользователя.
• leaveChat используйте этот метод чтобы ваш бот покинул группу, супергруппу или канал.
• sendMessage метод, для отправки текстовых сообщений.
• forwardMessage метод, для пересылки сообщений любого типа.
• copyMessage метод, для копирования сообщения.
• deleteMessage метод, для удаления сообщения.
• editMessageText метод, для редактирования текстовых и игровых сообщений.
• editMessageCaption метод, для редактирования подписей к сообщениям.
• editMessageMedia метод, для редактирования анимации, аудио, документа, фото или видео сообщения.
• editMessageReplyMarkup метод, для редактирования разметки ответов сообщений.
• sendPhoto метод, для отправки фотографий.
• sendAudio метод, для отправки отправки аудиофайлов.
• sendDocument метод, для отправки общих файлов.
• sendVideo метод, для отправки видео.
• sendAnimation метод, для отправки файлов анимации (видео GIF или H.264/MPEG-4 AVC без звука).
• sendVoice метод, для отправки аудиофайлов, если вы хотите, чтобы клиенты Telegram отображали файл как воспроизводимое голосовое сообщение.
• sendVideoNote метод, для отправки закругленных видео MPEG4 продолжительностью до 1 минуты.
• sendMediaGroup метод, отправки группы фотографий, видео, документов или аудио в виде альбома.
• sendLocation метод, для отправки точки на карте.
• editMessageLiveLocation метод, для редактирования сообщений о местоположении в реальном времени.
• stopMessageLiveLocation метод, для остановки обновления сообщения о текущем местоположении до истечения срока действия live_period.
• sendVenue Метод, для отправки информации о месте проведения.
• sendContact метод, для отправки телефонных контактов.
• sendDice метод, для отправики анимированный эмодзи, который будет отображать случайное значение.
• sendPoll метод, для отправки отправки собственного опроса.
• stopPoll метод, для остановки опроса, отправленный ботом.
• sendSticker метод, отправки статических стикеров .WEBP, анимированных .TGS или видео .WEBM.
• getStickerSet метод, для получения набора наклеек по названию набора.
• answerCallbackQuery метод, для отправки ответов на запросы обратного вызова, отправленные со встроенной клавиатуры.
• sendInvoice метод, для отправки счетов.
• answerShippingQuery метод, для ответа на запросы о доставке.
• answerPreCheckoutQuery метод, для ответа запросы перед оформлением заказа.
• getFile метод, для получения основной информации о файле и подготовки его к загрузке.

Неофициальные методы:

• getPath метод, для получения пути к файлу.
• getFileDownloadUrl метод, получения ссылки на скачивание файла.
• answerMessage ответ по from.id на получнное сообщение. Передать объект message в качестве первого аргумента.
• replyMessage ответ по message_id на получнное сообщение. Передать объект message в качестве первого аргумента.

Copyright & License

MIT License

Copyright (©) 2022 by Mikhail Nosaev

Настоящим предоставляется бесплатное разрешение любому лицу, получившему копию этого программного обеспечения и связанных с ним файлов документации («Программное обеспечение»), работать с Программным обеспечением без ограничений, включая, помимо прочего, права на использование, копирование, изменение, слияние. Публиковать, распространять, сублицензировать и/или продавать копии Программного обеспечения, а также разрешать лицам, которым предоставляется Программное обеспечение, делать это при соблюдении следующих условий:

Приведенное выше уведомление об авторских правах и это уведомление о разрешении должны быть включены во все копии или существенные части Программного обеспечения.

ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, ПОМИМО ПРОЧЕГО, ГАРАНТИИ КОММЕРЧЕСКОЙ ПРИГОДНОСТИ, ПРИГОДНОСТИ ДЛЯ ОПРЕДЕЛЕННОЙ ЦЕЛИ И НЕНАРУШЕНИЯ ПРАВ. НИ ПРИ КАКИХ ОБСТОЯТЕЛЬСТВАХ АВТОРЫ ИЛИ ОБЛАДАТЕЛИ АВТОРСКИМ ПРАВОМ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ЗА ЛЮБЫЕ ПРЕТЕНЗИИ, УЩЕРБ ИЛИ ИНУЮ ОТВЕТСТВЕННОСТЬ, БУДУТ СВЯЗАННЫЕ С ДОГОВОРОМ, ДЕЛОМ ИЛИ ИНЫМ ОБРАЗОМ, ВОЗНИКАЮЩИЕ ИЗ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ ИЛИ ИСПОЛЬЗОВАНИЯ ИЛИ ИНЫХ СДЕЛОК В СВЯЗИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ ИЛИ ИСПОЛЬЗОВАНИЕМ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ.