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
- Open the workspace settings, go to the Bots tab and open the bot’s page.
- In Slash commands, fill in the Command field, for example
deploy. Type the name without the leading “/”: the field does not accept a slash. - Fill in Description (optional) if you like: up to 200 characters on what the command does.
- Paste your service’s address into Request URL (optional), up to 2048 characters.
- Press Add command.
- 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,unflipandhelpare 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
- A person types
/deploy productionin the message field and sends it. The command has to start the message and be the whole message. - No message goes to the channel. The message field is cleared.
- Syncra sends a POST request to the command’s address and waits up to 5 seconds for an answer.
- 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.