Iris Callback API 2.0

Iris | Callback API·3 May 2020

С помощью Iris Callback API вы можете получать сигналы из бесед, на которые вы подписались. Это поможет вам обрабатывать информацию способом, который удобен для вас без каких-либо ограничений.Для этого необходимо создать/купить/настроить свой сервер, который будет принимать запросы от серверов Iris.

1. Прежде чем начать или FAQ

1.1. Как создать своего дежурного?

1. Взять готовый код и поставить его на сервер;
2. Написать код самому.

1.2. Где найти сервер?

Платные:
https://www.reg.ru
https://firstvds.ru
https://firstbyte.ru (от 55р на 2022 год)
https://www.hetzner.com
https://www.ovhcloud.com
https://www.kimsufi.com/

Условно-бесплатные:
https://www.pythonanywhere.com (no async)
https://cloud.google.com/free/ (1 год)
https://aws.amazon.com/ (1 год)
https://www.netlify.com/
https://railway.app/ (500 часов)

1.3. Где взять исходники дежурного?

PHP:
https://vk.cc/atrr83 — оригинальный приемник IRIS CB API
https://vk.cc/atrrcm — форк оригинального приемника.
— Автор: Vitalik Suhoviy

Python:
https://vk.cc/atyjdw — приемник с сигналами и веб-панелью управления
— Автор: Юрий Юшманов ; Даниил Марк елов

https://vk.cc/atrrsf — форк IDM с доработ
ками— Автор: Иосиф Александрович

1.4. На каком языке писать дежурного?

На любом, который умеет работать с HTTP запросами.

2. Регистрация API для пользователя

У вас должен быть адрес страницы, на которую Ирис будет отправлять сигналы.
Для этого вам нужно написать в личные сообщения Ириса следующую команду:

+api {секретная_фраза} {http://адрес_страницы_сервера_callback}

Синонимы команды: +сигналы, +апи

{секретная_фраза} будет отправляться при каждом сигнале от Ириса. Её смысл в проверке достоверности запроса. Никому не говорите секретную фразу.

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

3. Подписка на сигналы в нужных беседах

Если вы являетесь администратором беседы, вы сможете подписаться на сигналы от беседы. Для этого вам необходимо в нужной беседе написать

стать дежурным

Синонимы команды: +api, +апи, +дежурный

Проверить, кто дежурный в беседе можно командой «кто дежурный»

4. Структура сигналов Ириса

Сигналы от Ириса приходят в формате json. Структура объекта следующая:

user_id: integer — id пользователя, который подписался на уведомления.
method: string — тип сигнала
secret: string — секретная фраза, которая подтверждает достоверность (передается в lowercase)
message: object — информация о сообщении, в котором была вызвана команда
object: object — информация, разной структуры для разных типов сигналов

Обратите внимание, Вам необходимо как можно скорее закрыть соединение с сервером Ириса, а далее продолжать обработку полученного сигнала. Максимальное время ожидания ответа 5 секунд.

5. Перечень сигналов

Ниже приведены названия типов сигналов (method) и описание их объектов (object)

5.1. addUser

Отправляется в случае команды «добавить @ссылка»

Структура object:

user_id: integer — id пользователя, которого необходимо добавить
chat: string — код беседы, в которой произошло событие
source: string — необязательный параметр. Источник добавления. По умолчанию источник сигнала — беседа.
Также сигнал может подаваться со страницы беседы на сайте iris-cm.ru (Значение «site»)

При этом message == null

5.2. banExpired

Отправляется в случае истечения бана пользователя в беседе.

Структура object:

user_id: integer— id пользователя, срок бана которого истёк
chat: string — код беседы, в которой произошло событие
comment: string — причина бана
conversation_message_id: integer — локальный идентификатор сообщения с командой бан в беседе

При этом message == null

5.3. banGetReason

Отправляется, когда модератор вызывает команду «причина» и хочет перейти на место выданного бана.

Структура object:

chat: string — код беседы, в которой произошло событие
local_id: integer — локальный id сообщения в беседе, место выдачи бана
message: string— сообщение с основной информацией о бане

5.4. bindChat

Отправляется в случае команды «!связать».

Отправляется конкретной беседе для конкретного пользователя. Задача пользователя привязать код беседы, передаваемый в сигнале к своему номеру беседы (обычно номер беседы в адресной строке) по реквизитам сообщения беседы.

Структура object:

chat: string — код беседы, в которой произошло событие

5.5. deleteMessagesFromUser

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

Структура object:

chat: string — код беседы, в которой произошло событие
user_id: integer — id пользователя, чьи сообщения нужно удалить (устаревший параметр, используйте member_ids)
member_ids: array— массив id пользователей и групп, чьи сообщения нужно удалить
amount: integer — количество последних сообщений пользователя. (необязательный параметр)
is_spam: boolean — пометить спамом при удалении. (необязательный параметр)
silent: boolean — удалить сообщения без оповещения. (необязательный параметр)

5.6. deleteMessages

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

Структура object:

chat: string — код беседы, в которой произошло событие
local_ids: array — локальные идентификаторы сообщений в беседе
is_spam: boolean — пометить спамом при удалении
silent: boolean — удалить сообщения без оповещения

5.7. forbiddenLinks

Отправляется, когда в беседе было обнаружено сообщение с запрещёнными ссылками.

Структура object:

chat: string — код беседы, в которой произошло событие
local_ids: array — локальные идентификаторы сообщений в беседе

5.8. ping

Ирис отправляет этот сигнал для проверки доступности адреса, на который зарегистрирован Iris Callback API.

5.9. printBookmark

Отправляется, когда требуется получить сообщение из истории.

Структура object:

chat: string — код беседы, в которой произошло событие
conversation_message_id: integer — локальный идентификатор сообщения в беседе
description: string — подпись к заметке

5.10. subscribeSignals

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

Структура object:

chat: string — код беседы, в которой произошло событие
conversation_message_id: integer — локальный id сообщения
text: string — текст передаваемого сообщения
from_id: integer — автор сообщения

Отправляется только 1 раз в конкретной беседе для конкретного пользователя. Задача пользователя привязать код беседы, передаваемый в сигнале к своему номеру беседы (обычно номер беседы в адресной строке) по реквизитам сообщения беседы.

5.11. toGroup

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

Структура object:

chat: string — код беседы, в которой произошло событие
group_id: integer — группа, в которой нужно сделать пост
local_id: integer — локальный id сообщения в беседе

5.12. sendSignal

Отправляется при команде «!дежурный {произвольный текст}»

Структура object:

chat: string — код беседы, в которой произошло событие
from_id: integer — id пользователя, вызвавшего сигнал
value: string— произвольный текст, переданный в команде после ключевого слова «сигнал»
conversation_message_id: integer — локальный идентификатор сообщения в беседе

Синонимы: «!д», «.дежурный», «.д»

5.13. sendMySignal

Отправляется на сервис-приёмник Iris Callback API того пользователя, который вызвал команду.

Отправляется при команде «!сигнал {произвольный текст}»

Структура object:

chat: string — код беседы, в которой произошло событие
from_id: integer — id пользователя, вызвавшего сигнал
value: string — произвольный текст, переданный в команде после ключевого слова «сигнал»
conversation_message_id: integer — локальный идентификатор сообщения в беседе

Синонимы: «!с», «.сигнал», «.с»

5.14. hireApi

Отправляется, когда владелец беседы хочет нанять приёмника сигналов от Ириса.

Структура object:

chat: string — код беседы, в которой произошло событие
price: integer — число ирисок, которые пользователь готов заплатить

Сервер должен вернуть json объект либо успеха, в котором содержится поле «days», указывающее, на какое время продлевается наём Приёмника ICA, либо ошибки

{"response": "ok", "days": 7}

5.15 meetChatDuty

Отправляется на сервис-приёмник Iris Callback API того пользователя, который вызвал команду.

Отправляется при команде «добавь/верни в {код_беседы}»

Структура object:

chat: string — код беседы, в которую пользователь приемника ICA собирается добавиться
duty_id: integer — id пользователя, который является дежурным в беседе

При этом message == null

5.16 messages.deleteByType

Отправляется, когда модератор беседы желает удалить сообщения определённого типа.

Структура object:

chat: string — код беседы
type: string — тип сообщений, которые требуется удалить
local_id: integer — начиная с какого conversation_message_id следует удалять
offset: integer — отступ от конца переписки беседы
is_spam: boolean — помечать сообщения спамом
silent: boolean — удалить сообщения без оповещения. (необязательный параметр)
admin_ids: list — список администраторов беседы
time: integer — unix-время по МСК в секундах (при type == period)
amount: integer — количество сообщений, которое необходимо удалить (при type == any)

Возможные значения поля type:

forwarded — пересылаемые сообщения
wall — репосты из групп
stickers — сообщения со стикерами
voice — голосовые сообщения
gif — гифки
photo — с фотографиями
video — с видео
audio — с аудио
article — со статьями
period — сообщения за период от указанного до текущего времени
any — все попавшиеся сообщения

Возможно список будет расширяться.

5.17 groupbots.invited

Сигнал о приглашении в беседу группы ирис-бота.

Беседа может быть не инициализирована в системе Ириса и не иметь уникального кода беседы.

Структура object:

group_id: int — ID добавленной группы ирис-бота
chat: string | null — код беседы, если уже есть информация о беседе в системе

5.18 messages.recogniseAudioMessage

Сигнал о запросе распознать голосовое сообщение.

Структура object:

local_id: int — conversation_message_id сообщения с голосовым для расшифровки
chat: string — код беседы

При этом message == null

6. Возврат ошибок. Структура JSON

При ошибке необходимо вернуть JSON, со следующей структурой:

response— тип ошибки. Может принимать значение error (для ошибок дежурного) и vk_error (для ошибок VK)
error_code — код ошибки. При response=vk_error используются коды ошибок VK
error_message — сообщение об ошибке. При response=vk_error используйте текст ошибки VK.

42323 views·911 shares

42323 views

Iris Callback API 2.0

Оглавление

1. Прежде чем начать или FAQ

1.1. Как создать своего дежурного?

1.2. Где найти сервер?

1.3. Где взять исходники дежурного?

1.4. На каком языке писать дежурного?

2. Регистрация API для пользователя

3. Подписка на сигналы в нужных беседах

4. Структура сигналов Ириса

5. Перечень сигналов

5.1. addUser

5.2. banExpired

5.3. banGetReason

5.4. bindChat

5.5. deleteMessagesFromUser

5.6. deleteMessages

5.7. forbiddenLinks

5.8. ping

5.9. printBookmark

5.10. subscribeSignals

5.11. toGroup

5.12. sendSignal

5.13. sendMySignal

5.14. hireApi

5.15 meetChatDuty

5.16 messages.deleteByType

5.17 groupbots.invited

5.18 messages.recogniseAudioMessage

6. Возврат ошибок. Структура JSON

7. Перечень ошибок

7.1. Пустой запрос / ERROR_NO_DATA

7.2. Неизвестный тип сигнала / ERROR_NO_METHOD_FOUND

7.3. Пара Пользователь/секрет не найдены / ERROR_USER_SECRET

7.4. Беседа не привязана / ERROR_NO_CHAT

7.5. Не удалось связать беседу / ERROR_CANT_BIND_CHAT