Большинство современных мессенджеров предоставляют своим пользователям API, предназначенные для различных задач. На примере Telegram посмотрим, как работать с API, что они умеют и чем могут быть полезны.
Если вы не зарегистрированы в Telegram — самое время зарегистрироваться. Вы можете не пользоваться аккаунтом в повседневности, но для учёбы он необходим. Возможно, вам будет удобно работать через десктопную версию приложения, её можно скачать с официального сайта: https://telegram.org/.
API в Telegram
У мессенджера Telegram есть два API — Bot API и Client API.
- Bot API предназначен для работы с ботами.
- Client API позволяет управлять вашим аккаунтом: отправлять от вашего имени сообщения, вступать в группы или изменять информацию в своём профиле.
Начнём с Client API.
Управление аккаунтом через Client API
Для работы с Client API необходима аутентификация по токену, получить его можно на специальном сайте Telegram.
Получение токена для Client API
Зайдите на https://my.telegram.org и введите номер телефона, привязанный к вашему аккаунту:
Запустите Telegram: вам придёт код подтверждения для сайта, введите его в поле на сайте и нажмите кнопку Next.
В открывшемся окне нажмите на ссылку API development tools и введите данные для создания нового приложения. Заполните как минимум поля App title, Short name и укажите платформу: Web.
В следующем окне скопируйте и сохраните значения api_id и api_hash.
Готово! Эти идентификаторы вы перенесёте в код, они будут передаваться в Client API с каждым вашим запросом — и Client API опознает вас как владельца определённого аккаунта.
Программный клиент Telegram
Отправлять запросы к Client API можно через ваш Telegram-клиент на телефоне или на компьютере или через программный клиент.
Для работы с Client API существует несколько популярных Python-библиотек, которые эмулируют работу приложения. С чем-то подобным вы сталкивались в теме «Тестирование Django»: класс Client() в тестах эмулировал работу браузера, отправляя запросы и получая ответы от сервера.
Для создания программного клиента возьмём библиотеку pyrogram.
Создайте директорию /client_api, перейдите в неё, установите и активируйте виртуальное окружение, установите библиотеку pyrogram :
mkdir client_api # Создаём директорию cd client_api # Переходим в эту директорию python3 -m venv venv # Создаём виртуальное окружение . venv/bin/activate # Активируем виртуальное окружение # Для Windows команда source venv/Scripts/activate pip3 install pyrogram # Устанавливаем библиотеку
Создайте и откройте файл /client_api/main.py в текстовом редакторе, перенесите в него код:
from pyrogram import Client api_id = api_hash = «» with Client(«my_account», api_id, api_hash) as app: # Первый параметр метода send_message — id (int) или имя (str) того пользователя, # которому будет отправлено сообщение. # Зарезервированное слово «me» означает ваш собственный аккаунт. app.send_message(«me», «Привет, это я!»)
Сохраните файл и запустите его:
python3 main.py
При первом запуске программы в командной строке будет запрошен номер телефона, на который зарегистрирован ваш Telegram-аккаунт. Введите номер в консоль, после этого на телефон или в Telegram придёт проверочный код. Скопируйте этот код и вставьте в командную строку. Эта процедура выполняется только один раз, после этого приложение будет зарегистрировано.
Из вашего приложения будет отправлено сообщение. «me» — это зарезервированное слово, заменяющее ID аккаунта, для которого выдан токен. Следовательно, сообщение будет отправлено из вашего аккаунта в ваш аккаунт; оно отобразится во вкладке «Избранное» в вашем мессенджере.
Если изменить «me» на ID аккаунта вашего друга в Telegram, то сообщение уйдёт ему.
Начните диалог с ботом: нажмите кнопку Start.
Для начала бот отправит вам информацию о вашем аккаунте: ID, имя (то, что указано в полях First и Last name) и язык.
Если Telegram запущен на мобильном устройстве — вызовите меню долгим нажатием на сообщение и проделайте всё то же самое.
В ответ бот отправит информацию о пользователе: ID, имя (First name) и фамилию (Last name).
Список всех доступных методов библиотеки pyrogram доступен в документации.
Не увлекайтесь рассылкой сообщений через бота: в Client API есть лимит по количеству запросов. Если вы будете слишком часто отправлять сообщения, Telegram может принять вас за злоумышленника-спамера и забанить, лишить доступа к сервису. Telegram не раскрывает точных ограничений.
В первый раз блокировка продлится 24 часа, последующие будут длиться дольше. Во избежание блокировок мы бы предложили отправлять сообщения только на аккаунты из вашего контакт-листа и не отправлять суммарно более десяти сообщений в час.
Похожие записи:
- Бот в Telegram
- Библиотека python-telegram-bot
- Инструментарий для тестирования API
- Unittest в Django: тестирование URLs
Источник: mob25.com
Аутентификация Telegram WebApp на JavaScript
Сегодня я расскажу о хитром механизме аутентификации в Telegram WebApp Bot. Что такое бот Telegram WebApp? Это просто возможность запустить WebView с вашим сайтом внутри Telegram. Вы можете прочитать больше здесь».
Зачем нам здесь авторизация?
Ваш сайт должен открываться только в Telegram WebView. Итак, что, если бы кто-то сделал это в браузере? «Хакеры» могут использовать поддельные пользовательские данные, идентификаторы и так далее. Нам нужно защитить наш API от людей за пределами Telegram.
Как?
Telegram использует HMAC (код аутентификации сообщений на основе хэша). Итак, если вы инициализируете Telegram SDK на своем веб-сайте, вы сможете использовать эти данные для идентификации пользователя. Давайте шаг за шагом создадим механизм аутентификации.
Шаг 1: передача данных через запросы
Telegram SDK устанавливает пользовательские данные в глобальном масштабе вашего приложения. Есть данные о пользователях, их смартфонах, цветовых темах и многом другом. Вы можете найти это здесь:
window.Telegram.WebApp
Итак, есть поле, в котором нам нужно проверять наши сообщения. Telegram предоставляет специальное поле initData. Мы должны использовать это поле для проверки всех запросов от Telegram WebApp к нашему серверу.
const < initData >= window.Telegram.WebApp
Это просто строка, похожая на строку запроса GET, которая содержит несколько полей:
auth_date=user=
Вот и все. Необходимые данные будут в наших запросах.
Шаг 2: создание промежуточного ПО аутентификации
Я использую Nest.js в своем проекте, но способ создания промежуточного ПО почти одинаков в Express.js и Nest.js.
Во-первых, мы должны создать промежуточное ПО с помощью нескольких строк кода:
export function telegramAuthMiddleware(req, res, next) < // take initData from headers const iniData = req.headers[ ‘telegram-data’ ]; // use our helpers (see bellow) to validate string // and get user from it const user = checkAuthorization(iniData); // add uses to the request «context» for the future if (user) < req.user = user; next(); // or if the validation is failed response 401 >else < res.writeHead(401, < ‘content-type’: ‘application/json’ >); res.write(‘unauthorized’); res.end(); > >
Этот код просто берет initData из заголовков и использует вспомогательную функцию для их проверки.
Шаг 3: анализ initData
Я собираюсь описать процесс, а затем покажу вам код.
- Нам нужно разобрать строку initData
- Возьмите поле хэш из этой строки и сохраните его на будущее.
- Отсортируйте остальные поля в алфавитном порядке
- Соедините эти поля с помощью разрыва строки (n). Почему? Да просто так! Телеграм хочет!
Итак, после этих шагов у нас есть две строки: hash, telegramCheckString,и metaData (содержит пользователя, auth_date и query_id)
Давайте посмотрим на код:
function parseAuthString(iniData) < // parse string to get params const searchParams = new URLSearchParams(iniData); // take the hash and remove it from params list const hash = searchParams.get(‘hash’); searchParams.delete(‘hash’); // sort params const restKeys = Array.from(searchParams.entries()); restKeys.sort(([aKey, aValue], [bKey, bValue]) =>aKey.localeCompare(bKey)); // and join it with n const dataCheckString = restKeys.map(([n, v]) => `$=$`).join(‘n’); return < dataCheckString, hash, // get metaData from params metaData: < user: JSON.parse(searchParams.get(‘user’)), auth_date: searchParams.get(‘auth_date’), query_id: searchParams.get(‘query_id’), >, >; >
Шаг 4: проверка хэша
Это последняя глава нашего путешествия. Нам нужно проанализировать initData, используя функцию из предыдущего шага и немного криптографии.
Коды ошибок Telegram API
В данной статье собраны ошибки, возвращаемые API Telegram. Числовое значение аналогично статусу HTTP. Содержит информацию о типе возникшей ошибки: например, ошибка ввода данных, ошибка конфиденциальности или ошибка сервера.
303 SEE_OTHER
Запрос необходимо повторить, но направить в другой центр обработки данных.
- FILE_MIGRATE_X: файл, к которому нужно получить доступ, в настоящее время хранится в другом центре обработки данных.
- PHONE_MIGRATE_X: номер телефона, который пользователь пытается использовать для авторизации, связан с другим центром обработки данных.
- NETWORK_MIGRATE_X: исходный IP-адрес связан с другим центром обработки данных (для регистрации)
- USER_MIGRATE_X: пользователь, личность которого используется для выполнения запросов, связан с другим центром обработки данных (для регистрации)
Во всех этих случаях строковый литерал описания ошибки содержит номер центра обработки данных (вместо X), в который должен быть отправлен повторный запрос.
ОШИБКА 400, НЕВЕРНЫЙ ЗАПРОС
Запрос содержит ошибки. В случае, если запрос был создан с использованием формы и содержит данные, созданные пользователем, пользователь должен быть уведомлен о том, что данные должны быть исправлены, прежде чем запрос будет повторен.
- FIRSTNAME_INVALID: имя недействительно
- LASTNAME_INVALID: фамилия недействительна
- PHONE_NUMBER_INVALID: номер телефона недействителен
- PHONE_CODE_HASH_EMPTY: phone_code_hash отсутствует
- PHONE_CODE_EMPTY: phone_code отсутствует
- PHONE_CODE_EXPIRED: срок действия кода подтверждения истек
- API_ID_INVALID: комбинация api_id / api_hash недействительна
- PHONE_NUMBER_OCCUPIED: номер телефона уже используется
- PHONE_NUMBER_UNOCCUPIED: номер телефона еще не используется
- USERS_TOO_FEW: недостаточно пользователей (например, для создания чата)
- USERS_TOO_MUCH: превышено максимальное количество пользователей (например, для создания чата)
- TYPE_CONSTRUCTOR_INVALID: конструктор типа недействителен
- FILE_PART_INVALID: неверный номер части файла.
- FILE_PARTS_INVALID: недопустимое количество частей файла.
- FILE_PART_Х_MISSING: часть X (где X — номер) файла отсутствует в хранилище
- MD5_CHECKSUM_INVALID: контрольные суммы MD5 не совпадают
- PHOTO_INVALID_DIMENSIONS: размеры фотографии недействительны
- FIELD_NAME_INVALID: поле с именем FIELD_NAME недействительно
- FIELD_NAME_EMPTY: поле с названием FIELD_NAME отсутствует
- MSG_WAIT_FAILED: запрос, который должен быть выполнен перед обработкой текущего запроса, возвратил ошибку
- MSG_WAIT_TIMEOUT: запрос, который должен быть выполнен перед обработкой текущего запроса, еще не завершил обработку
401 ОШИБКА ДОСТУПА
Произошла попытка несанкционированного использования функций, доступных только авторизованным пользователям.
- AUTH_KEY_UNRIGN: Ключ не зарегистрирован в системе
- AUTH_KEY_INVALID: ключ недействителен
- USER_DEACTIVATED: пользователь удален / деактивирован
- SESSION_REVOKED: авторизация была аннулирована из-за того, что пользователь завершил все сеансы
- SESSION_EXPIRED: срок авторизации истек
- AUTH_KEY_PERM_EMPTY: метод недоступен для временного ключа авторизации, не привязан к постоянному
403 ЗАПРЕЩЕНО
Нарушение конфиденциальности. Например, попытка написать сообщение кому-то, кто занес текущего пользователя в черный список.
404 НЕ НАЙДЕНО
Попытка вызвать несуществующий объект, например метод.
406 NOT_ACCEPTABLE
Подобно 400 BAD_REQUEST , но приложение не должно отображать сообщения об ошибках для пользователя в пользовательском интерфейсе в результате этого ответа. Вместо этого сообщение об ошибке будет доставлено через updateServiceNotification.
420 FLOOD
Превышено максимально допустимое количество попыток вызвать данный метод с заданными входными параметрами. Например, при попытке запросить большое количество текстовых сообщений (SMS) на один и тот же номер телефона.
- FLOOD_WAIT_X: требуется ожидание X секунд (где X — число)
500 ВНУТРЕННИЙ
Произошла внутренняя ошибка сервера во время обработки запроса; например, произошел сбой при доступе к базе данных или файловому хранилищу.
Если клиент получает ошибку 500 или вы считаете, что эта ошибка не должна была возникнуть, пожалуйста, соберите как можно больше информации о запросе и ошибке и отправьте ее разработчикам.
Другие коды ошибок
Если сервер возвращает ошибку с кодом, отличным от перечисленных выше, это может рассматриваться как ошибка 500 и рассматриваться как внутренняя ошибка сервера.
- API
- Telegram
- error code
Источник: error-log.ru