Собственные slash-команды
Допустим, вы хотите, чтобы пользователи узнавали прогноз погоды командой /weather москва неделя. Для этого нужно создать команду в Loop и написать сервис, который принимает HTTP-запрос от Loop и возвращает ответ.
Создание команды
- Откройте Главное меню > Интеграции > Быстрые команды и нажмите Добавить быструю команду.
- Заполните поля:
- Заголовок (до 64 символов) и Описание — для страницы со списком команд.
- Ключевое слово — слово после
/, напримерweather. От 1 до 128 символов, без пробелов, не начинается с/и не совпадает со встроенной командой. - URL запроса — адрес вашего сервиса, начинается с
http://илиhttps://. - Метод запроса —
POSTилиGET. - (Необязательно) Имя пользователя для ответа и Значок ответа — от чьего имени публикуются ответы. Работают, если администратор разрешил переопределение имён и изображений.
- (Необязательно) Автодополнение — показывать команду в списке при вводе
/. Можно добавить Подсказку для автодополнения с аргументами (например,[город] [период]) и Описание для автодополнения.
- Нажмите Сохранить и скопируйте Токен — по нему сервис будет проверять, что запрос пришёл от Loop.
Командами управляют пользователи с разрешением Управление быстрыми командами — по умолчанию системные администраторы и администраторы команд. Сами команды включаются в Системная консоль > Интеграции > Управление интеграцией > Включить пользовательские быстрые команды (включено по умолчанию).
Запрос от Loop
Когда пользователь вызывает команду, Loop отправляет запрос на URL запроса: при POST — параметры в теле как форма (application/x-www-form-urlencoded), при GET — в строке запроса.
POST /weather HTTP/1.1
Host: weather-service:4000
Accept: application/json
Authorization: Token qzgakf1nx3yt9dr4n8585ihbxy
Content-Type: application/x-www-form-urlencoded
token=qzgakf1nx3yt9dr4n8585ihbxy&
team_id=wx4zz8t4ttgmtxqiwfohijayzc&
team_domain=team-awesome&
channel_id=fukxanjgjbnp7ng383at53k1sy&
channel_name=town-square&
user_id=erj6qck3rfgtujs86w5r6rckzh&
user_name=ivan&
command=%2Fweather&
text=%D0%BC%D0%BE%D1%81%D0%BA%D0%B2%D0%B0+%D0%BD%D0%B5%D0%B4%D0%B5%D0%BB%D1%8F&
trigger_id=ZWZ5ZjRndzR4YmJxOHJlZWh4MXpk...&
response_url=https%3A%2F%2Fyour-loop-server.ru%2Fhooks%2Fcommands%2Fi11f6nnfgfyk8eg56x9omc6dpa
| Поле | Описание |
|---|---|
token | Токен команды. Он же передаётся в заголовке Authorization: Token <токен>. Отклоняйте запросы с другим токеном |
team_id, team_domain | ID и имя команды |
channel_id, channel_name | Канал, в котором вызвана команда |
user_id, user_name | Пользователь, вызвавший команду |
command | Команда вместе с / |
text | Текст после команды |
trigger_id | Идентификатор для открытия интерактивного диалога |
response_url | Адрес для отложенных ответов |
user_mentions, user_mentions_ids | Упомянутые в тексте пользователи и их ID (если есть) |
channel_mentions, channel_mentions_ids | Упомянутые в тексте публичные каналы и их ID (если есть) |
Сервис должен ответить в течение 30 секунд (параметр ServiceSettings.OutgoingIntegrationRequestsTimeout).
Ответ сервиса
Верните JSON с заголовком Content-Type: application/json. Без этого заголовка тело ответа будет опубликовано как обычный текст.
{
"response_type": "in_channel",
"text": "#### Погода в Москве на неделю\n\n| День | Погода | Днём | Ночью |\n|:---|:---|:---|:---|\n| Пн | Облачно, небольшой снег | -3 °C | -12 °C |\n| Вт | Солнечно | -4 °C | -8 °C |\n| Ср | Переменная облачность | -4 °C | -14 °C |"
}
Параметры ответа
| Параметр | Описание | Обязательный |
|---|---|---|
text | Текст сообщения с поддержкой Markdown. | Да, если нет attachments |
attachments | Вложения для расширенного оформления. | Да, если нет text |
response_type | in_channel — сообщение видят все участники канала; ephemeral или пусто — временное сообщение, которое видит только вызвавший команду. По умолчанию ephemeral. | Нет |
username | Имя отправителя. Используется, если в настройках команды не задано Имя пользователя для ответа и разрешено переопределение имён. | Нет |
icon_url | Адрес изображения профиля. Используется, если в команде не задан Значок ответа и разрешено переопределение изображений. | Нет |
channel_id | Опубликовать ответ в другом канале. Пользователь, вызвавший команду, должен быть его участником. По умолчанию — канал, где вызвана команда. | Нет |
goto_location | Адрес, на который перейдёт пользователь после вызова команды: ссылка на канал Loop или внешний адрес (http://, https://, mailto: и др.). | Нет |
type | Тип сообщения, обычно для плагинов. Должен начинаться с custom_. При передаче attachments игнорируется. | Нет |
props | Произвольные данные сообщения в JSON. Ключи from_webhook, override_username и override_icon_url задаёт сам Loop. | Нет |
extra_responses | Массив дополнительных ответов в том же формате, чтобы опубликовать несколько сообщений. Внутри нельзя использовать goto_location и extra_responses. | Нет |
skip_slack_parsing | true — не преобразовывать разметку Slack в тексте. Полезно, если в ответе есть код с символами < и >. | Нет |
Пример ответа с несколькими параметрами:
{
"response_type": "in_channel",
"text": "#### Результаты тестов\n@channel вот запрошенные результаты.\n\n| Компонент | Запущено | Упало |\n| --- | --- | --- |\n| Сервер | 948 | :white_check_mark: 0 |\n| Веб-клиент | 123 | :warning: 2 |",
"username": "test-automation",
"icon_url": "https://example.ru/icon.png",
"props": {
"test_data": {"server": 948, "web": 123}
}
}
Отложенные и множественные ответы
Если на ответ нужно больше нескольких секунд — например, сервис обращается к медленному внешнему API или строит отчёт, — сразу верните короткий ответ, а результат отправьте позже POST-запросом на response_url:
curl -X POST -H 'Content-Type: application/json' \
-d '{"response_type": "in_channel", "text": "Отчёт готов :white_check_mark:"}' \
'https://your-loop-server.ru/hooks/commands/i11f6nnfgfyk8eg56x9omc6dpa'
По одному response_url можно отправить до 5 сообщений в течение 30 минут после вызова команды. Тело запроса — JSON в формате ответа сервиса или обычный текст.