VK puppeting bridge for Matrix, taking use of VK Communities API
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

267 lines
15 KiB

11 months ago
11 months ago
11 months ago
11 months ago
10 months ago
11 months ago
10 months ago
11 months ago
8 months ago
8 months ago
  1. [![Matrix](https://img.shields.io/matrix/mx-puppet-vk:sunbutt.faith?logo=matrix&server_fqdn=gospel.sunbutt.faith)](https://matrix.to/#/#mx-puppet-vk:inex.rocks?via=inex.rocks&via=sunbutt.faith)
  2. # mx-puppet-vk
  3. This is a Matrix <-> VK bridge based on [mx-puppet-bridge](https://github.com/Sorunome/mx-puppet-bridge) and [VK-IO](https://github.com/negezor/vk-io).
  4. Это мост между Matrix и Вконтакте, основанный на [mx-puppet-bridge](https://github.com/Sorunome/mx-puppet-bridge) и [VK-IO](https://github.com/negezor/vk-io).
  5. [Документация на русском ниже.](#docs-in-russian)
  6. It is in early development. Right now it logs message data when log level includes "info" level.
  7. Relay mode works too, but we don't recommend it.
  8. ## Installation
  9. ```bash
  10. git pull https://github.com/innereq/mx-puppet-vk
  11. npm install
  12. npm run build
  13. ```
  14. Next copy the `sample.config.yaml` to `config.yaml`, edit it and then run `npm run start -- -r` to generate a registration file.
  15. Register that one with synapse and start the bridge with `npm run start`.
  16. ## Features and roadmap
  17. - Matrix -> VK
  18. - [x] Text content
  19. - [x] Image content
  20. - [x] Audio/Video content
  21. - [x] Other files
  22. - [x] Replies
  23. - [x] Typing notifs - [see note](#Note-on-presence-from-matrix-side)
  24. - [ ] Presence - ~~not possible yet~~
  25. - [x] Read notifications
  26. - [x] Message edits
  27. - [x] Message redacts - works as edit, real redact unavailable without being admin in chat
  28. - [ ] Initiate rooms from the matrix side
  29. - VK -> Matrix
  30. - [x] Text content
  31. - [x] Forwards
  32. - [x] Image content
  33. - [x] Audio content
  34. - [ ] Video content
  35. - [x] Stickers
  36. - [x] Other files
  37. - [ ] Presence - not effective to track
  38. - [x] Typing notifs
  39. - [x] User profiles
  40. - [ ] Read notifications - not effective to track
  41. - [x] Message edits
  42. - [ ] Message redacts - doesn't work
  43. - [ ] Autopopulate rooms with users
  44. - Edge cases to work around
  45. - [ ] Access token revoked on VK side
  46. - [ ] Bot is kicked out on VK side
  47. - Probably more, send an issue!
  48. ## Usage
  49. [Video demonstration by Coma Grayce](https://youtu.be/nBRBUA9beXs)
  50. 1. Get VK community token (Just open the "Manage community" tab, go to "API usage" tab and click "Create token"). Token must have community control and message permissions.
  51. 2. Activate Bots Long Poll API ("Manage community" → "API usage" → "Bots Long Poll API") and choose the latest API version. Make sure that under event types all message-realted events are turned on.
  52. 3. Activate an option to message your community. To allow group chats, activate it under bot capabilities.
  53. 4. On matrix, contact `@_vk_puppet_bot:your.domain` and type `link <vk token>`
  54. 5. Now, if someone contacts your community, you will be invited to the corresponding room on Matrix.
  55. Plese note: when community is invited to the group chat as a bot, make sure it has message access. Only chat admins can change bot permissions.
  56. Bridge doesn't handle being kicked from chat yet.
  57. ### Relay usage
  58. See [mx-puppet-bridge docs](https://github.com/Sorunome/mx-puppet-bridge#relay-mode)
  59. ### Note on presence from Matrix side
  60. For presence bridging from Matrix side (including typing) your Synapse server has to be on 1.22.0 or later.
  61. Also, make sure your registration file contains this:
  62. ```
  63. de.sorunome.msc2409.push_ephemeral: true
  64. ```
  65. ## Usage as User puppet, for bridge all personal messages and chats
  66. _This is experimental and is not the main goal of this bridge._
  67. 1. Select the `CLIENT_ID` - it is ID of registered application, that allowed to access your messages. You can register your own application (and [require access for Messages API](https://vk.com/dev/messages_api) from VK owners), or reuse ID of already registered application.
  68. You can select some of popular applications for reuse the `CLIENT_ID` via [VKhost](https://vkhost.github.io/) service.
  69. Example of URL to generate `access_token`:
  70. ```
  71. https://oauth.vk.com/authorize?client_id=<CLIENT_ID>&display=page&redirect_uri=https://oauth.vk.com/blank.html&scope=friends,messages,offline,docs,photos,video&response_type=token&v=5.126
  72. ```
  73. You must review grant access list and allow access for selected `CLIENT_ID`. After pressing "Allow" you browser will be redirected to other URL.
  74. 2. Get the generated `access_token` string from redirected URL via looking the `&access_token=` GET parameter, here is example of url:
  75. ```
  76. https://oauth.vk.com/blank.html#access_token=df89482ba9a19e5a2dee85031612b021a08cd521115e1c7d2cd70710a50783105cfeae7386ab4f1003b54&expires_in=0&user_id=12345&email=vasya@example.com
  77. ```
  78. where the access token is `df89482ba9a19e5a2dee85031612b021a08cd521115e1c7d2cd70710a50783105cfeae7386ab4f1003b54` (don't use it, it is only example).
  79. 3. On Matrix client, create private chat with `@_vk_puppet_bot:your.domain` user and type `link <access_token>` command.
  80. ### Implemented features using a user token instead of group bot:
  81. - Matrix -> VK (AS A USER)
  82. - [x] Text content
  83. - [x] Image content
  84. - [x] Audio messages
  85. - [x] Other files
  86. - [x] Replies
  87. - [x] Typing notifs
  88. - [ ] Presence
  89. - [x] Read notifications
  90. - [x] Message edits
  91. - [x] Message redacts - in 24 hours
  92. - [ ] Initiate rooms from the matrix side
  93. - VK (AS A USER) -> Matrix
  94. - [x] Auth as a user instead of group
  95. - [x] Text content
  96. - [x] Replies (as forwards)
  97. - [x] Forwards
  98. - [x] Image content
  99. - [ ] Audio content - unavailable via user tokens
  100. - [ ] Video content - unavailable via user tokens
  101. - [x] Stickers
  102. - [x] Other files
  103. - [ ] Presence
  104. - [x] Typing notifs
  105. - [x] User profiles
  106. - [ ] Read notifications
  107. - [x] Message edits
  108. - [ ] Message redacts
  109. - [ ] Autopopulate rooms with users
  110. To avoid imposture, do **not** use relay mode with user tokens!
  111. # Docs in Russian
  112. Это мост между Matrix и Вконтакте, основанный на [mx-puppet-bridge](https://github.com/Sorunome/mx-puppet-bridge) и [VK-IO](https://github.com/negezor/vk-io).
  113. Находится в ранней разработке. Содержание сообщений выводится в логи, если уровень логов включает в себя уровень "info".
  114. Режим релея работает, но мы его не рекомендуем.
  115. ## Установка
  116. ```bash
  117. git pull https://github.com/innereq/mx-puppet-vk
  118. npm install
  119. npm run build
  120. ```
  121. Затем скопируйте `sample.config.yaml` в `config.yaml`, отредактируйте его, и затем запустите `npm run start -- -r` чтобы сгенерировать регистрационный файл.
  122. Зарегистрируйте его на вашем сервере Synapse и запустите мост коммандой `npm run start`.
  123. ## Реализованные функции и план разработки
  124. - Matrix -> Вконтакте
  125. - [x] Текстовые сообщения
  126. - [x] Изображения
  127. - [x] Аудио и видео
  128. - [x] Прочие файлы
  129. - [x] Ответы
  130. - [x] Индикатор печати - [смотрите примечание](#примечание-о-эфемерных-событиях)
  131. - [ ] Индикатор "в сети"
  132. - [x] Индикаторы прочтения
  133. - [x] Редактирование сообщений
  134. - [x] Удаление сообщений - работает как редактирование
  135. - [ ] Инициация чатов со стороны Matrix
  136. - Вконтакте -> Matrix
  137. - [x] Текстовые сообщения
  138. - [x] Пересланные сообщения
  139. - [x] Изображения
  140. - [x] Аудио
  141. - [ ] Видео
  142. - [x] Стикеры
  143. - [x] Прочие файлы
  144. - [ ] Индикатор "в сети" - Не эффективно отслеживать
  145. - [x] Индикатор печати
  146. - [x] Имена и аватарки пользователей
  147. - [ ] Индикаторы прочтения - Не эффективно отслеживать
  148. - [x] Редактирование сообщений
  149. - [ ] Удаление сообщений - не работает
  150. - [ ] Автоматическое заполнение комнаты пользователями
  151. - Крайние случаи, которые надо проработать
  152. - [ ] Токен доступа отозван со стороны Вконтакте
  153. - [ ] Бот выгнан из чата со стороны Вконтакте
  154. - Возможно больше, открывайте issue!
  155. ## Использование
  156. [Видео демонстрация от Coma Grayce](https://youtu.be/nBRBUA9beXs)
  157. 1. Получите токен сообщества Вконтакте. Откройте раздел «Управление сообществом» («Управление страницей», если у Вас публичная страница), выберите вкладку «Работа с API» и нажмите «Создать ключ доступа». Не забудьте предоставить доступ к сообщениям и **управлению сообществом**.
  158. 2. Активируйте Long Poll API (откройте раздел «Управление сообществом», на вкладке «Работа с API» → «Long Poll API» выберите «Включён») и выберите самую актуальную версию API, так как по умолчанию выбрана устаревшая, с ней не работает. Убедитесь, что во вкладке типов событий выбраны все события в категории сообщений.
  159. 3. Во вкладке сообщений, активируйте сообщения сообщества. Чтобы позволить добавлять сообщества в групповые чаты, активируйте это во вкладке возможностей ботов.
  160. 4. В matrix, напишите боту `@_vk_puppet_bot:ваш.домен` и напишите `link <токен вк>`
  161. 5. Теперь, если кто-то напишет вашему сообществу, со стороны Matrix вас пригласят в соответствующую комнату.
  162. Обратите внимание: когда сообщество приглашено в групповой чат как бот, убедитесь что у бота есть права на чтение сообщений. Только администраторы чата могут менять права ботов.
  163. ### Использование в качестве релея
  164. Смотрите [документацию mx-puppet-bridge](https://github.com/Sorunome/mx-puppet-bridge#relay-mode) (на английском)
  165. ### Примечание о эфемерных событиях
  166. Для пересылки эфемерных событий со стороны Matrix (включая индикаторы печати), ваш сервер Synapse должен быть версии 1.22.0 или выше.
  167. Также, ваш файл регистрации должен включать в себя эту строку:
  168. ```
  169. de.sorunome.msc2409.push_ephemeral: true
  170. ```
  171. ## Использование токена пользователя для доступа ко всем персональным сообщениям и чатам конкретного пользователя
  172. _Этот режим является экспериментальным и не является основной целью данного моста._
  173. 1. Выберите `CLIENT_ID` - это идентификатор приложения, которому предоставлен доступ к сообщениям пользователя. Вы можете зарегистрировать своё личное приложение (и [запросить доступ к Messages API](https://vk.com/dev/messages_api) от админов ВК), или переиспользовать ID от уже зарегистрированного приложения.
  174. Вы можете выбрать одно из популярных приложений для переиспользования `CLIENT_ID` через сервис [VKhost](https://vkhost.github.io/).
  175. Пример URL для генерации `access_token`:
  176. ```
  177. https://oauth.vk.com/authorize?client_id=<CLIENT_ID>&display=page&redirect_uri=https://oauth.vk.com/blank.html&scope=friends,messages,offline,docs,photos,video&response_type=token&v=5.126
  178. ```
  179. Вы должны перепроверить список доступа дя выбранного `CLIENT_ID` и разрешиь доступ. После нажатия кнопки "Разрешить" ваш браузер переадресует вас на другой URL.
  180. 2. Скопируйте текст сгенерированного `access_token` с переадресованного URL через просмотр GET-параметра `&access_token=`, вот пример URL:
  181. ```
  182. https://oauth.vk.com/blank.html#access_token=df89482ba9a19e5a2dee85031612b021a08cd521115e1c7d2cd70710a50783105cfeae7386ab4f1003b54&expires_in=0&user_id=12345&email=vasya@example.com
  183. ```
  184. в котором access_token это `df89482ba9a19e5a2dee85031612b021a08cd521115e1c7d2cd70710a50783105cfeae7386ab4f1003b54` (не используйте данный токен, это только пример).
  185. 3. В Матрикс-клиенте создайте приватный чат с пользователем `@_vk_puppet_bot:your.domain` и отправьте команду `link <access_token>`, заменив "<access_token>" на сгенерированный токен доступа.
  186. ### Реализованные функции для режима персонального токена пользователя:
  187. - Matrix -> Вконтакте (как пользователь)
  188. - [x] Текстовые сообщения
  189. - [x] Изображения
  190. - [x] Аудио сообщения
  191. - [x] Прочие файлы
  192. - [x] Ответы
  193. - [x] Индикатор печати
  194. - [ ] Индикатор "в сети"
  195. - [x] Индикаторы прочтения
  196. - [x] Редактирование сообщений
  197. - [x] Удаление сообщений - в течении 24 часов
  198. - [ ] Инициация чатов со стороны Matrix
  199. - Вконтакте (как пользователь) -> Matrix
  200. - [x] Текстовые сообщения
  201. - [x] Пересланные сообщения
  202. - [x] Изображения
  203. - [ ] Аудио - недоступно через токен пользователя
  204. - [ ] Видео - недоступно через токен пользователя
  205. - [x] Стикеры
  206. - [x] Прочие файлы
  207. - [ ] Индикатор "в сети"
  208. - [x] Индикатор печати
  209. - [x] Имена и аватарки пользователей
  210. - [ ] Индикаторы прочтения
  211. - [x] Редактирование сообщений
  212. - [ ] Удаление сообщений
  213. - [ ] Автоматическое заполнение комнаты пользователями
  214. Чтобы избежать самозванства, **не** используйте режим релея с токенами пользователя!