CloudGram API

Один модуль: боты, свой аккаунт и доступ к аккаунтам пользователей вашего сайта.

Адреса, заголовки, коды ошибок и опрос обновлений настроены внутри модуля. Снаружи — только функции из этого справочника.

Первый бот за минуту

Бот создаётся не в коде, а в переписке: у CloudGram есть служебный бот Bot Father, он всё и оформит.

Копироватьconst cloudgram = require("./cloudgram.js");
const bot = cloudgram.bot("ВАШ_ТОКЕН");

bot.onMessage((msg) => msg.reply("Привет, " + msg.from.first_name + "!"));
bot.start();

В том же мини-приложении задаются аватарка, описание, команды-подсказки и мини-приложение самого бота.

Что такое токен и почему его берегут

Токен — это и логин, и пароль бота в одной строке вида 5:c229bf39…. Сервер не спрашивает больше ничего: пришёл верный токен — значит, пришёл владелец бота.

Как хранить правильно:

• держите токен в переменной окружения, а не в тексте программы;
• не коммитьте файл с токеном в репозиторий — добавьте его в .gitignore;
• если токен где-то засветился, сразу нажмите «Сбросить» в карточке бота: старый перестанет работать в ту же секунду.

Копироватьconst bot = cloudgram.bot(process.env.CLOUDGRAM_TOKEN);

Установка

Модуль без зависимостей: один файл, ставить ничего не нужно.

Node.js 12+

Скачайте cloudgram.js и положите рядом со своим скриптом:

Копироватьconst cloudgram = require("./cloudgram.js");

Python 3.8+

Скачайте cloudgram.py и положите рядом со своим скриптом:

Копироватьimport cloudgram

Быстрый старт

Бот отвечает на сообщения

Копироватьconst cloudgram = require("./cloudgram.js");
const bot = cloudgram.bot("ТОКЕН_БОТА");

bot.onMessage((msg) => {
  msg.reply("Привет, " + msg.from.first_name + "!");
});

bot.start();

Копироватьimport cloudgram
bot = cloudgram.bot("ТОКЕН_БОТА")

@bot.on_message
def handle(msg):
    msg.reply("Привет, " + msg.sender_name + "!")

bot.start()

Свой аккаунт

Копироватьconst account = cloudgram.account("CLIENT_ID", "CLIENT_SECRET");

const chats = await account.chats();
await account.send(chats[0].id, "Сообщение из скрипта");

Копироватьaccount = cloudgram.account("CLIENT_ID", "CLIENT_SECRET")

chats = account.chats()
account.send(chats[0]["id"], "Сообщение из скрипта")

Сайт подключает аккаунт пользователя

Шаг 1 — отправьте пользователя на страницу согласия. Шаг 2 — обменяйте код из адреса возврата на подключение.

Копироватьconst site = cloudgram.site({ name: "Моя CRM", redirectUri: "https://ваш-сайт/callback" });

// 1. куда отправить пользователя
const url = site.link(myRandomState);

// 2. на адресе возврата пришёл code
const session = await site.connect(code);
const chats = await session.chats();

Копироватьsite = cloudgram.site("https://ваш-сайт/callback", name="Моя CRM")

url = site.link(my_random_state)

session = site.connect(code)
chats = session.chats()

Ключи

Функции: бот

Создание: cloudgram.bot(token) — в Python так же.

Приём сообщений

Ссылка на бота с меткой

Ссылка вида cloudgram.ru/имя_бота?start=метка открывает чат с ботом и показывает кнопку «Начать». Когда человек её нажимает, боту приходит команда /start метка — по метке видно, откуда он пришёл: из рекламы, по приглашению друга, с конкретной страницы сайта.

bot.onCommand("/start", function (msg) {
  var метка = msg.text.split(" ")[1] || "";

  if (метка) {
    msg.reply("Вы пришли по приглашению: " + метка);
  } else {
    msg.reply("Здравствуйте!");
  }
});

Нажатия кнопок

Кнопка с полем callback не отправляет ничего в чат — вместо этого бот получает нажатие и отвечает всплывающей подсказкой.

Копироватьbot.send(chatId, "Продолжить?", { buttons: [
  [{ text: "Да", callback: "yes" }, { text: "Нет", callback: "no" }]
]});

bot.onCallback((press) => {
  press.answer(press.data === "yes" ? "Поехали!" : "Отменено");
});

Отправка

Файлы

Файл можно передать четырьмя способами, модуль сам разберётся: путь на диске, ссылка http/https, содержимое (Buffer или bytes) либо строка base64.

Копироватьbot.photo(chatId, "./cat.jpg", { caption: "Котик" });
bot.video(chatId, "https://example.com/clip.mp4");
bot.file(chatId, "./отчёт.pdf", { name: "Отчёт за август.pdf" });

Копироватьbot.photo(chat_id, "./cat.jpg", caption="Котик")
bot.video(chat_id, "https://example.com/clip.mp4")
bot.file(chat_id, "./отчёт.pdf", name="Отчёт за август.pdf")

Команды

Заданные команды всплывают подсказкой, когда пользователь начинает вводить «/», и открываются кнопкой слева в поле ввода.

Копироватьbot.setCommands([
  { command: "start", description: "Меню и справка" },
  { command: "check", description: "Проверить каталог сейчас" }
]);

Копироватьbot.set_commands([
    {"command": "start", "description": "Меню и справка"},
    {"command": "check", "description": "Проверить каталог сейчас"},
])

Кто написал боту

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

Копироватьconst who = await bot.getUser(msg.chat.id);
// { id, username, first_name, registered_at, registered_date, verified, avatar_url }

Мини-приложения

Ваш сайт открывается прямо в CloudGram: в поле ввода появляется кнопка, по ней всплывает окно с приложением. Сверху — название бота, крестик и меню с пунктами «На весь экран», «Перезагрузить», «Закрыть».

Копироватьbot.setMenu("https://example.com", "Открыть карту");

То же самое можно сделать без кода — командой в чате с ботом @newbot:

Копировать/setmenu @вашбот https://example.com Открыть карту

Кто открыл приложение

Адрес приложения дополняется данными о пользователе — во фрагменте, после решётки. Фрагмент не уходит на ваш сервер в запросе и не оседает в логах: приложение читает его само.

Копироватьvar p = new URLSearchParams(location.hash.replace(/^#/, ""));
var data = JSON.parse(p.get("cgInitData"));   // user, bot, auth_date
var signature = p.get("cgSignature");

Копироватьconst crypto = require("crypto");
const ok = crypto.createHmac("sha256", ТОКЕН_БОТА).update(cgInitData).digest("hex") === cgSignature;

Команды из приложения

Приложение может управлять окном через postMessage:

Копироватьparent.postMessage({ type: "cloudgram:close" }, "*");    // закрыть
parent.postMessage({ type: "cloudgram:expand" }, "*");   // на весь экран

Разметка текста

Параметр format у send и edit. Значение "html" — привычные теги, "markdown" — короткие символы. Без параметра текст уходит как есть.

Копироватьbot.send(chatId, "<b>Готово</b>, файл: <code>отчёт.pdf</code>", { format: "html" });

Функции: аккаунт

Создание: cloudgram.account(clientId, clientSecret). Работает с вашим собственным аккаунтом.

Функции: сайт

Создание: cloudgram.site({ name, redirectUri }), в Python — cloudgram.site(redirect_uri, name). Пользователь один раз подтверждает доступ, пароль вам не передаётся.

При отказе пользователя на адрес возврата придёт error=denied вместо code.

Подключение

Возвращает site.connect(). Сохранённый токен восстанавливается через cloudgram.session(token).

Объекты

Сообщение

В Python у сообщения есть короткие свойства: msg.text, msg.chat_id, msg.sender, msg.sender_name, msg.media_url. Само сообщение при этом остаётся обычным словарём.

Кнопка

Кнопки передаются рядами: массив рядов, в каждом до 3 кнопок, всего до 6 рядов — лишние отбрасываются. Один ряд можно передать без вложенного массива. В url принимаются только адреса http и https.

Копироватьbot.send(chatId, "Выберите действие:", { buttons: [
  [{ text: "Каталог", app: "https://example.com/shop" }],
  [{ text: "Открыть сайт", url: "https://cloudgram.ru" }],
  [{ text: "/start", send: true }, { text: "Скопировать код", copy: "ABC-123" }]
]});

Чат

Ошибки

При ошибке функция выбрасывает исключение с понятным текстом на русском. В Node это CloudGramError, в Python — cloudgram.CloudGramError.

Копироватьtry {
  await account.send(chatId, "текст");
} catch (e) {
  console.log(e.code, e.message);
}

Копироватьtry:
    account.send(chat_id, "текст")
except cloudgram.CloudGramError as e:
    print(e.code, e.message)

Лимиты

При превышении функция выбрасывает ошибку с кодом 429 — повторите позже.