Message ID — идентификатор сообщения

Содержание
  1. negezor/-io
  2. loadMessagePayload
  3. hasAttachments
  4. hasText
  5. hasReplyMessage
  6. hasForwards
  7. hasGeo
  8. isChat
  9. isUser
  10. isGroup
  11. isFromUser
  12. isFromGroup
  13. isEvent
  14. isOutbox
  15. isInbox
  16. isImportant
  17. id
  18. conversationMessageId
  19. peerId
  20. peerType
  21. senderId
  22. senderType
  23. clientInfo
  24. chatId
  25. createdAt
  26. text
  27. replyMessage
  28. forwards
  29. geo
  30. eventType
  31. eventMemberId
  32. eventText
  33. eventEmail
  34. messagePayload
  35. getAttachments
  36. getInviteLink
  37. editMessage
  38. editMessageText
  39. send
  40. reply
  41. sendSticker
  42. sendPhotos
  43. sendDocuments
  44. sendAudioMessage
  45. setActivity
  46. markAsImportant
  47. deleteMessage
  48. restoreMessage
  49. renameChat
  50. newChatPhoto
  51. deleteChatPhoto
  52. inviteUser
  53. kickUser
  54. pinMessage
  55. unpinMessage
  56. Система уведомлений о событиях (Webhooks) | Интеграция c UniSender по API
  57. Установить обработчик
  58. Пример вызова
  59. Список обработчиков
  60. Удалить обработчик
  61. Пример возвращаемого оповещения
  62. Описание параметров оповещения (для single_event = 0)
  63. Документация Telegram: Подробное описание MTProto
  64. Терминология
  65. Ключ сервера
  66. Идентификатор ключа
  67. Сессия
  68. Соль сервера (Server Salt)
  69. Идентификатор сообщения (msg_id)
  70. Сообщение, связанное с контентом
  71. Порядковый номер сообщения (msg_seqno)
  72. Ключ сообщения
  73. Payload (полезная нагрузка)
  74. Определение ключа AES и вектора инициализации
  75. Важные тесты
  76. Незашифрованные сообщения
  77. Зашифрованное сообщение
  78. Зашифрованное сообщение:
  79. Незашифрованное сообщение
  80. Запросы к API
  81. Основная информация о запросах
  82. Основная информация об ответах
  83. Отправка методом GET и POST
  84. Обработка ответа — объект

negezor/-io

Message ID - идентификатор сообщения
import { MessageContext } from '-io';

  • Событие message
  • Возможные подтипы new_message, edit_message

Обратите внимание

Если вы используете свойства контекста напрямую то это может привести к проблемам несовместимости кода в дальнейшем, используйте лучше методы getter'ы

Так как контекст реализует совместимость с несколькими способами получения данных

Инициализация новой инстанции

new MessageContext(, payload);

ПараметрТипОписание
Инстанция
payloadObjectОбъект сообщения

Контекст сообщений, наследует Context

loadMessagePayload

Перезагружает сообщения с сервера

Например если вы используете polling где получается только часть данных сообщения (отсутствуют полные данные о геолокации, пересланных сообщениях, прикреплениях)

context.loadMessagePayload(); // => Promise

hasAttachments

Проверяет наличие прикреплений

При передаче параметра проверит наличие всех прикреплений указанного типа

context.hasAttachments([type]); // => boolean

ПараметрТипОписание
typestringТип прикрепления

hasText

Проверяет наличие текста

context.hasText; // => boolean

hasReplyMessage

Проверяет наличие сообщения, в ответ на которое отправлено текущее

context.hasReplyMessage; // => boolean

hasForwards

Проверяет наличие пересланных сообщений

context.hasForwards; // => boolean

hasGeo

Проверяет наличие геолокации

context.hasGeo; // => boolean

isChat

Проверяет что сообщение пришло из чата (беседы)

context.isChat; // => boolean

isUser

Проверяет что сообщение пришло от пользователя

context.isUser; // => boolean

isGroup

Проверяет что сообщение пришло от группы

context.isGroup; // => boolean

isFromUser

Проверяет что сообщение пришло в диалоге с пользователем

context.isFromUser; // => boolean

isFromGroup

Проверяет что сообщение пришло в диалоге с группой

context.isFromGroup; // => boolean

isEvent

Проверяет что сообщение является событием (например приглашение пользователя)

context.isEvent; // => boolean

isOutbox

Проверяет что сообщение является исходящим

context.isOutbox; // => boolean

isInbox

Проверяет что сообщение является входящим

context.isInbox; // => boolean

isImportant

Проверяет что сообщение, является важным

context.isImportant; // => boolean

id

Возвращает идентификатор сообщения или сообщения беседы

conversationMessageId

Возвращает идентификатор сообщения из беседы

context.conversationMessageId; // => number

peerId

Возвращает идентификатор назначения

context.peerId; // => number

peerType

Возвращает тип идентификатора назначения

context.peerType; // => string

senderId

Возвращает идентификатор отправителя

context.senderId; // => number

senderType

Возвращает тип идентификатора отправителя

context.senderType; // => string

clientInfo

Возвращает информацию о клиенте отправителя

context.clientInfo; // => Object

chatId

Возвращает идентификатор чата

context.chatId; // => ?number

createdAt

Возвращает метку времени отправки сообщения в формате Unixtime

context.createdAt; // => number

text

Возвращает текст сообщения

context.text; // => ?string

replyMessage

Возвращает сообщение, в ответ на которое отправлено текущее

context.replyMessage; // => MessageReply[]

forwards

Возвращает пересланные сообщение

context.forwards; // => MessageForward[]

geo

Возвращает геолокацию

context.geo; // => Object

eventType

Возвращает тип события

context.eventType; // => ?string

eventMemberId

Возвращает идентификатор пользователя на которого произошло событие

context.eventMemberId; // => ?number

eventText

Возвращает текст события

context.eventText; // => ?string

eventEmail

Возвращает email события

context.eventEmail; // => ?string

messagePayload

Возвращает значение указанное в payload, подробнее

context.messagePayload; // => ?*

getAttachments

Возвращает прикрепления

При передаче параметра вернёт все прикрепления указанного типа

context.getAttachments([type]); // => Attachment[]

Получает ссылку для приглашения пользователя в беседу

context.getInviteLink([params]); // => Promise

Возвращает следующие свойства

ПараметрТипОписание
linkstringСсылка на беседу

editMessage

Редактирует сообщение

context.editMessage(params); // => Promise

ПараметрТипОписание
paramsObjectПараметры

editMessageText

Редактирует текст сообщения

context.editMessageText(message); // => Promise

ПараметрТипОписание
messagestringТекст сообщения

send

Отправляет сообщение в текущий диалог

context.send(text [, params]); // => Promise context.send(params); // => Promise

ПараметрТипОписание
paramsObjectПараметры сообщения

reply

Пересылает текущее сообщение с ответом

context.reply(text [, params]); // => Promise context.reply(params); // => Promise

ПараметрТипОписание
paramsObjectПараметры сообщения

sendSticker

Отправляет стикер в текущий диалог

context.sendSticker(id); // => Promise

ПараметрТипОписание
idnumberИдентификатор стикера

sendPhotos

Отправляет фото в текущий диалог

context.sendPhotos(source [, params]); // => Promise

sendDocuments

Отправляет документ в текущий диалог

context.sendDocuments(source [, params]); // => Promise

sendAudioMessage

Отправляет ое сообщение в текущий диалог

context.sendAudioMessage(source [, params]); // => Promise

setActivity

Изменяет статус на набор текста в диалоге

context.setActivity(); // => Promise

markAsImportant

Помечает сообщение(я) как важное или наоборот

context.markAsImportant([ids, params]); // => Promise

ПараметрТипОписание
idsnumber[]Идентификаторы сообщений (по умолчанию текущее)
paramsObjectДополнительные параметры

deleteMessage

Удаляет сообщение(я)

context.deleteMessage([ids, params]); // => Promise

ПараметрТипОписание
idsnumber[]Идентификаторы сообщений (по умолчанию текущее)
paramsObjectДополнительные параметры

restoreMessage

Восстанавливает текущее сообщение

context.restoreMessage(); // => Promise

renameChat

Переименовывает чат (беседу)

context.renameChat(title); // => Promise

ПараметрТипОписание
titlestringНовое название чата (беседы)

newChatPhoto

Загружает новую фотографию чата (беседы)

context.newChatPhoto(source [, params]); // => Promise

deleteChatPhoto

Удаляет фотографию чата (беседы)

context.deleteChatPhoto();

inviteUser

Приглашает нового пользователя в чат

По умолчанию идентификатор события

context.inviteUser([id]); // => Promise

ПараметрТипОписание
idnumberИдентификатор пользователя

kickUser

Исключает нового пользователя в чате

По умолчанию идентификатор события

context.kickUser([id]); // => Promise

ПараметрТипОписание
idnumberИдентификатор пользователя

pinMessage

Закрепляет сообщение

context.pinMessage(); // => Promise

unpinMessage

Открепляет сообщение

context.unpinMessage(); // => Promise

Источник: https://github.com/negezor/vk-io/blob/master/docs/ru/api-reference/contexts/message.md

Система уведомлений о событиях (Webhooks) | Интеграция c UniSender по API

Message ID - идентификатор сообщения

Webhook — механизм оповещения пользователей системы о событиях. События, о которых может уведомлять Webhook:

  • изменение статуса письма (отправлено, доставлено, отклонено, прочитано, получатель перешел по ссылке);
  • контакт отписался от списка/подписался на другой список;
  • изменение статуса рассылки;
  • изменение данных пользователя;
  • добавление подтвержденного обратного адреса
  • изменение состояния счета
  • добавление нового пользователя (для реселлеров)

Webhook используют для отслеживания изменения статусов писем в реальном времени.

Модель, используемая в Webhook, работает следующим образом: при возникновении события установленный ранее обработчик отправляет JSON на URL, который был указан для этого Webhook. Используются стандартные порты: 80 порт для HTTP и 443 порт для HTTPS. Для установки Webhook на URL с указанным портом можно передавать URL в виде: http://11.111.111.11:80

Если URL, на который отправляется Webhook, недоступен (отвечает не HTTP 200 OK, таймаут — 3 секунды), попытки отправки Webhook на этот URL до получения ожидаемого 200 ОК будут продолжаться в течение 24 часов с интервалом в 10 минут с дополнительным параметром retry_count, значение которого будет увеличиваться на 1 с каждой повторной отправкой Webhook.

Установить обработчик

установить / заменить обработчик оповещений о событиях определенного типа.

Синтаксис и URL для вызова метода
setHook (hook_url, events, [event_format, max_parallel])
https://api.unisender.com/ru/api/setHook?api_key=KEY&hook_url=URL&event_format=FORMAT&events[]=EVENT&max_parallel=NUM
Аргументы
api_key*ключ доступа к API
hook_url *на какой URL отправлять запрос при возникновении события. Фактически является идентификатором обработчика. При повторном вызове setHook с таким же hook_url данные обработчика будет заменены
event_formatформат, в котором передаются данные о событии, обязательный параметр с тремя вариантами значений:
  • json_post — параметры оповещения будут переданы в теле POST-запроса в JSON-формате, возможна группировка сразу нескольких событий разных типов в одном запросе;
  • json_post_gzip— рекомендованный способ. Совпадает с json_post, только тело POST-запроса сжато с помощью gzip;
  • http_get— устаревший вариант, параметры оповещения передаются как GET-параметры HTTP-запроса, не поддерживается событие email_status
events*ассоциативный массив, перечисляющий оповещения, которые получает обработчик. Ключами массива могут быть строки:
Ключ массиваОписание
email_statusИзменение статуса отправленного email.Допустимые значения:ok_sent — письмо отправлено;ok_delivered — письмо доставлено;ok_read— письмо прочитано;ok_link_visited — зафиксирован переход по ссылкеerr_will_retry— письмо не доставлено, но будут попытки отправить его повторно.Другие допустимые значения можно посмотреть здесь.Разрешается использовать только с форматами json_post_gzip и json_post, и запрещается с форматом http_get.
unsubscribeИзменение статуса подписки получателя (отписался от списка, подписался на список).Допустимое значение:*
subscribeИзменение статуса подписки получателя (подписался на список)Допустимые значения:* — отправлять при подписке на любой списокid списка — отправлять при подписке на список с заданным id
subscribe_primaryИзменение статуса подписки получателя (подписался на список впервые)Допустимые значения:* — отправлять при подписке на любой списокid списка — отправлять при подписке на список с заданным id
campaign_statusИзменение статуса массовой рассылки.Допустимое значение: *
email_checkДобавление подтвержденного обратного адреса.Допустимое значение: *
user_paymentДоступен только для реселлеров. Изменение состояния счета. Учитываются движения,связанные с основным и бонусным счетом.Допустимое значение: *
user_infoИзменение полей информации о пользователе.Допустимое значение: *
max_parallelнеобязательное указание максимального количество параллельных вызовов к этому обработчику. По умолчанию равно 10.
single_eventПринимает значения 1 и 0. По умолчанию: 01 — оповещение Webhook не содержит массивов, за одно оповещение информация будет возвращаться только по одному событию;0 — оповещение Webhook возвращает информацию в виде массивов (см. пример ниже).

Пример вызова

https://api.unisender.com/ru/api/setHook?api_key=XXX&hook_url=https%3A%2F%2Fmycompany.com%2Funisender-hook&event_format=json_post_gzip&events[unsubscribe]=*&events[email_status]=ok_read,ok_link_visited

Список обработчиков

listHooks — получить список всех обработчиков.

Синтаксис и URL для вызова метода
listHooks ()
https://api.unisender.com/ru/api/listHooks?api_key=KEY
Аргументы
api_key *ключ доступа к API
Возвращаемое значение
{ «result»: [{ «id»:3, «url»:»https://site.com/unisender-hook», «event_format»:»json_post_gzip», «max_parallel»:1, «single_event»:0, «events»: { «subscribe»: [«1″,»2″,»3»] } }] }

Удалить обработчик

removeHook — удалить обработчик оповещений.

Синтаксис и URL для вызова метода
removeHook (hook_url)
https://api.unisender.com/ru/api/removeHook?api_key=KEY&hook_url=URL
Аргументы
api_key *ключ доступа к API
hook_url*URL-идентификатор удаляемого обработчика

Пример возвращаемого оповещения

{ «auth»:»6931402abc4b2a76b9719d911017c592″, «num»:»12″, «events_by_user»: [ { «login»:»user_zz», «Events»: [ { «event_name»:»email_status», «event_time»:»2015-04-24 15:18:34″, «event_data»: { «email»:»user@example.

com», «campaign_id»:»124345″, «status»:»ok_read», «status_group»:»success_group», «delivery_info»: { «user_agent»:»Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, Gecko) Chrome/57.0.2987.133 Safari/537.36″, «ip»:»111.111.

111″ } } }, { «event_name»:»email_status», «event_time»:»2015-04-24 15:18:36″, «event_data»: { «email»:»user2@example.com», «email_id»:»346134″, «status»:»ok_link_visited», «status_group»:»success_group», «delivery_info»: { «user_agent»:»Mozilla/5.0 (X11; Linux x86_64)», «ip»:»111.111.

111″ } } }, { «event_name»:»unsubscribe», «event_time»:»2015-04-24 15:18:58″, «event_data»: { «email»:»user2@example.com», «campaign_id»:»87434″, «list_id»:»3346″, «Just_unsubscribed_list_ids»: [ «3346», «7473» ], «Just_subscribed_list_ids»: [ «9745» ] } } ] } ] }

Описание параметров оповещения (для single_event = 0)

Оповещения форматов json_post и json_post_gzip отправляются в виде POST-запроса на URL оповещения без дополнительных аргументов с Content-Type=application/json (и для json_post_gzip с Content-Encoding: gzip).

В случае выбора формата json_post_gzip , необходимо проводить декомпрессию GZIP объекта, перед чтением JSON. JSON-объект передается в теле запроса без задания каких-либо переменных, для чтения данных.

К примеру на PHP, можно использовать команды:- gzdecode($postData); — для декомпрессии GZIP — file_get_contents(‘php://input’); — для чтения JSON

Данные оповещения — JSON-объект со следующими полями:

массив из JSON-объектов, каждый элемент которого соответствует одному пользователю. Более одного элемента в этом массиве может быть только для реселлеров — реселлеры могут получить уведомление о событиях сразу нескольких своих пользователей в одном вызове, в остальных случаях этот массив состоит из одного элемента.

ПараметрОписание
authMD5-хэш строкового тела сообщения, в котором значение auth заменено на api_key пользователя, чей обработчик вызывается. С помощью этого получатель оповещения может как провести аутентификацию, так и проверить целостность оповещения.Для генерации auth сформировать полностью тело оповещения в JSON, вместо значения auth подставить значение api_key пользователя и вычислить md5 от тела. Затем заменить в сообщении api_key на получившийся md5, записанный в шестнадцатеричном виде в lowercase.Для проверки auth надо заменить его значение на api_key, также вычислить md5 от тела оповещения и сверить его со значением auth, полученном в изначальном теле оповещения.
numна какой URL в формате punycode отправлять запрос при возникновении события. Фактически является идентификатором обработчика. При повторном вызове setHook с таким же hook_url данные обработчика будет заменены.
events_by_userмассив из JSON-объектов, каждый элемент которого соответствует одному пользователю. Более одного элемента в этом массиве может быть только для реселлеров — реселлеры могут получить уведомление о событиях сразу нескольких своих пользователей в одном вызове, в остальных случаях этот массив состоит из одного элемента.
loginлогин пользователя, оповещение о событиях которого мы передаём в рассматриваемом элементе массива events_by_user.
eventsмассив событий пользователя с вышеуказанным логином, каждый элемент массива имеет следующие поля:
event_nameимя события, одно из: email_check, unsubscribe, activate, reject, campaign_status, user_payment, user_info, email_status
event_timeвремя возникновения события в формате «YYYY-MM-DD hh:mm:ss» в часовом поясе UTC
event_dataобъект с данными события, формат которых зависит от имени события. Форматы описаны ниже: *
Формат event_dataОписание
email_status
  • email — email контакта, статус доставки сообщения по которому изменён
  • email_id — идентификатор сообщения, полученный через sendEmail. Только для сообщений, отправленных через sendEmail
  • campaign_id — только для отправленных через createCampaign
  • status — статус доставки сообщения.
  • status_group — группа статуса в соответствии с названиями из результатов отправки email : «not_sent_group», «not_allowed_group» и т.п.
unsubscribe
  • email — email отписавшегося
  • campaign_id — идентификатор рассылки, по письму из которой произошла отписка
  • list_id — либо «0», либо код списка, по которому было отправлено письмо, после которого произошла отписка. «0» означает, что выполнена отписка от всех списков.
  • just_unsubscribed_list_ids — необязательный массив кодов списков, от которых только что произошла отписка. Отсутствует в случае, если была глобальная отписка была от всех списков (включая будущие).
  • just_subscribed_list_ids — необязательный массив кодов списков, на которые только что подписались (на странице отписки можно и вернуть подписку). Отсутствует в случае, если отписка была от всех списков или ни на что не подписались.
campaign_status
  • campaign_id — идентификатор рассылки, который был возвращён вызовом метода createCampaign.
  • status — статус рассылки
  • contact_count — количество контактов в рассылке
  • period_messages — количество сообщений, отправленных за счёт включённых в период. Для SMS-сообщений всегда равно 0.
  • prepaid_messages — Количество сообщений, отправленных за счёт ранее купленных.
  • pay_sum — сумма за отправку писем.
  • currency — трёхбуквенный международный код валюты, в которой посчитана сумма за отправку писем (RUB, USD, EUR, UAH)
email_checkemail — Email, право использования которого в качестве обратного адреса подтверждено пользователем.
user_payment
  • sum
  • sum_bonus
  • currency
  • description
  • new_balance
  • new_balance_bonus
user_info
  • email
  • firstname
  • middlename
  • phone
  • company
  • timezone
  • master
  • country
  • language
  • rights

Источник: https://www.unisender.com/ru/support/api/common/sistema-uvedomlenij-o-sobytiyah-webhooks/

Документация Telegram: Подробное описание MTProto

Message ID - идентификатор сообщения

Рекомендуем вам сначала ознакомиться с техническим FAQ.

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

Ключ юзера вместе с ключом сообщения определяет актуальный (текущий) 256-битный ключ и 256-битный вектор инициализации, который шифрует сообщение, используя AES-256 шифрование с расширением неопределённого искажения (infinite garble extension, IGE).

Обратите внимание, что часть сообщения, которая должна быть зашифрована, содержит переменные данные (сессию, ID сообщения, порядковый номер, соль сервера), которые явно оказывают влияние на ключ сообщения (и таким образом на ключ AES и iv). Ключ сообщения определяется 128 битами нижнего порядка от SHA1 тела сообщения (включая сессию, ID сообщения, и т. д.) Составные сообщения шифруются как одно сообщение.

Терминология

2048-битный ключ, которым обмениваются девайс клиента и сервер, созданный непосредственно во время регистрации юзера на устройстве клиента, чтобы обмениваться ключами Диффи-Хеллмана, и никогда не передаваемый через сеть.

Каждый ключ авторизации существует только для конкретного пользователя.

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

См. также создание ключа авторизации.

Ключ сервера

2048-битный ключ RSA, используемый для цифровой подписи своих собственных сообщений, в то время как происходит регистрация и генерируется ключ авторизации. Приложение имеет встроенный публичный ключ сервера, который можно использовать для проверки подписи, но нельзя использовать для подписи сообщений. Личный (приватный) ключ сервера хранится на сервере и изменяется очень редко.

Идентификатор ключа

64 бита нижнего порядка хеша SHA1 ключа авторизации используется, чтобы показать, какой именно ключ был использован для шифрования сообщения.

Ключи должны уникально определяться 64-мя битами нижнего порядка их SHA1, и в случае коллизии/столкновения, ключ авторизации генерируется заново.

Нулевой идентификатор ключа (zero key identifier) означает, что шифрование не было использовано, что разрешено для ограниченного набора типов сообщений, используемых во время регистрации для генерации ключа авторизации, основанного на обмене Диффи-Хеллмана.

Сессия

(Рандомное) 64-битное число, сгенерированное клиентом для того, чтобы различать отдельные (индивидуальные) сессии (например, между разными инстанциями приложения, созданными с помощью одного и того же ключа авторизации).

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

Сервер может в одностороннем порядкезабыть любые сессии клиента; клиенты должны быть способны справиться с этим.

Соль сервера (Server Salt)

(Рандомное) 64-битное число, периодически (например, каждые 24 часа) изменяемое (отдельно для каждой сессии) по запросу сервера.

Все последующие сообщения должны содержать новый salt (хотя, сообщения со старым salt’ом принимаются на протяжении следующих 300 секунд).

Предназначается для защиты против атак повторного воспроизведения, и для определённых уловок/трюков, связанных с регулировкой часов клиента к моменту в отдалённом будущем.

Идентификатор сообщения (msg_id)

(Зависимое от времени) 64-битное число, используемое для того, чтобы уникально идентифицировать сообщение внутри сессии. Идентификаторы сообщения клиента кратны четырём (делятся на 4), остаток от деления идентификатора сообщения сервера на 4 приравнивается к 1 если сообщение является ответом на сообщение клиента, и к трём в остальных случаях.

Идентификаторы сообщения клиента должны увеличиваться монотонно (внутри одной сессии), так же как идентификаторы сообщений сервера, и должныпримерно равняться unixtime*232. Таким образом, идентификатор сообщения указывает на приблизительный момент времени, в который сообщение было создано.

Сообщение отклоняется через 300 секунд после того, как оно было создано, или за 30 секунд до того как оно будет создано (это необходимо для защиты против атак повторноговоспроизведения). В этой ситуации, оно должно быть отправлено заново с другим идентификатором (или помещено в контейнер с более высоким идентификатором).

Идентификатор контейнера сообщений обязательно должен быть больше, чем идентификатор вложенных в него сообщений.

Важно: чтобы противостоять атакам повторного воспроизведения, нижние 32 бита msg_id переданные клиентом, должны быть не пустые и должны представлять собой дробную часть от момента времени, в который было создано сообщение. Довольно быстро сервер начнёт игнорировать сообщения, в которых нижние 32 бита msg_id содержат слишком много нулей.

Сообщение, связанное с контентом

Сообщение, требующее точного подтверждения. Это включает все сообщения юзера и многие из сообщений сервера, фактически все, кроме контейнеров и подтверждений.

Порядковый номер сообщения (msg_seqno)

32-битное число, равное двойному числу «связанных с контентом» сообщений (которые требуют подтверждения, и в частности те, которые не являются контейнерами) созданных отправителем до этого сообщения и впоследствии увеличивающееся на один если текущее сообщение является сообщением, связанным с контентом. Контейнер всегда генерируется после того, как генерируется то, что он содержит; таким образом, его порядковый номер больше либо равен порядковым номерам сообщения, содержащимся в нём.

Ключ сообщения

128 бит нижнего порядка хеша SHA1 части сообщения, которая будет зашифрована (включая внутренний заголовок и исключая байты выравнивания данных).

Заголовок (16 байт), добавляемый перед сообщением или контейнером до того, как они все вместе будут зашифрованы. Состоит из соли сервера (64 бита) и сессии (64 бита).

Заголовок (24 байта), добавляемый перед зашифрованным сообщением или контейнером. Состоит из идентификатора ключа (64 бита) и ключа сообщения (128 бит).

Payload (полезная нагрузка)

Внешний заголовок + зашифрованное сообщение или контейнер.

Определение ключа AES и вектора инициализации

2048-битный ключ авторизации (auth_key) и 128-битный ключ сообщения (msg_key) используются для вычисления 256-битного ключа AES (aes_key) и 256-битного вектора инициализации (aes_iv), которые в дальнейшем используются, чтобы зашифровать часть сообщения, которая должна быть зашифрована (то есть всё за исключением внешнего заголовка, который добавляется позднее) с AES-256 в режиме расширения неопределённого искажения (infinite garble extension, IGE).

Алгоритм для вычисления aes_key и aes_iv из auth_key and msg_key таков:

sha1_a = SHA1 (msg_key + substr (auth_key, x, 32));sha1_b = SHA1 (substr (auth_key, 32+x, 16) + msg_key + substr (auth_key, 48+x, 16));sha1_с = SHA1 (substr (auth_key, 64+x, 32) + msg_key);sha1_d = SHA1 (msg_key + substr (auth_key, 96+x, 32));aes_key = substr (sha1_a, 0, 8) + substr (sha1_b, 8, 12) + substr (sha1_c, 4, 12);aes_iv = substr (sha1_a, 8, 12) + substr (sha1_b, 0, 8) + substr (sha1_c, 16, 4) + substr (sha1_d, 0, 8);

Где x = 0 для сообщений передаваемых от клиента к серверу и x = 8 для сообщений от сервера клиенту.

1024 бита нижнего порядка auth_key не включены в вычисление. Они могут (вместе с оставшимися битами или отдельно) использоваться на девайсе клиента для шифрования локальной копии данных, полученных от сервера.

512 бит нижнего порядка auth_key не хранятся на сервере; следовательно, если девайс клиента использует их, чтобы зашифровать локальные данные, и если юзер теряет ключ или пароль, расшифровка локальных данных невозможна (даже если могут быть получены данные с сервера).

Когда AES используется для шифровки блока данных длиной, не делимой по 16 байт, данные подбиваются рандомными байтами до минимальной длины, делимой по 16 байт, непосредственно перед тем как будут зашифрованы.

Важные тесты

Когда зашифрованное сообщение получено, должно быть проверено, что msg_key фактически равен 128 битам нижнего порядка хэша SHA1 от предварительно зашифрованной порции, и что msg_id имеет чётный результат для сообщений от клиента к серверу, и нечётный — для сообщений от сервера к клиенту.

Примечание переводчика: имеется в виду бит чётности. Вычисляется сложением по модулю 2, результат 0 считается чётным, результат 1 — нечётным.

Дополнительно, идентификаторы (msg_id) последних N сообщений, полученных от другой стороны, должны быть сохранены, и если сообщение приходит с msg_id меньшим или равным любому из сохранённых значений, сообщение будет проигнорировано. В противном случае, новый msg_id сообщения добавляется к комплекту, и, если число сохранённых значений msg_id больше чем N, самое старое (т. е. самое нижнее) забывается.

Дополнительно, значения msg_id, относящиеся ко времени более 30 секунд в будущем и более 300 секунд в прошлом, игнорируются. Это особенно важно для сервера. Для клиента это также будет полезным (для защиты от атаки повторного воспроизведения), но только если он его настройки времени точны (например, если его время было синхронизировано с временем сервера).

Определённые сервисные сообщения «от клиента к серверу», содержащие данные, отправленные клиентом серверу (например, msg_id последнего запроса клиента) могут, тем не менее, быть обработаны на/в клиенте даже если время «неправильное». Это особенно верно для сообщений, которые меняют сервер-salt и уведомлений о неправильных настройках времени у клиента. См. мобильный протокол: сервисные сообщения.

Юзерам, заботящимся о безопасности, может быть предложено защитить паролем ключ авторизации — примерно таким же способом как в ssh.

Это достигается добавлением SHA1 ключа впереди ключа, после чего вся строка шифруется с использованием AES в режиме CBC и ключа, равного юзерскому (текстовому) паролю.

Когда юзер вводит пароль, сохранённый защищённый пароль расшифровывается и проверяется сравнением с SHA1. С точки зрения юзера, это практически то же самое, что и использования пароля вебсайта или приложения.

Незашифрованные сообщения

Специальные только-текстовые сообщения могут быть использованы для создания ключа авторизации, также как для выполнения синхронизации времени.

Они начинаются с auth_key_id = 0 (64 бита), что означает что здесь нет auth_key. За этим следует непосредственно тело сообщения в сериализованном формате без внутреннего и внешнего заголовка.

Идентификатор сообщения (64 бита) и длина тела в байтах (32 байта) добавляются до тела сообщения.

Только очень ограниченное количество сообщений определённых типов могут быть переданы как только-текстовые.

Зашифрованное сообщение

auth_key_idint64msg_keyint128encrypted_dataбайты
  • auth_key_id — идентификатор ключа
  • msg_key — ключ сообщения
  • encrypted_data — зашифрованные данные

Зашифрованное сообщение:

Содержит шифротекст для следующих данных:

  • salt — сервер salt (соль сервера)
  • session_id — сессия
  • message_id — идентификатор сообщения
  • seq_no — порядковый номер сообщения
  • message_data_length — длина данных сообщения
  • message_data — данные сообщения

Незашифрованное сообщение

Ключ авторизации обычно создаётся один раз для каждого юзера во время процесса установки приложения непосредственно перед регистрацией. Непосредственно сама регистрация происходит после того, как создан ключ авторизации.

Однако, юзеру может быть предложено заполнить форму регистрации одновременно с тем, как в фоновом режиме генерируется ключ авторизации.

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

См. создание ключа авторизации.

В то время как создаётся ключ авторизации, клиент определяет какова соль сервера (server salt) (то есть для всех сессий, которые будут созданы в ближайшем будущем для ключа). Далее, клиент создаёт первую (зашифрованную) сессию, используя ключ, и каждая последующая коммуникация (включая передачу регистрационной информации юзера и валидацию номера телефона) будут происходить внутри сессии.

Источник: https://tlgrm.ru/docs/mtproto/description

Запросы к API

Message ID - идентификатор сообщения

  • /
  • /

Основная информация о запросах

Основная информация об ответах

Отправка методом GET и POST

Обработка ответа — объект

Основная информация о запросах

Запрос — обращение от одного сервиса к другому сервису для получения или отправки информации.

Запросы можно делать к любому стороннему сервису, который их поддерживает. Если вы не можете найти документацию к API в публичном доступе, свяжитесь с поддержкой или разработчиками системы.

Ботмама умеет отправлять запросы и принимать ответы только в формате JSON. Если нужная вам система не поддерживает JSON, нужно искать сервис, который изменяет формат запроса, или писать кодом скрипт обработки на сервере. Ещё можно использовать сервисы, которые заменяют интеграцию запросами — например, Zapier.

Существует множество типов запросов, мы используем только самые распространённые: GET, POST, PUT, DELETE.

  • GET чаще всего используется как запрос получения информации. В отдельных случаях он может использоваться равнозначно с другими типами. Например, в Telegram можно использовать и GET, и POST для одинаковых запросов.
  • POST используется для отправки информации и создания объектов. Этим методом чаще всего создаются заявки, формируются заказы и т.д.
  • PUT обновляет информацию об объекте.
  • DELETE удаляет созданный объект.

Тело в GET запросе можно передавать в строке URL, для остальных запросов — только в специальном поле компонента.

Основная информация об ответах

Ответом на запрос может быть информация об ошибке или об удачном запросе с дополнительными данными или без них.

Об ответах на запросы можно подробно узнать в Википедии.

Чаще всего приходят ответы успеха и ошибок.

Если запрос прошёл успешно, код будет иметь значение, начинающееся на 2:

  • 200 OK — успешный запрос.
  • 201 Created — в результате успешного выполнения запроса был создан новый ресурс.
  • 202 Accepted — запрос был принят на обработку, но она не завершена.

Если запрос не прошёл из-за ошибки параметров запроса, Ботмама считает его успешным, но в объекте {{last_request}} будет лежать ошибка, начинающаяся на 4:

  • 400 Bad Request — сервер обнаружил в запросе клиента синтаксическую ошибку. Этот код используется для любых ошибок такого типа, если разработчик сервиса не вложил другие значения.
  • 401 Unauthorized — для доступа к запрашиваемому ресурсу требуется авторизация.
  • 403 Forbidden — сервер понял запрос, но он отказывается его выполнять из-за ограничений в доступе для клиента к указанному ресурсу.
  • 404 Not Found — запрашиваемый ресурс не был найдет или не существует.

Если запрос не прошёл из-за ошибки сервера, Ботмама исполняет Экран при ошибке запроса. Ошибки сервера начинаются на 5:

  • 500 Internal Server Error — любая внутренняя ошибка сервера. Этот код используется, если разработчик не добавил код для описания данной ошибки.
  • 501 Not Implemented — сервер не может обработать запрос.

    Например, вы используете несуществующий метод.

  • 502 Bad Gateway — когда сервер, к которому вы делаете запрос, фактически является буфером между вами и другим сервером, получает некорректный ответ от другого сервера.

  • 503 Service Unavailable — сервер временно не может обрабатывать запросы. Такие ошибки возникают, когда сервер выключен, не имеет доступа к Сети или ограничен в доступе.
  • 504 Gateway Timeout — когда сервер, к которому вы делаете запрос, фактически является буфером между вами и другим сервером, не получает ответ от другого сервера.

Отправка методом GET и POST

Для примера мы будем использовать запросы к Telegram bot API

Авторизация запросов к Telegram проходит по токену бота. Это значит, что срабатывать запрос будет в боте, токен которого вы указали. К примеру, отправляя запрос с текстом, вы можете указать токен другого бота, и тогда сообщение будет приходить в него.

Все запросы в телеграм создаются по шаблону:

https://api.telegram.org/bot/НАЗВАНИЕ_МЕТОДА

Метод API — действие, которое должна совершить система в заданном боте.

Один из самых простых методов — sendMessage. Он отправляет текст.

Параметры запроса — обязательные и дополнительные данные, которые конкретизируют, какое действие произойдёт. Например, параметры получателя или текст, который ему придёт.

Обязательными параметрами являются chat_id и text:

  • chat_id — уникальный идентификатор пользователя в Telegram. Его мы получаем из переменной {{this_user.platform_id}}. Чтобы отправить сообщение определённому пользователю, нужно вставить значение его переменной.
  • text — текст сообщения, которое мы отправляем.

Для передачи пробелов в URL запроса нужно заменять их знаком + . Если отправить текст без замены, он оборвётся на первом пробеле.

Для запроса методом GET метод API и параметры передаются в URL запроса. Параметры от метода API отделяются знаком вопроса. Значение параметра отправляется после знака равенства. Между собой параметры отделяются знаком &

Формируем шаблон GET-запроса:

https://api.telegram.org/bot/НАЗВАНИЕ_МЕТОДА_API?параметр1=значение1&параметр2=значение2

Подставляем метод и параметры для отправки текста:

https://api.telegram.org/bot/sendMessage?chat_id=значение1&text=значение2

Вставляем значения токена и параметров, чтобы получить работающий путь (URL) GET-запроса:

https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage?chat_id=123456&text=Привет+из+бота!

Теперь попробуем сделать тот же запрос, но методом POST.

Параметры запроса и их значения составляют тело запроса. Поэтому в строке URL мы оставляем только:

https://api.telegram.org/bot/НАЗВАНИЕ_МЕТОДА

Для метода POST в URL передаётся только метод API, параметры отправляются в теле запроса в формате JSON.

JSON — один из форматов данных. Он состоит из пар данных: ключ-значение. Ключ — название параметра, значение — значение параметра (может быть определенным или переменной).

Чтобы сделать тело с нашими параметрами, указываем их в формате JSON:

{ «chat_id»: «123456», «text»: «Привет из бота!» }

Важно следить за синтаксисом. Если вы забудете поставить хотя бы один символ, запрос не сработает. Это самая распространённая ошибка при отправке запросов.

Вставляем GET-запрос на экран в конструкторе:

* отмечены обязательные поля

Вставляем Post-запрос на экран в конструкторе:

* отмечены обязательные поля

Для тестирования можете попробовать удалить предыдущее сообщение методом deleteMessage.

Обязательные параметры:

  • chat_id — уникальный идентификатор пользователя в боте. Его мы получаем как основную переменную {{this_user.platform_id}}.
  • message_id — уникальный идентификатор сообщения, находится в переменной {{last_telegram_message_id}}.

Обработка ответа — объект

Для примера мы будем использовать ресурс https://www.cbr-xml-daily.ru/

В нём мы выбираем запрос в формате JSON:

https://www.cbr-xml-daily.ru/daily_json.js

Открываем его как обычную ссылку в браузере и получаем ответ в JSON-формате.

Чтобы ответ был удобным для чтения, поставьте расширение на браузер. Для Google Chrome это JSON Formatter

Например, мы хотим получить стоимость 1 белорусского рубля. Находим часть, где выводится значение BYN и составляем переменную.

Ответ на запрос находится в объекте {{last_request}}

Чтобы вывести переменную внутри текста, вводим её внутри фигурных скобок:

Источник: https://botmother.com/ru/doc/requests-and-integrations/api-requests

Все термины
Добавить комментарий

;-) :| :x :twisted: :smile: :shock: :sad: :roll: :razz: :oops: :o :mrgreen: :lol: :idea: :grin: :evil: :cry: :cool: :arrow: :???: :?: :!: