SectionSlash commands

Slash commands

How to add a command like /deploy that sends a request to your service and posts its answer in the channel, with the request your service receives and what it should answer.

A slash command is a word with a leading “/” that a person types in the message field: /deploy, /report. Syncra does not post that line as a message. It sends a request to your service’s address instead, and a bot posts the text from your service’s answer in the channel. A team can, for example, start a deploy without leaving the chat. A workspace owner or admin adds a command: workspace settings, the Bots tab, the bot’s page, the Slash commands section. A command belongs to a bot, so you need a bot first: Bots.

Add a command

  1. Open the workspace settings, go to the Bots tab and open the bot’s page.
  2. In Slash commands, fill in the Command field, for example deploy. Type the name without the leading “/”: the field does not accept a slash.
  3. Fill in Description (optional) if you like: up to 200 characters on what the command does.
  4. Paste your service’s address into Request URL (optional), up to 2048 characters.
  5. Press Add command.
  6. In the command’s row, find Signing secret and press Reveal. Copy the value, it starts with whsec_. Your service uses this secret to check the request signature.

Rules for the command name:

  • 1 to 32 characters: lowercase Latin letters, digits, “-” and “_”. Syncra turns capital letters into lowercase.
  • The names shrug, me, tableflip, unflip and help are taken by built-in commands.
  • A name must be unique in the workspace. Two commands cannot share a name, even under different bots.

Once added, the command appears among the suggestions in the message field for every member of the workspace. You can turn a command off with the switch in its row and remove it with Delete.

How a command runs

  1. A person types /deploy production in the message field and sends it. The command has to start the message and be the whole message.
  2. No message goes to the channel. The message field is cleared.
  3. Syncra sends a POST request to the command’s address and waits up to 5 seconds for an answer.
  4. If the answer has text, the bot posts it in the channel as a regular message. Every member of the channel sees it.

Any workspace member can run a command in a channel they are a member of. The bot does not have to be a member of that channel.

The request Syncra sends

POST your Request URL

Syncra sends this request to the address from the Request URL field every time a person runs the command.

Headers:

Header Value Description
Content-Type application/json The body is JSON.
X-Syncra-Event slash.command Always this value.
X-Syncra-Timestamp number The time the request was sent, in Unix seconds.
X-Syncra-Signature v1=<hex> The request signature, made with the command’s secret.

Body fields:

Field Type Required Description
command string yes The command name without “/”, in lowercase.
text string yes Everything the person typed after the command. An empty string if nothing. Up to 4000 characters.
channelId string yes The id of the channel where the command was run.
channelName string yes The channel’s name.
workspaceId string yes The workspace id.
userId string yes The id of the person who ran the command.
userName string yes That person’s name.
botId string yes The id of the bot that owns the command.

The request body for /deploy production:

{
  "command": "deploy",
  "text": "production",
  "channelId": "...",
  "channelName": "releases",
  "workspaceId": "...",
  "userId": "...",
  "userName": "Anna Kim",
  "botId": "..."
}

To test your handler without Syncra, run this command. It builds the same request and signs it with your secret. Put in the address of your own handler.

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"

Your service’s response, 200 OK:

{
  "text": "Deploy to production started"
}

What to answer

Your service’s response What Syncra does
A 2xx status and JSON with a non-empty text string The bot posts text in the channel. Text longer than 4000 characters is cut to 4000.
A 2xx status with no text, an empty text, or a body that is not JSON Posts nothing. The command counts as done.
Another status, a network error, or silence for longer than 5 seconds The person sees the error “Couldn’t run /deploy. Please try again.”, and the typed command returns to the message field.

There are no retries: one run of a command is one request. If the work takes longer than 5 seconds, answer right away with a short text and post the result later through the bot API: the channel id is in the channelId field. The bot has to be a member of the channel for that.

Check the signature

The scheme is the same as for event subscriptions. The signature is an HMAC SHA-256 in hex. The key is this command’s secret. The signed string is the value of X-Syncra-Timestamp, a dot, and the request body exactly as it arrived.

X-Syncra-Signature: v1=HMAC_SHA256(secret, "<timestamp>.<request body>")

Each command has its own secret. The secret of an event subscription does not work for a command.

A handler in Node.js with no third-party libraries. It checks the signature and answers with text:

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);

A command with no address

You can leave Request URL (optional) empty. The command’s row then shows “AI” in place of an address, and what happens depends on the bot:

  • The bot has the AI responses switch on. The bot answers the command itself with AI, with no service of yours involved. The bot posts “…” in the channel at once and then replaces it with the answer. The text after the command is the question.
  • AI responses is off. The command does not run, and the person sees the same error as when your service fails.

What slash commands do not do

  • Your service cannot send a late answer to the command’s request. The answer is due within 5 seconds, and a later result goes through the bot API.
  • There are no answers that only the caller sees. Every member of the channel sees the bot’s answer.
  • There are no buttons, forms or other interactive elements in an answer.
  • An answer is text only. It cannot carry files.
  • There is no retry if your service did not answer.

The full list of limits is on the What exists and what does not page.