Skip to main content

Set up Hatz agents in Slack channels (Beta)

Connect a Slack workspace to Hatz, link user accounts, deploy an owned agent to a channel, and verify channel and direct-message replies.

Beta availability: Slack agent channels are available only in Hatz workspaces enabled for the beta. If you do not see Slack agent channel in Settings, contact your Hatz account team.

Slack agent channels let people talk to Hatz agents from a Slack channel or direct message. A workspace administrator connects one customer-owned Slack app, each agent owner decides where their agent can answer, and each Slack user can link their Slack identity to Hatz for direct messages and private-channel access.

This is different from the Slack MCP integration. Use this article when you want Slack messages to invoke a Hatz agent. Use Adding Slack as a Custom MCP when you want an agent or workflow inside Hatz to read or act on Slack as a connected tool.

Before you begin

Plan for these roles. One person can hold more than one role.

  • Hatz workspace administrator: Opens the Slack setup page, submits the Slack app credentials, checks connection health, and can disconnect the workspace.

  • Slack workspace administrator or app manager: Creates and installs the Slack app and applies the generated manifest.

  • Agent owner: Deploys or removes their own agent from channels. A collaborator cannot deploy an agent they do not own.

  • Slack user: Links their own Slack account to Hatz and chooses which agent answers their direct messages.

You also need:

  • A Hatz tenant enabled for the Slack agent channel beta.

  • Permission to create and install an app in the intended Slack workspace.

  • At least one Hatz agent owned by the person who will deploy it.

  • A Slack channel for testing. Start with a fictional public test channel and text-only prompts so no customer information appears in setup evidence.

Use the Hatz-generated manifest exactly as provided. It requests the required bot scopes app_mentions:read, channels:history, channels:read, chat:write, commands, files:read, groups:history, groups:read, im:history, reactions:write, users:read, and users:read.email. It may also request optional scopes for branded replies, output files, and future multiparty direct-message behavior. Do not remove scopes from the manifest; Hatz shows Action needed when a required scope is missing.

Part 1: Connect the Slack workspace

Who completes this part: A Hatz workspace administrator and a Slack workspace administrator or app manager.

The screenshots use a synthetic example workspace and a test Slack app. Your workspace, app, channel, agent, and administrator names will be different.

Animated walkthrough of the administrator flow from Hatz setup through Slack app creation, credential locations, event configuration, slash command, and Connected status.

1. Open Slack agent setup in Hatz

  1. In the tenant, open Settings.

  2. Open Integrations & Tools.

  3. Find Slack agent channel and select Set up Slack agent.

The setup page shows three stages: Create and install the app, Verify credentials, and Enable Slack events.

Hatz Slack setup progress showing Create and install the app, Verify credentials, and Enable Slack events completed.

2. Create the Slack app from the bootstrap manifest

  1. Under Create and install the Slack app, select Create app in Slack. Hatz opens Slack with the bootstrap manifest prefilled.

  2. Choose the Slack workspace that Hatz should serve.

  3. Review the app configuration, then create the app.

  4. In Slack app settings, open Install App, select Install to Workspace, and approve the requested access.

Success check: Slack shows the app as installed to the intended workspace and displays a Bot User OAuth Token beginning with xoxb-.

Slack Review your app dialog summarizing what the Hatz app can read, do, and show to users before creation.

Slack authorization page for allowing the Hatz app to access an example workspace after reviewing its permissions.

3. Copy the three credentials from Slack

  • Copy the App ID from Basic Information.

  • Copy the Signing Secret from Basic Information → App Credentials.

  • Copy the Bot User OAuth Token from Install App. Use the value beginning with xoxb-; do not use Slack's legacy verification token.

Keep these values private. The bot token and signing secret authorize the connection. Do not paste them into chat, screenshots, screen recordings, support tickets, or shared documents.

Slack App Credentials section showing the locations of the masked App ID, Client ID, client secret, and signing secret.

Slack OAuth and Permissions page showing the location of the fully redacted Bot User OAuth Token.

4. Verify the credentials in Hatz

  1. Return to the Hatz Slack setup page.

  2. Enter the Slack App ID, Slack signing secret, and Slack bot token.

  3. Select Verify and continue.

Hatz verifies the app and workspace, encrypts the submitted secrets, and never shows them again.

Success check: The first two setup stages show complete and Enable Slack events becomes the current stage.

5. Apply the connection-specific manifest

  1. Under Enable Slack events, select Copy manifest.

  2. In the Slack app settings, open App Manifest.

  3. Replace the existing manifest with the connection-specific manifest copied from Hatz, then save the changes.

  4. If Slack asks you to reinstall or reauthorize the app, complete that prompt.

  5. In Slack, open Event Subscriptions and confirm the Request URL shows Verified. If Slack shows a verification prompt or Retry, complete it before continuing.

  6. Return to Hatz and select Check connection.

The full manifest gives Slack the exact Events API request URL and the exact request URL for the /hatz command. Keep the generated URLs unchanged; they identify this Hatz connection.

Success check: Hatz shows Connected, Slack events are ready, the intended workspace name, a Last verified time, and no missing required scopes.

Hatz Slack setup page showing the generated connection manifest and the channel governance section.

Slack Event Subscriptions page with events enabled and the Hatz request URL verified; the connection identifier is redacted.

Slack Slash Commands page showing the configured slash command named slash-hatz.

Hatz Slack setup page showing all three stages complete, a Connected status, healthy Slack events, masked app identifiers, and granted scopes.

6. Invite the Hatz bot to a test channel

In Slack, open the channel where you want to test the integration and invite the Hatz app. Hatz can list and deploy only to channels the bot has joined.

Success check: Slack shows the Hatz app as a channel member.

Example Slack test channel showing the Hatz app joined and ready for a channel mention.

Part 2: Link your Slack account and choose a direct-message agent

Who completes this part: Each Slack user links only their own identity. Linking is required to choose a direct-message agent and to discover private channels the user can access.

Animated walkthrough of linking a Slack identity to Hatz with a redacted one-time code and selecting a direct-message agent.

  1. In Slack, run /hatz link.

  2. Copy the one-time linking code. It expires after five minutes.

  3. In Hatz, open Settings → Personal Settings.

  4. In the Slack account card, enter the code.

  5. Review the Slack identity and Hatz account shown in the confirmation, then select Link @your-handle.

  6. Under DM agent, choose Hatz built-in agent (default) or an agent you own.

Success check: The Slack account card shows the connected Slack workspace and account, and Slack direct messages to the app receive a response from the selected agent.

Only agents you own appear in the DM agent list. This prevents a direct message from running another person's connected accounts.

Hatz Personal Settings Slack account card with an empty one-time linking code field and instructions to run slash-hatz link.

Slack response to slash-hatz link showing the one-time linking code and account URL fully redacted and an expiration warning.

Hatz Slack identity confirmation card with synthetic user and email values before linking the accounts.

Hatz Slack account card showing a linked example workspace and Slack Beta Helper selected as the direct-message agent.

Part 3: Deploy an agent to a Slack channel

Who completes this part: The recorded owner of the Hatz agent.

Animated walkthrough of inviting the Hatz app, deploying an agent, verifying channel and direct-message replies, and reviewing governance controls.

  1. Open Workshop and edit the agent you own.

  2. Find the Slack channels section.

  3. Select Deploy to a channel… and choose the joined Slack channel.

  4. Review the confirmation. Everyone in that channel can invoke the agent. If the agent has connected tools, those tools run with the agent owner's credentials—not each channel member's credentials.

  5. Select Deploy agent. If connected tools are listed, select I understand, deploy.

Success check: The agent editor lists the channel under Slack channels, and the administrator's Channel deployments view lists the channel, agent, owner, and deployment health.

Review connected tools before deployment. Anyone in the selected channel may be able to invoke the connected tools shown in the confirmation, using the agent owner's access. Deploy only to an audience that should have that capability.

Hatz agent editor confirmation dialog for deploying Slack Beta Helper to an example Slack channel.

Hatz Channel governance view showing an active Slack Beta Helper deployment, its owner, and deployer.

Part 4: Test the complete flow

Test the channel

  1. In the test channel, type @, select the installed app from Slack's mention picker, and ask a text-only question. For example, if the app is named Acme Assistant, enter: @Acme Assistant Reply with the name of the agent serving this channel and one sentence confirming the connection works.

  2. Confirm the installed app replies in the channel.

  3. Ask a second fictional prompt that matches the agent's instructions, then confirm the answer comes from the deployed agent.

Test a direct message

  1. Open a direct message with the Hatz app in Slack.

  2. Send a text-only prompt.

  3. Confirm the reply comes from the DM agent selected in Hatz Personal Settings.

Channel and direct-message routing are separate: a channel uses its deployed agent or the built-in fallback, while a direct message uses the linked user's DM agent preference.

Example Slack channel thread showing a mention of Hatz and a successful reply from Slack Beta Helper.

Slack direct-message thread showing a text prompt and a successful reply from Slack Beta Helper.

Change or remove a deployment

  • Replace the channel's agent: The new agent's owner selects the same channel from their agent editor and confirms the replacement.

  • Remove an agent from a channel: The agent owner selects the remove control beside the channel in the agent editor.

  • Edit a deployed agent: While any Slack channel deployment exists, only the agent's owner can edit it. Remove every Slack deployment before transferring ownership or relying on normal shared editing.

  • Disconnect a linked Slack identity: Open Settings → Personal Settings and select Disconnect on that Slack account.

Disconnect the Slack workspace

A workspace administrator can open the Slack agent setup page and select Disconnect workspace. Hatz stops accepting Slack events and deletes the stored bot token and signing secret.

Undeploy first for a durable stop. Disconnecting retains channel assignments. Reconnecting the same Slack app and workspace can reactivate them. If the stop must remain in effect after a future reconnect, have each agent owner remove their deployments and confirm Channel deployments is empty before disconnecting.

Hatz connection maintenance controls for replacing a bot token or signing secret and disconnecting the workspace.

Hatz connection maintenance form for reconnecting a Slack workspace with an app ID, signing secret, and bot token.

Troubleshooting

  • Slack agent channel is missing in Settings: The tenant may not be enabled for the beta, or your role may not allow connection administration. Contact your Hatz account team or workspace administrator.

  • The credentials cannot be verified: Confirm the App ID and xoxb- bot token came from the same Slack app and workspace. Do not use Slack's legacy verification token.

  • Hatz shows Action needed or missing required scopes: Restore the generated manifest, reinstall or reauthorize the Slack app, then select Check connection.

  • Hatz shows Finish setup: Apply the connection-specific manifest in Slack, save it, and return to Hatz to check the connection.

  • A token check passes but Slack messages do not arrive: Confirm Hatz also shows Connected and a recent Last verified time. Token health and Slack event URL verification are separate.

  • No channels appear in the agent editor: Invite the Hatz app to the Slack channel, then refresh the Hatz agent editor.

  • A private channel does not appear: Invite the Hatz app to the private channel, link your own Slack account in Hatz Personal Settings, and confirm your Slack user is a member of that channel.

  • The bot was removed from a deployed channel: Invite the Hatz app back to the channel. The assignment remains stored, but Hatz cannot answer there while the bot is absent.

  • Replies use the plain app name instead of the agent's name or icon: Reauthorize the app with the optional chat:write.customize scope.

  • You replaced the signing secret: Hatz pauses event verification. Reapply the exact connection-specific manifest in Slack, save it, then check the connection.

  • You need Support: Send the workspace name, approximate time, lifecycle status, and visible error. Do not send bot tokens, signing secrets, one-time link codes, or screenshots containing them.

Current beta limitations

  • Slack agent channels use one customer-owned Slack app per Hatz workspace.

  • Only an agent's owner can deploy that agent or edit it while it remains deployed.

  • Only channels the Hatz bot has joined can be listed for deployment.

  • Private-channel discovery also requires the agent owner's linked Slack identity and membership in that channel.

  • Direct messages can use the built-in Hatz agent or an agent the linked user owns.

  • This guide validates text replies. Output-file delivery is not included in this beta setup walkthrough.

Did this answer your question?