userbot/README_ru.md at master · getCompass/userbot

Бот
Создание бота
- Учётные данные бота
Отправка запроса в приложении Compass
- Ответ от приложения Compass после отправки запроса
Webhook и реагирование на команды
Список методов Compass Userbot API
Дополнительное форматирование сообщений
Ошибки при выполнении запроса Compass Userbot API
Библиотека для работы с API ботов приложения Compass

Бот

Бот — это специальный аккаунт в приложении Compass, который создаётся пользователем для автоматического выполнения настраиваемых действий.

Бот Compass умеет:

отправлять сообщения в личные и групповые чаты;
ставить реакции на сообщения;
отправлять файлы в чат;
получать основную информацию по участникам команды (user_id, имя, URL файла-аватарки).

Перечисленные действия реализуются через специальные запросы, описанные в разделе Список методов приложения Compass Userbot API.

Также, если включить режим "Реагировать на команды", бот начнёт реагировать на команды, которые вы укажете, и перенаправлять их на адрес вашего webhook (подробнее в разделе Webhook и реагирование на команды).

Создание бота

Создание бота доступно пользователю, имеющему права управления ботами.

Данные права можно выдать только участникам с правами в соответствующих настройках. Для этого перейдите в раздел "Участники", выберите пользователя, которому хотите выдать права, и далее — "Настроить права в команде":

После редактирования прав у участника обновится меню команды, в нём появится функционал для управления ботами:

При создании бота вы можете настроить следующие параметры:

аватар бота;
имя бота;
описание бота;
webhook, куда будут перенаправлены команды от участников.

Webhook — это URL-адрес вашего сервиса. После его настройки бот сможет реагировать на сообщения-команды, перенаправляя их на указанный вами адрес.

Учётные данные бота

После создания бота в разделе «Карточка бота» вам будут предоставлен Токен нового бота (виден участникам с правами управления ботами).

Токен бота (token) — уникальный для каждого бота идентификатор.

⚠️ Обратите внимание: Токен вашего бота нельзя сообщать третьим лицам.
Если же это произошло, рекомендуем сменить Токен в приложении Compass через настройки бота:

Таким образом, все запросы бота, которые использовали скомпрометированный токен, станут недействительными для приложения Compass.

Отправка запроса в приложении Compass

Запросы к приложению Compass Userbot API должны осуществляться через HTTPS-запрос методом POST, отправленный на endpoint:
URL для облачной версии продукта:
https://userbot.getcompass.com/api/v3/ + (выполняемый метод)

URL для On-premise версии продукта:
https://<yourdomain>/userbot/api/v3/ + (выполняемый метод)

Все запросы должны использовать тип содержимого: application/json.
Для загрузки файлов: multipart/form-data.

Тело каждого запроса к приложению Compass должно содержать:

json-строку требуемых параметров для запроса (пустой, если данные не требуются).

Авторизация запроса осуществляется через header-заголовок с использованием токена вашего бота:

заголовок "Authorization: bearer={токен бота}" - заголовок содержит токен, который принадлежит вашему боту (бот должен быть включён для этого).

Все методы регистрозависимы и должны быть в кодировке UTF-8.

Рассмотрим запрос на примере отправки сообщения участнику.

Используется метод /user/send.
URL для отправляемого запроса: https://userbot.getcompass.com/api/v3/user/send

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

{
  "text": "Hello, this is bot", // произвольный текст для нового сообщения от бота
  "type": "text",               // указываем, что сообщение является текстовым
  "user_id": 12345              // идентификатор участника, которому отправляется сообщение
}

Структура curl-запроса:

curl -X POST -d "{параметры в json-формате}"
-H "Content-Type: application/json"
-H "Authorization: bearer={токен бота}" 
https://userbot.getcompass.com/api/v3/user/send

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

При отправке запроса вам необходимо указать, куда будет отправлено сообщение от бота:

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

ID участника

Идентификатор участника (параметр "user_id" в запросах) используется при отправке сообщения конкретному участнику. Его можно получить в приложении Compass через Профиль участника (доступны только пользователям с правами управления ботами):

Ключ чата

Уникальный идентификатор группы (используется как "group_id" в запросах), участником которой является бот.
Доступен для участника с правами управления ботами из раздела "Меню бота" в групповом чате:

Пример ключа чата:

3brLYUVlCEbNg6A0m6W2X2zkPyY8PN3Ijw6efI20gVJHGiy4xHOociXAmMh1o/i01gLTS8wHHx7JGrrzIL4zDC6a4qX031dzJfqTzl8MD6Rqv2wd38yfGLS6n6VlwmPQ2hNNXCDPEL9sddmYCfHSSY/BfjXsNvJh3YpBH1pRf1I=

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

Идентификатор сообщения (используется как "message_id" в запросах), с которым работает бот. Пример ключа сообщения:

oDT9FLRWjDOX0+4smgkCn039jKIce+NUE90zy9neDKvh6ubLMDGU/Cee5e07avTPFT/WcnAJIXFxBYmT8vqbF5vNIi4T/YEKZh4yF4iLXo9J4pW/4UguVkB0XY9/vF5pzUHUL4eVr3ScGWEP3fUEWdNlws+pffgp9oUOl+X0HrFxXxuFVfREy6od/psN+lob

Ответ от приложения Compass после отправки запроса

Все запросы к Compass выполняются синхронно и возвращают результат своего выполнения.

Ответ представляет собой json-объект, в котором содержатся поля:

status (string) — отражает статус выполнения запроса.
Может принимать значение "ok" (в случае, если запрос выполнился успешно) или "error" (в случае ошибки);
response (json) — json-объект произвольных данных.

В случае успешного выполнения поле response может иметь данные выполненного запроса, либо пустое значение.

Рассмотрим схему получения результата на примере отправки сообщения от бота:

выполним запрос /user/send, передав текст: Hello, this is bot 😊
в случае если сообщение успешно отправлено, метод вернёт результат выполнения запроса — в данном примере это message_id отправленного ботом сообщения:

{
    "status": "ok",
    "response": {
         "message_id": "eNb2VLAPCGFfK1gHzNkH78XNDsPr9N/dDI7f/yaeTof0zjXwv/G000SZFNwqBOx2ACjqSwFjB1Lhgtqn..."
    }
}

Пример пустого ответа:

{
    "status": "ok",
    "response": {}
}

Если произошла ошибка, поле status будет принимать значение "error".

В таком случае поле response будет содержать поля:

error_code (int) — код ошибки. Более подробно расписано в разделе Ошибки при выполнении запроса Compass Userbot API;
message (string) — произвольный текст ошибки.

Пример ответа с ошибкой:

{
    "status": "error",
    "response": {
        "error_code": 1000,
        "message": "invalid parameters: not passed param text for request"
    }
}

Webhook и реагирование на команды

Бот может реагировать на специальные команды-сообщения.
Для добавления команд используется метод /command/update:

Установленные команды будут видны всем участникам команды на экране "Карточка бота":

Когда участник отправляет сообщение-команду боту, у которого включён режим "Реагировать на команды" и установлен webhook, то на указанный адрес отправляются данные вида:

Если команда была отправлена в группе

{
   "group_id": "3brLYUVlCEbNg6A0m6W2X2zkPyY8PN3Ijw6efI20gVJHGiy4xHOociXAmMh1o/i01gLTS8wHHx7JGrrzIL4z...",
   "message_id": "oDT9FLRWjDOX0+4smgkCn039jKIce+NUE90zy9neDKvh6ubLMDGU/Cee5e07avTPFT/WcnAJIXFxBYmT8vqbF5vNIi4T/YEKZh...",
   "text": "/покажи список команд",
   "type": "group",
   "user_id": 12345,
}

group_id — ключ группы, откуда отправлена команда;
message_id — уникальный идентификатор сообщения-команды;
text — текст команды, переданной боту;
type — указывает, откуда пришла команда (single — чат с ботом; group — группа);
user_id — идентификатор участника пространства, который отправил команду.

Если команда была отправлена в личном чате с ботом

{
    "group_id": "",
    "message_id": "oDT9FLRWjDOX0+4smgkCn039jKIce+NUE90zy9neDKvh6ubLMDGU/Cee5e07avTPFT/WcnAJIXFxBYmT8vqbF5vNIi4T/YEKZh...",
    "text": "/покажи список команд",
    "type": "single",
    "user_id": 12345,
}

⚠️ Обратите внимание: на ваш сервис отправляются только сообщения, текст которых начинается с символа «/». Другие сообщения из чата не отправляются на webhook.

Запрос будет содержать header-заголовок с токеном того бота, которому принадлежит отправленная команда:

заголовок "Authorization: bearer={токен бота}".

Получив данные на ваш webhook, вы можете:

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

Ответ на команду пользователя

Получив сообщение на ваш webhook, у вас есть возможность ответить на команду пользователя, отправив данные в ответе запроса без необходимости вызова метода Compass Userbot API.
Ответ на запрос от бота должен иметь формат json-строки требуемых параметров.

Рассмотрим пример отправки ответа на команду пользователя:

пользователь отправляет в диалог команду для вашего бота;
запрос с данными команды отправляется на ваш webhook;
получив данные, необходимо сформировать требуемые параметры и вернуть в ответе запроса;
бот, успешно завершив запрос на webhook, получает ваш ответ и отвечает на команду пользователя.

Пример параметров для ответа на команду пользователя в виде сообщения в диалог:
{
  "answer": {
  	"action": "message_send",
  	"post": {
  		"text": "Привет, это сообщение от бота",
  		"type": "text"
  	}
  }
}

answer - поле, которое содержит json-объект переданных параметров;
action - действие, которое желаете выполнить в ответе;
post - объект с post-параметрами.

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

Доступные действия для ответа с webhook

Действие	Для чего используется
message_send	действие для отправки сообщения от бота на команду пользователя.
thread_send	действие для отправки сообщения от бота в тред на команду пользователя.
message_addreaction	действие для установки реакции на команду пользователя.

`message_send`

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

Должны быть указаны следующие параметры:

Название	Тип	Свойство	Описание
action	string	обязательный	Выполняемое действие в ответ на команду.
post	object	обязательный	Объект с post-параметрами.
post.text	string	обязательный, если не передан параметр file_id	Текст сообщения от бота.
post.file_id	string	обязательный, если не передан параметр text	Идентификатор файла для сообщения-файла. О получении file_id подробнее расписано в данном разделе.
post.type	string	обязательный	Для текстовых сообщений необходимо передавать в этот параметр значение = "text". Для сообщений-файлов необходимо передавать в этот параметр значение = "file".

Пример параметров

Для отправки текстового сообщения:

{
	"answer": {
		"action": "message_send",
		"post": {
			"text": "Привет, это сообщение от бота",
			"type": "text"
		}
	}
}

Для отправки файла:

{
	"answer": {
		"action": "message_send",
		"post": {
  		    "file_id": "+OVV/dHD03Pb/qRQz9W/FhgupqO6UY0lmbwnG5tz9mHW51N8gA10VvotOzq01GuWq/c5LGZSldSCz4aki...",
		    "type": "file"
		}
	}
}

`thread_send`

Действие для отправки в тред сообщения от бота на команду пользователя.

Должны быть указаны следующие параметры:

Название	Тип	Свойство	Описание
action	string	обязательный	Выполняемое действие в ответ на команду.
post	object	обязательный	Объект с post-параметрами.
post.text	string	обязательный, если не передан параметр file_id	Текст сообщения от бота.
post.file_id	string	обязательный, если не передан параметр text	Идентификатор файла для сообщения-файла. О получении file_id подробнее расписано в данном разделе.
post.type	string	обязательный	Для текстовых сообщений необходимо передавать в этот параметр значение = "text". Для сообщений-файлов необходимо передавать в этот параметр значение = "file".

Пример параметров

Для отправки текстового сообщения:

{
	"answer": {
		"action": "thread_send",
		"post": {
		    "text": "Привет, это сообщение от бота в тред",
		    "type": "text"
		}
	}
}

Для отправки файла:

{
	"answer": {
		"action": "thread_send",
		"post": {
  		    "file_id": "+OVV/dHD03Pb/qRQz9W/FhgupqO6UY0lmbwnG5tz9mHW51N8gA10VvotOzq01GuWq/c5LGZSldSCz4aki...",
		    "type": "file"
		}
	}
}

`message_addreaction`

Действие для установки реакции на сообщение-команду пользователя.

Должны быть указаны следующие параметры:

Название	Тип	Свойство	Описание
action	string	обязательный	Выполняемое действие в ответ на команду.
post	object	обязательный	Объект с post-параметрами.
post.reaction	string	обязательный	Реакция, которую необходимо установить. Может принимать значение: - короткое описание (short_name). Например, `:blush:` - emoji. Например, 😊

Приложение Compass поддерживает список реакций версии 15.0: https://emojipedia.org/emoji-15.0/.

Пример параметров

{
	"answer": {
		"action": "message_addreaction",
		"post": {
  		    "reaction": ":black_cat:"
		}
	}
}

Версия webhook бота

Каждый бот приложения Compass имеет версию для webhook, которая позволяет более гибко взаимодействовать с Userbot API при изменениях API.

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

Чтобы получить новые изменения, необходимо с помощью метода /webhook/setVersion переключить версию webhook на актуальную.
Подробнее об изменениях миграции и версии webhook: Migration guide

Список методов Compass Userbot API

Метод	Для чего используется
/user/send	отправить сообщение от бота конкретному участнику
/group/send	отправить сообщение от бота в группу
/thread/send	отправить сообщение от бота в комментарии к сообщению
/message/addReaction	добавить реакцию на сообщение от лица бота
/message/removeReaction	удалить реакцию бота с сообщения
/user/getList	получить данные об участниках команды
/group/getList	получить данные групп, в которых состоит бот
/command/update	обновить список команд бота
/command/getList	получить список команд бота
/webhook/setVersion	установить версию для webhook бота
/webhook/getVersion	получить текущую версию webhook бота
/file/getUrl	получить URL для загрузки файлов

Описание методов

`POST /user/send`

Метод для отправки сообщения от бота пользователю.
URL для облачной версии продукта: https://userbot.getcompass.com/api/v3/user/send
URL для On-premise версии продукта: https://<yourdomain>/userbot/api/v3/user/send

В теле запроса должны быть указаны следующие параметры:

Название	Тип	Свойство	Описание
user_id	int	обязательный	ID участника, которому бот отправит сообщение в личный чат.
text	string	обязательный, если не передан параметр file_id	Текст сообщения от бота.
file_id	string	обязательный, если не передан параметр text	Идентификатор файла для сообщения-файла. О получении file_id подробнее расписано в данном разделе.
type	string	обязательный	Для текстовых сообщений необходимо передавать в этот параметр значение = "text". Для сообщений-файлов необходимо передавать в этот параметр значение = "file".

Результатом выполнения данного метода будет:
message_id (string) — ключ сообщения, отправленного ботом.

Пример данных для тела запроса и результата выполнения

Данные для тела запроса:

{
     "text": "Привет, это сообщение от бота",
     "type": "text",
     "user_id": 12345
}

Результат выполнения запроса:

{
     "status": "ok",
     "response": {
          "message_id": "eNb2VLAPCGFfK1gHzNkH78XNDsPr9N/dDI7f/yaeTof0zjXwv/G000SZFNwqBOx2ACjqSwFjB1Lhgtqn..."
     }
}

Список возможных ошибок:

error_code	Значение
1000	Переданы некорректные данные (например, не передан один из параметров).
1001	Выбранный участник не существует в команде.
1002	Выбранный участник покинул команду.

`POST /group/send`

Метод для отправки сообщения от бота в группу.
URL для облачной версии продукта: https://userbot.getcompass.com/api/v3/group/send
URL для On-premise версии продукта: https://<yourdomain>/userbot/api/v3/group/send

В теле запроса должны быть указаны следующие параметры:

Название	Тип	Свойство	Описание
group_id	string	обязательный	Идентификатор группы, в которое бот отправит сообщение.
text	string	обязательный, если не передан параметр file_id	Текст сообщения от бота.
file_id	string	обязательный, если не передан параметр text	Идентификатор файла для сообщения-файла. О получении file_id подробнее расписано в данном разделе.
type	string	обязательный	Для текстовых сообщений необходимо передавать в этот параметр значение = "text". для сообщений-файлов необходимо передавать в этот параметр значение = "file".

Результатом выполнения данного метода будет:
message_id (string) — ключ сообщения, отправленного ботом в группу.

Пример данных для тела запроса и результата выполнения

Данные для тела запроса:

{
     "group_id": "GrrzIL4zDC6a4qX031dzJfqTzl8MD6Rqv2wd38yfGLS6n3brLYUVlCEbNg6A0m6W2X2zkPyY8PN3Ijw6e...",
     "text": "Привет, это сообщение от бота для группы",
     "type": "text"
}

Результат выполнения запроса:

{
     "status": "ok",
     "response": {
          "message_id": "eNb2VLAPCGFfK1gHzNkH78XNDsPr9N/dDI7f/yaeTof0zjXwv/G000SZFNwqBOx2ACjqSwFjB1LhgtqnmXFReGjz..."
     }
}

Список возможных ошибок:

error_code	Значение
1000	Переданы некорректные данные (например, не передан один из параметров).
1003	Бот не состоит в групповом чате.
1004	Такой групповой чат не существует.

`POST /thread/send`

Метод для отправки сообщения от бота в тред.
URL для облачной версии продукта: https://userbot.getcompass.com/api/v3/thread/send
URL для On-premise версии продукта: https://<yourdomain>/userbot/api/v3/thread/send

В теле запроса должны быть указаны следующие параметры:

Название	Тип	Свойство	Описание
message_id	string	обязательный	Идентификатор сообщения-команды, для которого будет создан тред, если ранее он не был создан, и отправлено сообщение от бота в этот тред.
text	string	обязательный, если не передан параметр file_id	Текст сообщения от бота.
file_id	string	обязательный, если не передан параметр text	Идентификатор файла для сообщения-файла. О получении file_id подробнее расписано в данном разделе.
type	string	обязательный	Для текстовых сообщений необходимо передавать в этот параметр значение = "text". для сообщений-файлов необходимо передавать в этот параметр значение = "file".

Результатом выполнения данного метода будет:
message_id (string) — ключ сообщения, отправленного ботом в тред.

Пример данных для тела запроса и результата выполнения

Данные для тела запроса:

{
     "message_id": "oDT9FLRWjDOX0+4smgkCn039jKIce+NUE90zy9neDKvh6ubLMDGU/Cee5e07avTPFT/WcnAJIXFx...",
     "text": "Привет, это сообщение от бота в тред",
     "type": "text"
}

Результат выполнения запроса:

{
     "status": "ok",
     "response": {
          "message_id": "eNb2VLAPCGFfK1gHzNkH78XNDsPr9N/dDI7f/yaeTof0zjXwv/G000SZFNwqBOx2ACjqSwFj..."
     }
}

Список возможных ошибок:

error_code	Значение
1000	Переданы некорректные данные (например, не передан один из параметров).
1005	У бота отсутствует доступ к сообщению (сообщение удалено или чат очищен).
1007	Переданный ID сообщения не существует.

`POST /message/addReaction`

Метод для добавления реакции на сообщение от лица бота.
URL для облачной версии продукта: https://userbot.getcompass.com/api/v3/message/addReaction
URL для On-premise версии продукта: https://<yourdomain>/userbot/api/v3/message/addReaction

Приложение Compass поддерживает список реакций версии 15.0: https://emojipedia.org/emoji-15.0/.

В теле запроса должны быть указаны следующие параметры:

Название	Тип	Свойство	Описание
message_id	string	обязательный	Идентификатор сообщения, на которое устанавливается реакция от лица бота.
reaction	string	обязательный	Реакция, которую необходимо установить. Может принимать значение: - короткое описание (short_name). Например, `:blush:` - emoji. Например, 😊

Результатом данного метода будет стандартный ответ "ok" без возвращаемых данных.

Пример данных для тела запроса и результата выполнения

Данные для тела запроса:

{
     "message_id": "oDT9FLRWjDOX0+4smgkCn039jKIce+NUE90zy9neDKvh6ubLMDGU/Cee5e07avTPFT/WcnAJIXFxBYmT8v...",
     "reaction": ":blush:"
}

Результат выполнения запроса:

{
     "status": "ok",
     "response": {}
}

Список возможных ошибок:

error_code	Значение
1000	Переданы некорректные данные (например, не передан один из параметров).
1005	У бота отсутствует доступ к сообщению (сообщение удалено или чат очищен).
1006	Переданная реакция отсутствует в приложении.
1007	Переданный ID сообщения не существует.

`POST /message/removeReaction`

Метод для удаления реакции бота с сообщения.
URL для облачной версии продукта: https://userbot.getcompass.com/api/v3/message/removeReaction
URL для On-premise версии продукта: https://<yourdomain>/userbot/api/v3/message/removeReaction

Приложение Compass поддерживает список реакций версии 15.0:
https://emojipedia.org/emoji-15.0/.

В теле запроса должны быть указаны следующие параметры:

Название	Тип	Свойство	Описание
message_id	string	обязательный	Идентификатор сообщения, с которого будет удалена реакция бота.
reaction	string	обязательный	Реакция, которую необходимо удалить. Может принимать значение: - короткое описание (short_name). Например, `:blush:` - emoji. Например, 😊

Результатом данного метода будет стандартный ответ "ok" без возвращаемых данных.

Пример данных для тела запроса и результата выполнения

Данные для тела запроса:

{
     "message_id": "oDT9FLRWjDOX0+4smgkCn039jKIce+NUE90zy9neDKvh6ubLMDGU/Cee5e07avTPFT/WcnAJIXFxBYmT8v...",
     "reaction": ":blush:"
}

Результат выполнения запроса:

{
     "status": "ok",
     "response": {}
}

Список возможных ошибок:

error_code	Значение
1000	Переданы некорректные данные (например, не передан один из параметров).
1005	У бота отсутствует доступ к сообщению (сообщение удалено или чат очищен).
1006	Переданная реакция отсутствует в приложении.
1007	Переданный ID сообщения не существует.

`POST /user/getList`

Метод для получения данных об участниках команды.
URL для облачной версии продукта: https://userbot.getcompass.com/api/v3/user/getList
URL для On-premise версии продукта: https://<yourdomain>/userbot/api/v3/user/getList

В теле запроса могут использоваться следующие параметры:

Название	Тип	Свойство	Описание
count	int	необязательный	Количество данных в ответе. По умолчанию = 100. Максимум = 300.
offset	int	необязательный	Смещение для пагинации данных. По умолчанию = 0.

Результатом выполнения данного метода будет:
user_list (array) — список с информацией по участникам команды.

Пример данных для тела запроса и результата выполнения

Данные для тела запроса:

{"count": 300, "offset": 0}

Результат выполнения запроса:

{
     "status": "ok",
     "response": {
          "user_list": [
               {
                    "user_id": 1,
                    "user_name": "Иванов Иван",
                    "avatar_file_url": ""
               },
               {
                    "user_id": 2,
                    "user_name": "Михайлов Михаил",
                    "avatar_file_url": "https://file-1.getcompass.com/files/pivot/dca/e8d/632/fa7/51f/fdcaee3ecea91e6c_w400.jpeg"
               }
          ]
     }
}

`POST /group/getList`

Метод для получения информации о группах, в которых состоит бот.
URL для облачной версии продукта: https://userbot.getcompass.com/api/v3/group/getList
URL для On-premise версии продукта: https://<yourdomain>/userbot/api/v3/group/getList

В теле запроса могут использоваться следующие параметры:

Название	Тип	Свойство	Описание
count	int	необязательный	Количество данных в ответе. По умолчанию = 100. Максимум = 300.
offset	int	необязательный	Смещение для пагинации данных. По умолчанию = 0.

Результатом выполнения данного метода будет:
group_list (array) — список с информацией по групповым чатам бота.

Пример данных для тела запроса и результата выполнения

Данные для тела запроса:

{"count": 50, "offset": 0}

Результат выполнения запроса:

{
     "status": "ok",
     "response": {
          "group_list": [
               {
                    "group_id": "kPyY8PN3Ijw6efI20gVJHGiy4xHOociXAmMh1o/i01gLTS8wHHx7JGrrzIL4zDC6a4qX031dzJfqTzl8MD6Rqv2wd38...",
                    "name": "Библиотека",
                    "avatar_file_url": "https://file-1.getcompass.com/files/c1/cba/30i/de0/2ff/uf3/4128e05b1cbd1f79_w80.jpg"
               },
               {
                    "group_id": "GrrzIL4zDC6a4qX031dzJfqTzl8MD6Rqv2wd38yfGLS6n3brLYUVlCEbNg6A0m6W2X2zkPyY8PN3Ijw6efI20gVJHG...",
                    "name": "Расписание",
                    "avatar_file_url": "https://file-1.getcompass.com/files/c1/cde/b4s/duo/1fc/97t/4128e05b1cbd1f79_w80.jpg"
               },
               {
                    "group_id": "3brLYUVlCEbNg6A0m6W2X2zkPyY8OociXAmMh1o/i01gLTS8wHHx7JGrrzIL4zDC6a4qX031dzJfqTzl8MD6Rqv2wd...",
                    "name": "Статистика",
                    "avatar_file_url": "https://file-1.getcompass.com/files/c1/adf/a1e/pra/4ca/mt5/4128e05b1cbd1f79_w80.jpg"
               }
          ]
     }
}

`POST /command/update`

Метод для обновления списка команд бота.
URL для облачной версии продукта: https://userbot.getcompass.com/api/v3/command/update
URL для On-premise версии продукта: https://<yourdomain>/userbot/api/v3/command/update

В теле запроса должны быть указаны следующие параметры:

Название	Тип	Свойство	Описание
command_list	array	обязательный	Новый список строк-команд для бота (максимум 100 команд для бота).

Несколько правил для установки команд:

Длина команды не должна превышать 80 символов.
Команда может иметь параметры, заключённые в квадратные скобки. В этом случае паттерн для определения команд для бота "проигнорирует" их при обработке, посчитав за переданный параметр. Например, бот в списке команд имеет команду: "отправить сообщение участнику [ID]". В случае отправки в чат сообщения "/отправить сообщение участнику [1666]" парсер определит её как команду.
Команды могут состоять из букв русского и латинского алфавита, цифр и знака подчёркивания. Например,

/помощь

/чей клиент [ID]

/установить_таймер 10мин.

Результатом данного метода будет стандартный ответ "ok" без возвращаемых данных.

Пример данных для тела запроса и результата выполнения

Данные для тела запроса:

{
     "command_list": [
          "/помощь",
          "/отправить сообщение пользователю [ID]"
     ]
}

Результат выполнения запроса:

{
     "status": "ok",
     "response": {}
}

Список возможных ошибок:

error_code	Значение
1000	Переданы некорректные данные (превышена длина для команды).
1008	Превышен лимит списка команд.
1009	Некорректная команда в списке.

`POST /command/getList`

Метод для получения списка команд бота.
URL для облачной версии продукта: https://userbot.getcompass.com/api/v3/command/getList
URL для On-premise версии продукта: https://<yourdomain>/userbot/api/v3/command/getList

В теле запроса не требуются передавать параметры.

Результатом выполнения данного метода будет:
command_list (array) — список команд бота.

Пример результата выполнения запроса

{
     "status": "ok",
     "response": {
          "command_list": [
               "/помощь",
               "/отправить сообщение пользователю [ID]"
          ]
     }
}

`POST /webhook/setVersion`

Метод для установки уровня версии webhook бота.
URL для облачной версии продукта: https://userbot.getcompass.com/api/v3/webhook/setVersion
URL для On-premise версии продукта: https://<yourdomain>/userbot/api/v3/webhook/setVersion

В теле запроса должны быть указаны следующие параметры:

Название	Тип	Свойство	Описание
version	int	обязательный	Номер версии для webhook бота.

Результатом данного метода будет стандартный ответ "ok" без возвращаемых данных.

Пример данных для тела запроса и результата выполнения

Данные для тела запроса:

{"version": 3}

Результат выполнения запроса:

{
     "status": "ok",
     "response": {}
}

Список возможных ошибок:

error_code	Значение
1000	Переданы некорректные данные.
1011	Передана некорректная версия webhook.

`POST /webhook/getVersion`

Метод для получения уровня версии webhook бота.
URL для облачной версии продукта: https://userbot.getcompass.com/api/v3/webhook/getVersion
URL для On-premise версии продукта: https://<yourdomain>/userbot/api/v3/webhook/getVersion

В теле запроса не требуются передавать параметры.

Результатом выполнения данного метода будет:
version (int) — уровень версии webhook бота.

Пример результата выполнения запроса

{
     "status": "ok",
     "response": {
          "version": 2
     }
}

`POST /file/getUrl`

Метод для получения URL ноды, куда загружаются файлы. Предназначен для дальнейшего получения параметра file_id для отправки сообщения-файла.
URL для облачной версии продукта: https://userbot.getcompass.com/api/v3/file/getUrl
URL для On-premise версии продукта: https://<yourdomain>/userbot/api/v3/file/getUrl

В теле запроса не требуются передавать параметры.

Результатом выполнения данного метода будет:
node_url — URL-адрес сервера, на который возможно загрузить файл;
file_token — токен для валидации запроса загрузки файла.

Пример результата выполнения запроса

{
     "status": "ok",
     "response": {
          "node_url": "https://file1.getcompass.com/api/userbot/files/upload",
          "file_token": "404952d4ac90ae960de4d2a96fb95d306493e151"
     }
}

После получения URL сервера, появится возможность загрузить файл POST-запросом с помощью multipart/form-data, подписав запрос полученным file-токеном.

В нашем случае с полученными из ответа node_url и токеном для загрузки файла запрос будет выглядеть следующим образом:
URL для облачной версии продукта: https://file1.getcompass.com/api/userbot/files/upload
URL для On-premise версии продукта: https://<yourdomain>/file1/api/userbot/files/upload

Название	Тип	Свойство	Описание
token	string	обязательный	file_token для валидации загрузки файла.
file	string/binary	обязательный	Содержимое файла для загрузки.

⚠️ Ограничения для загрузки файла:

максимальный размер файла:
- в облачной версии продукта — 512 мегабайт;
- в On-premise версии продукта — 2 гигабайта (размер может быть изменён администратором сервера).
один токен разрешает загрузку одного файла, т.е. с его помощью невозможно загрузить второй файл;
для загрузки доступно не более 100 файлов в течение 5 минут.

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

file_id (string) — уникальный идентификатор загруженного файла.

Пример запроса и результата выполнения запроса

Пример запроса:

token: "404952d4ac90ae960de4d2a96fb95d306493e151", // значение полученного file_token
file: "(binary)"                                   // бинарные данные загружаемого файла

Результат выполнения запроса:

{
     "status": "ok",
     "response": {
          "file_id": "+OVV/dHD03Pb/qRQz9W/FhgupqO6UY0lmbwnG5tz9mHW51N8gA10VvotOzq01GuWq/c5LGZSldSCz4aki..."
     }
}

Список возможных ошибок:

error_code	Значение
1000	Переданы некорректные данные.
1010	Не удалось загрузить файл.

Дополнительное форматирование сообщений

Боту доступен функционал, позволяющий упомянуть участника или группу участников, объединённых по бейджу, в отправленном сообщении:

Для этого текст сообщения должен иметь формат вида:
["@"|<числовой идентификатор user_id>|"<имя участника>"]

На примере выше представим, что у Фёдора Денисова ID участника соответствует 345. Для получения сообщения, как в примере, текст отправленного от бота сообщения должен иметь вид:
["@"|345|"Фёдор Денисов"] данные сформированы ✅

Текст сообщения с упоминанием по бейджу должен иметь вид:
["@"|0|"all"] – чтобы упомянуть всех пользователей чата;
["@"|0|"manager"] – чтобы упомянуть группу участников, объединённых по бейджу "manager".

Например: ["@"|0|"all"] данные сформированы ✅

Бот также обладает теми же возможностями форматирования сообщений, что и участник команды в приложении Compass.

Например, можно изменить вид шрифта или выделить слова определённым цветом:

для создания жирного шрифта текста: *жирный шрифт*
для создания курсива в тексте: _курсив_
для создания зачёркнутого текста: ~зачёркнутый текст~
текст на чёрном фоне: ``текст на чёрном фоне``
текст, выделенный зелёным: ++зелёное выделение++
текст, выделенный розовым: --розовое выделение--

Ошибки при выполнении запроса Compass Userbot API

В случае если при выполнении запроса произошла ошибка, то возвращается ответ следующего формата:

{
     "status": "error",
     "response": {
          "error_code": 1,
          "message": "missing required fields for request"
     }
}

status "error" — сообщает о том, что запрос завершился ошибкой;
error_code — специальный код ошибки;
message — произвольный текст для описания ошибки.

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

error_code	Описание
1	Отсутствуют обязательные поля для запроса.
2	Токен запроса не найден.
3	Бот выключен или удалён — выполнение запроса невозможно.
5	Достигнут лимит ошибок при выполнении запроса.
6	Неизвестная ошибка при выполнении внутреннего метода для запроса.
8	Указаны некорректные параметры для запроса.
9	Указан некорректный метод запроса.

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

error_code	Значение
1000	Переданы некорректные данные.
1001	Выбранный участник не существует в команде.
1002	Выбранный участник покинул команду
1003	Бот не состоит в группе.
1004	Такой группы не существует.
1005	У бота отсутствует доступ к сообщению (сообщение удалено или чат очищен).
1006	Переданная реакция отсутствует в приложении.
1007	Переданный ID сообщения не существует.
1008	Превышен лимит списка команд.
1009	Некорректная команда в списке.
1010	Не удалось загрузить файл.
1011	Передана некорректная версия webhook.

Библиотека для работы с API ботов приложения Compass

Для вашего удобства мы создали библиотеку для взаимодействия с приложением Compass Userbot API:

Библиотека для работы с API ботов.

Postman: готовая коллекция и настройки окружения

Чтобы быстро начать работать с Compass Userbot API, скачайте и импортируйте в Postman файлы из директории postman/ данного репозитория.

Коллекция запросов для Postman
Загрузка/отправка файлов, отправка сообщений, управление webhook, настройка команд и т.д.

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

Посмотреть коллекцию

Окружение для облачной (SaaS) версии
Переменные:

api_base_url — https://userbot.getcompass.com
bot_token — токен вашего бота

Посмотреть окружение SaaS

Окружение для On-Premise установки
Переменные:

api_base_url — ваш домен, например https://<yourdomain>/userbot/
bot_token — токен вашего бота

Посмотреть окружение On-Premise

Важно: после импорта зайдите в настройки окружения (Environments) и заполните api_base_url и bot_token своими значениями.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Бот

Создание бота

Учётные данные бота

Отправка запроса в приложении Compass

ID участника

Ключ чата

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

Ответ от приложения Compass после отправки запроса

Webhook и реагирование на команды

Ответ на команду пользователя

Доступные действия для ответа с webhook

`message_send`

`thread_send`

`message_addreaction`

Версия webhook бота

Список методов Compass Userbot API

Описание методов

`POST /user/send`

`POST /group/send`

`POST /thread/send`

`POST /message/addReaction`

`POST /message/removeReaction`

`POST /user/getList`

`POST /group/getList`

`POST /command/update`

`POST /command/getList`

`POST /webhook/setVersion`

`POST /webhook/getVersion`

`POST /file/getUrl`

Дополнительное форматирование сообщений

Ошибки при выполнении запроса Compass Userbot API

Библиотека для работы с API ботов приложения Compass

Postman: готовая коллекция и настройки окружения

FilesExpand file tree

README_ru.md

Latest commit

History

README_ru.md

File metadata and controls

Бот

Создание бота

Учётные данные бота

Отправка запроса в приложении Compass

ID участника

Ключ чата

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

Ответ от приложения Compass после отправки запроса

Webhook и реагирование на команды

Ответ на команду пользователя

Доступные действия для ответа с webhook

message_send

thread_send

message_addreaction

Версия webhook бота

Список методов Compass Userbot API

Описание методов

POST /user/send

POST /group/send

POST /thread/send

POST /message/addReaction

POST /message/removeReaction

POST /user/getList

POST /group/getList

POST /command/update

POST /command/getList

POST /webhook/setVersion

POST /webhook/getVersion

POST /file/getUrl

Дополнительное форматирование сообщений

Ошибки при выполнении запроса Compass Userbot API

Библиотека для работы с API ботов приложения Compass

Postman: готовая коллекция и настройки окружения

`message_send`

`thread_send`

`message_addreaction`

`POST /user/send`

`POST /group/send`

`POST /thread/send`

`POST /message/addReaction`

`POST /message/removeReaction`

`POST /user/getList`

`POST /group/getList`

`POST /command/update`

`POST /command/getList`

`POST /webhook/setVersion`

`POST /webhook/getVersion`

`POST /file/getUrl`