Create a Custom Slack Handle for an Agent

A custom Slack handle lets teammates start a specific Firetiger agent by mentioning a workspace handle such as @checkout-oncall. The handle is a Slack user group: Firetiger creates a new one if the handle is unused, or binds to an existing workspace group if the handle already exists. The trigger decides which agent responds and which channels are in scope.

Use this when you want a memorable Slack mention for a purpose-built agent, instead of routing every Slack request through the default Firetiger mention.

Prerequisites

A Firetiger agent.
A Slack connection with the Firetiger app installed. See Slack.
The Slack connection must include usergroups:read to import existing handles. It also needs usergroups:write to create a new Slack user group when the handle is unused. If the connection was installed before custom handles were added, reconnect the Slack app from the connection page.
A Slack workspace with user groups. Custom handles are implemented as Slack user groups, which require Slack Business+ or Enterprise Grid. To create a new handle from Firetiger, workspace policy must allow user-group management. To use an existing handle, the user group can be created and managed in Slack by an admin.
Any channels you want to pick should be available to the Slack connection. If a channel is missing from the picker, update the connection’s Allowed channels list first.

Slack workspace requirements

Firetiger creates user groups on your behalf using the usergroups:read and usergroups:write scopes when the handle is unused. If your workspace blocks user-group management and the requested handle does not already exist, handle creation will fail with:

Slack workspace blocks user group management

This is a workspace policy, not a Firetiger permission. To unblock:

Confirm your workspace is on Slack Business+ or Enterprise Grid — user groups are not available on Free or Pro plans.
Ask a Slack workspace admin to create the user group in Slack, then enter that existing handle in Firetiger.
Alternatively, ask a Slack workspace admin to allow user-group creation. Slack admins can review the setting in Manage user groups from the admin dashboard.

After your admin creates the group or enables user-group management, you can retry adding the handle in Firetiger without reconnecting.

Create the trigger

In Firetiger, go to Agents and open the agent that should respond to the Slack handle.
Open the agent’s Plan page.
In the triggers area, click the + button to create a trigger.
Select Slack @mention.
Choose the Slack connection for the workspace where the handle should exist.
Under SlackHandle, select an existing Firetiger handle or click Add.
Enter the handle name, then click Add. If the Slack user group already exists, Firetiger imports it without changing its membership. If it does not exist and Slack allows Firetiger to create user groups, Firetiger creates it. Use the handle text without the leading @; Firetiger normalizes it to lowercase. Handles must be at least four characters.
Under Channels, either select the channels where this agent should respond, or leave the field empty to respond in any channel allowed by the Slack connection.
Click Create trigger.

After the trigger is created, mention the handle in Slack:

@checkout-oncall investigate the elevated checkout error rate

Firetiger starts a new session for the selected agent and includes the Slack mention context, including the channel, user, message text, and permalink.

Channel scope

Slack @mention triggers have two channel controls:

The Slack connection’s Allowed channels list controls which channels are eligible for triggers.
The trigger’s Channels field narrows this specific agent to a subset of those channels.

If the trigger’s Channels field is empty, the agent can respond anywhere the connection is allowed to receive matching mentions. If you select channels on the trigger, mentions in other channels are ignored.

Handle behavior

A SlackHandle is separate from the trigger that routes mentions. The handle reserves the Slack @ name in the workspace, while the trigger points that handle at an agent.

You can reuse an existing handle when creating another trigger. This is useful when the same Slack handle should route to another agent, or when you are recreating a trigger after changing channel scope.

If the workspace already has a user group with the handle you enter, Firetiger binds to it instead of creating a duplicate. Firetiger does not change that group’s membership.

Deleting a SlackHandle removes the Firetiger record but leaves the underlying Slack user group in place — including its members. Other people in your workspace may rely on that group, so Firetiger never disables or deletes it on your behalf. If you want the group itself removed, a Slack workspace admin can do that from Slack.

If a Slack message mentions both @firetiger and a custom handle, Firetiger runs only the custom handle trigger to avoid duplicate responses.

Troubleshooting

No Slack connection appears. Install the Firetiger Slack app from Integrations first.

The handle cannot be created because scopes are missing. Reconnect the Slack app so Firetiger can request usergroups:read and usergroups:write. Existing handle import requires usergroups:read; creating a new Slack user group requires usergroups:write.

The Slack user group is disabled (slack user group is disabled). A workspace user group with this handle exists but has been disabled. Firetiger does not automatically re-enable groups it doesn’t own end-to-end — ask a Slack workspace admin to re-enable it, then retry handle creation.

A channel is missing from the picker. Open the Slack connection and update Allowed channels, then return to the agent’s trigger form.

Slack user groups are restricted (Slack workspace blocks user group management). Your workspace plan or policy doesn’t allow Firetiger to create user groups, and the handle you entered was not found. See Slack workspace requirements above — a Slack admin can create the group in Slack first, enable user-group creation, or upgrade the workspace to Business+ or Enterprise Grid.