Слеш-команды
Как сделать команду вида /deploy, которая из поля сообщения отправляет запрос вашему сервису и публикует его ответ в канале: настройка, тело запроса, ответ и проверка подписи.
Слеш-команда — это слово со знаком «/» в начале, которое человек пишет в поле сообщения: /deploy, /report. Syncra не публикует эту строку как сообщение, а отправляет запрос на адрес вашего сервиса. Текст из ответа сервиса бот публикует в канале. Так из чата можно запустить выкладку, спросить статус или найти заказ. Команду добавляет владелец или администратор рабочего пространства: настройки рабочего пространства, вкладка «Боты», страница бота, раздел «Слеш-команды». Команда принадлежит боту, поэтому сначала нужен бот: Боты.
Как добавить команду
- Откройте настройки рабочего пространства, вкладку «Боты», страницу бота.
- В разделе «Слеш-команды» заполните поле «Команда», например
deploy. Пишите имя без знака «/»: со знаком поле его не примет. - Если нужно, заполните «Описание (необязательно)»: до 200 символов о том, что делает команда.
- В поле «Адрес запроса (необязательно)» вставьте адрес своего сервиса, до 2048 символов.
- Нажмите «Добавить команду».
- В строке команды найдите «Секрет подписи» и нажмите «Показать». Скопируйте значение, оно начинается с
whsec_. Этим секретом ваш сервис проверяет подпись запроса.
Правила для имени команды:
- От 1 до 32 символов: строчные латинские буквы, цифры, «-» и «_». Заглавные буквы Syncra переводит в строчные.
- Имена
shrug,me,tableflip,unflipиhelpзаняты встроенными командами. - Имя должно быть единственным в рабочем пространстве. Две команды с одним именем завести нельзя, даже у разных ботов.
Добавленная команда появляется в подсказках поля сообщения у всех участников рабочего пространства. Команду можно выключить переключателем в её строке и убрать кнопкой «Удалить».
Как команда работает
- Человек пишет в поле сообщения
/deploy productionи отправляет. Команда должна стоять в начале и занимать всё сообщение. - Сообщение в канал не уходит. Поле ввода очищается.
- Syncra отправляет POST-запрос на адрес команды и ждёт ответа до 5 секунд.
- Если в ответе есть текст, бот публикует его в канале обычным сообщением. Его видят все участники канала.
Вызвать команду может любой участник рабочего пространства в канале, где он состоит. Боту состоять в этом канале не обязательно.
Запрос, который отправляет Syncra
POST ваш адрес запроса
Syncra отправляет этот запрос на адрес из поля «Адрес запроса» каждый раз, когда человек вызывает команду.
Заголовки:
| Заголовок | Значение | Описание |
|---|---|---|
Content-Type |
application/json |
Тело запроса — JSON. |
X-Syncra-Event |
slash.command |
Всегда это значение. |
X-Syncra-Timestamp |
число | Время отправки в секундах Unix. |
X-Syncra-Signature |
v1=<hex> |
Подпись запроса секретом команды. |
Поля тела:
| Поле | Тип | Обязательно | Описание |
|---|---|---|---|
command |
string | да | Имя команды без «/», строчными буквами. |
text |
string | да | Всё, что человек написал после команды. Пустая строка, если ничего. До 4000 символов. |
channelId |
string | да | Номер канала, где вызвали команду. |
channelName |
string | да | Название канала. |
workspaceId |
string | да | Номер рабочего пространства. |
userId |
string | да | Номер человека, который вызвал команду. |
userName |
string | да | Его имя. |
botId |
string | да | Номер бота, которому принадлежит команда. |
Тело запроса для /deploy production:
{
"command": "deploy",
"text": "production",
"channelId": "...",
"channelName": "releases",
"workspaceId": "...",
"userId": "...",
"userName": "Анна Ким",
"botId": "..."
}
Команда ниже запускается в терминале. Она собирает такой же запрос и подписывает его вашим секретом, так что обработчик можно проверить без Syncra. Подставьте адрес своего обработчика.
SECRET="whsec_..."
BODY='{"command":"deploy","text":"production","channelId":"...","channelName":"releases","workspaceId":"...","userId":"...","userName":"Anna","botId":"..."}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)
curl -X POST "http://localhost:3000/syncra/commands" \
-H "Content-Type: application/json" \
-H "X-Syncra-Event: slash.command" \
-H "X-Syncra-Timestamp: $TS" \
-H "X-Syncra-Signature: v1=$SIG" \
-d "$BODY"
Ответ вашего сервиса, 200 OK:
{
"text": "Выкладка production запущена"
}
Что ответить
| Ответ вашего сервиса | Что делает Syncra |
|---|---|
Статус 2xx и JSON с непустой строкой text |
Бот публикует text в канале. Текст длиннее 4000 символов обрезается до 4000. |
Статус 2xx без text, с пустым text или не JSON |
Ничего не публикует. Команда считается выполненной. |
| Другой статус, сетевая ошибка или молчание дольше 5 секунд | Человек видит ошибку «Не удалось выполнить /deploy. Попробуйте ещё раз.», а набранная команда возвращается в поле ввода. |
Повторных попыток нет: один вызов команды — один запрос. Если работа занимает больше 5 секунд, ответьте сразу коротким текстом, а результат опубликуйте позже через API ботов: номер канала есть в поле channelId. Для этого бот должен состоять в канале.
Проверка подписи
Схема та же, что у подписок на события. Подпись — HMAC SHA-256 в шестнадцатеричной записи. Ключ — секрет этой команды. Подписывается значение X-Syncra-Timestamp, точка и тело запроса в том виде, в каком оно пришло.
X-Syncra-Signature: v1=HMAC_SHA256(secret, "<timestamp>.<тело запроса>")
У каждой команды свой секрет. Секрет подписки на события к команде не подходит.
Обработчик на Node.js без сторонних библиотек. Он проверяет подпись и отвечает текстом:
import { createServer } from "node:http";
import { createHmac, timingSafeEqual } from "node:crypto";
const secret = process.env.SYNCRA_COMMAND_SECRET; // whsec_...
createServer((req, res) => {
const chunks = [];
req.on("data", (chunk) => chunks.push(chunk));
req.on("end", () => {
const rawBody = Buffer.concat(chunks);
const timestamp = String(req.headers["x-syncra-timestamp"] ?? "");
const received = Buffer.from(String(req.headers["x-syncra-signature"] ?? ""));
const expected = Buffer.from(
"v1=" + createHmac("sha256", secret).update(`${timestamp}.`).update(rawBody).digest("hex"),
);
if (received.length !== expected.length || !timingSafeEqual(received, expected)) {
res.writeHead(401).end();
return;
}
const { command, text, userName } = JSON.parse(rawBody.toString("utf8"));
res.writeHead(200, { "Content-Type": "application/json" });
res.end(JSON.stringify({ text: `${userName}: /${command} ${text}` }));
});
}).listen(3000);
Команда без адреса
Поле «Адрес запроса (необязательно)» можно оставить пустым. Тогда в строке команды вместо адреса написано «ИИ», и поведение зависит от бота:
- У бота включён переключатель «Ответы ИИ». На команду отвечает ИИ самого бота, ваш сервис не нужен. Бот сразу публикует в канале «…», а затем заменяет его ответом. Текст после команды служит вопросом.
- Переключатель «Ответы ИИ» выключен. Команда не выполняется, человек видит ту же ошибку, что и при сбое вашего сервиса.
Чего слеш-команды не умеют
- Нет отложенных ответов. Ответ на запрос нужен за 5 секунд.
- Нет ответов, которые видит только вызвавший. Ответ бота видят все участники канала.
- Нет кнопок, форм и других интерактивных элементов в ответе.
- В ответе только текст. Файлы приложить нельзя.
- Нет повторной отправки, если ваш сервис не ответил.
Общий список ограничений собран на странице Что есть и чего нет.