РазделСлеш-команды

Слеш-команды

Как сделать команду вида /deploy, которая из поля сообщения отправляет запрос вашему сервису и публикует его ответ в канале: настройка, тело запроса, ответ и проверка подписи.

Слеш-команда — это слово со знаком «/» в начале, которое человек пишет в поле сообщения: /deploy, /report. Syncra не публикует эту строку как сообщение, а отправляет запрос на адрес вашего сервиса. Текст из ответа сервиса бот публикует в канале. Так из чата можно запустить выкладку, спросить статус или найти заказ. Команду добавляет владелец или администратор рабочего пространства: настройки рабочего пространства, вкладка «Боты», страница бота, раздел «Слеш-команды». Команда принадлежит боту, поэтому сначала нужен бот: Боты.

Как добавить команду

  1. Откройте настройки рабочего пространства, вкладку «Боты», страницу бота.
  2. В разделе «Слеш-команды» заполните поле «Команда», например deploy. Пишите имя без знака «/»: со знаком поле его не примет.
  3. Если нужно, заполните «Описание (необязательно)»: до 200 символов о том, что делает команда.
  4. В поле «Адрес запроса (необязательно)» вставьте адрес своего сервиса, до 2048 символов.
  5. Нажмите «Добавить команду».
  6. В строке команды найдите «Секрет подписи» и нажмите «Показать». Скопируйте значение, оно начинается с whsec_. Этим секретом ваш сервис проверяет подпись запроса.

Правила для имени команды:

  • От 1 до 32 символов: строчные латинские буквы, цифры, «-» и «_». Заглавные буквы Syncra переводит в строчные.
  • Имена shrug, me, tableflip, unflip и help заняты встроенными командами.
  • Имя должно быть единственным в рабочем пространстве. Две команды с одним именем завести нельзя, даже у разных ботов.

Добавленная команда появляется в подсказках поля сообщения у всех участников рабочего пространства. Команду можно выключить переключателем в её строке и убрать кнопкой «Удалить».

Как команда работает

  1. Человек пишет в поле сообщения /deploy production и отправляет. Команда должна стоять в начале и занимать всё сообщение.
  2. Сообщение в канал не уходит. Поле ввода очищается.
  3. Syncra отправляет POST-запрос на адрес команды и ждёт ответа до 5 секунд.
  4. Если в ответе есть текст, бот публикует его в канале обычным сообщением. Его видят все участники канала.

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

Запрос, который отправляет 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 секунд.
  • Нет ответов, которые видит только вызвавший. Ответ бота видят все участники канала.
  • Нет кнопок, форм и других интерактивных элементов в ответе.
  • В ответе только текст. Файлы приложить нельзя.
  • Нет повторной отправки, если ваш сервис не ответил.

Общий список ограничений собран на странице Что есть и чего нет.