Agent slash commands

Your agent can offer its own slash commands inside a code channel, such as /create-pr, /run-tests, /summarize, or other shortcut that describes the task.

Requirements

• Your app must be the agent bot for the channel (the bot Slack invited when the channel was created) and must be granted the code_channels:manage scope.
• Your app must enable code channels and declare a slash_command_url in its code_channels manifest feature so that Slack knows where to deliver command invocations. Socket Mode and hosted apps don't need to set a URL; their invocations are routed automatically. If your app has neither, the agents.conversations.setCommands API method returns no_actions_url.

Setting your command request URL

Unlike slash commands declared in your app manifest, agent slash commands are registered at runtime and scoped to a single channel. Runtime-registered commands aren't declared in your manifest, so they have no per-command request URL of their own. Tell Slack where to deliver them by setting the slash_command_url property on the code_channels feature in your app manifest:

features:
  code_channels:
    enabled: true
    slash_command_url: https://example.com/slack/code-channel-commands

{
  "features": {
    "code_channels": {
      "enabled": true,
      "slash_command_url": "https://example.com/slack/code-channel-commands"
    }
  }
}

The URL must be https:// (or http://) and at most 3000 characters. Slack delivers every code channel command invocation for your app to this URL as a slash-command-style request.

Registering commands

Call the agents.conversations.setCommands API method, passing the full set of commands your agent offers. A natural time to do this is when your session begins. Update only when the set of useful commands actually changes. Each call replaces your agent's command set for that channel, so always send the complete list you want available. To clear your agent's commands entirely, send an empty commands array. At most 10 commands may exist across all agents in a channel.

POST /api/agents.conversations.setCommands
{
  "channel_id": "C9876543210",
  "commands": [
    {
      "name": "create-pr", // don't include a leading slash (`create-pr`, not `/create-pr`). 
      // should be 1–31 characters, unique within your set, and can't be a built-in Slack command.
      "description": "Open a pull request for the current branch",
      "argument_hint": "[title]"
    },
    {
      "name": "run-tests",
      "description": "Run the test suite and report back"
    }
  ]
}

Receiving requests

When a user types / in the code channel, your agent's commands appear in the typeahead attributed to your app, alongside their descriptions and argument hints. When one of your commands is invoked, Slack POSTs a slash-command-style request to your app's code_channels.slash_command_url, carrying the command, the text, a response_url, and a trigger_id. The body is application/x-www-form-urlencoded and matches the slash command request your app already handles:

token=XXYYZZ
team_id=T123ABC456
team_domain=borant
channel_id=C9876543210
channel_name=fix-flaky-login
user_id=U2345678901
user_name=alice
command=/create-pr
text=Fix the flaky login test
api_app_id=A123ABC456
response_url=https://hooks.slack.com/commands/T123ABC456/1234567890/abcdef
trigger_id=13345224609.738474920.8088930838d88f008e0

Field	Description
command	The invoked command, with its leading slash (e.g., /create-pr).
text	Everything the user typed after the command. Empty string if none.
channel_id	The code channel the command was invoked in.
user_id	The user who invoked the command.
response_url	Use to post one or more responses for up to 30 minutes after invocation.
trigger_id	Use to open a modal with the views.open API method within 3 seconds.
api_app_id	Your app's ID. Confirms which app the invocation was routed to.

Respond just as you would to a manifest slash command: reply synchronously, post later via the response_url, or open a modal with the trigger_id. Refer to responding to slash commands. If you set should_escape: true for the command, the channel, user, and link references in text are escaped/parsed before delivery.

Hosting multiple agents

A code channel can host multiple agents, and each agent owns its own command set. Your call to the agents.conversations.setCommands API method only ever affects your own agent's commands; other agents' commands are left untouched.

Two agents in the same channel may register the same command name (e.g., both could offer /summarize). The composer typeahead shows each command attributed to its owning app, so the user picks which agent they mean. When the user invokes the command, Slack routes it to the agent they selected and delivers the request to that app. It won't be misrouted to a different agent that happens to share the name.

Built-in command names

Command names can't collide with Slack's built-in slash commands (see the full list in this Help Center article). Attempting to register one returns the colliding_with_builtin error. Choose agent-specific names such as /create-pr or /run-tests, which also read more clearly to users.

Error reference

Registration errors are documented on the method page for the agents.conversations.setCommands API method.