Products & Surfaces

Setting up a Slack Surface

Set up a Slack Surface to connect a Product to Slack and route incoming messages to a Capability.

Before you begin

Create a Product and decide which Capability handles Slack messages. Make sure that you can create and install a Slack app in your Slack workspace.

Create the Slack Surface

To create the Slack Surface and its Slack app, follow these steps:

  1. Open the Product that you want to connect to Slack.
  2. Go to Surfaces and click Add Surface.
  3. Select Slack.
  4. Enter a name for the Slack app.
  5. Click Copy manifest.
  6. Click Open Slack app creation.
  7. In Slack, under Or start your own way, select From a manifest, then Continue. Do not choose the AI agent or Starter app template.
  8. In the JSON tab, replace the entire Demo App sample with the manifest. Select your Workspace on the same screen.
  9. Click Next, review the settings, and create the app.
  10. Return to Runtype and click App created, continue. You do not need to wait for an automatic webhook check.

Slack’s app-creation modal ignores the manifest URL parameters. Copy and paste the manifest instead.

If you already created the app, keep using it. Update its settings under Features > App Manifest instead of creating another app.

If Slack says the request URL is not verified, open Features > Event Subscriptions, enable events, and use the events request URL shown in Runtype’s setup wizard. Click Retry if verification times out, then save your changes. URL verification checks the endpoint; it does not mean the app is installed. You do not need an Incoming Webhook or Socket Mode for this setup.

Connect the Slack app

To connect the Slack app to the Surface, follow these steps:

  1. In Slack, open the app that you created.
  2. Go to Basic Information and find App Credentials.
  3. Copy Client ID, Client Secret, and Signing Secret into the Runtype setup wizard.
  4. Click Add to Slack. A popup opens Slack’s authorization page.
  5. Approve the requested permissions in Slack.

Runtype completes the install and shows the connected workspace when setup finishes. Runtype stores the bot token on the server and does not send it through your browser.

Connect with a coding agent

You can start the same setup from a coding agent connected to the Runtype MCP server. Ask the agent to connect your Slack Surface and it fetches the slack-setup documentation topic, which is the full runbook.

The agent does the tool work. You do two things in your browser:

  1. Open the connect page returned by get_slack_app_manifest. Surface-linked connect pages use the same setup wizard as the Product panel: name the app, copy its manifest, and create it in Slack. If you already created it from the agent’s manifest, reuse that app and continue to the connection step.
  2. Paste the Client ID, Client Secret, and Signing Secret into the wizard’s connection step and click Add to Slack.

The connect page is a normal signed-in page in your dashboard. There is no shareable setup link on purpose, because the page collects secrets.

The agent then polls get_surface_setup until it reports ready, which means the install finished and the Surface has the workspace details written to it.

Never paste your Slack Client Secret, Signing Secret, or bot token into a chat with an agent. The connect page is the only place those values belong, and no Runtype tool asks for them. If one ends up in a conversation, finish setup and then rotate it from the Surface’s Reconfigure panel.

If the Surface was paused, the install still records the workspace details but leaves it paused. Un-pause it yourself when you are ready for it to take traffic.

Choose how the Surface responds

A Slack Surface receives direct messages, channel messages, mentions, and thread replies. After you connect the Surface, attach the Capability that handles incoming Slack messages.

If you have not attached a Capability, see Adding capabilities to a Product.

Tool approvals

Slack displays native Approve and Deny buttons when an attached Agent uses Tool approval. For a Runtype Agent, enable Agent Loop before you use these controls and set Max turns to 2 or higher. A Managed external Agent already executes through an effective Runtime Agent Loop and does not need an authored Agent Loop or Max turns setting.

The Agent Loop lane stores a durable checkpoint. When you click a button, the same execution resumes at the reviewed tool call instead of starting the Agent again.

Each Slack decision applies only to the reviewed tool call. The Slack prompt does not offer Always allow. It does not create a remembered approval, even when the Agent configuration enables that choice for another attended UI.

Slack uses explicit buttons to capture approvals. SMS and iMessage capture decisions from replies. For a comparison with other messaging Surfaces, see Approvals on messaging surfaces.

When an approval is pending, later messages in the same Slack conversation do not start another Agent run. Answer the pending prompt first. Approval prompts expire after 1 hour. After expiration, a button cannot resume the execution. Runtype reports an authoring warning for an approval-gated single-pass Runtype Agent because that lane has no checkpoint to resume.

Test the connection

To verify the connection, follow these steps:

  1. Send a direct message to the Slack app or mention it in a channel where it is available.
  2. Confirm that your Product receives the message.
  3. Confirm that Slack displays the response.

If verification succeeds, your Slack Surface is ready to use.

Start with direct messages during testing. After the response looks right, expand to channels or mention-based workflows.

If you build your Product headlessly with the Runtype MCP server or an agent, use get_surface_setup to check one Surface. Pass product_id and surface_id. If the OAuth install remains, the response returns a dashboard link for you to complete. Call get_product_setup to check every Surface on the Product at once.

Next steps

Continue with these guides: