Set up a custom-branded Slack app for your Assistant

You can configure Atom in Slack to use your own company name, icon, and identity. It also supports Atom in Slack through Slack's AI Agents and Assistants experience. You'll generate a Slack app manifest from Atomicwork's API, use it to create a new app in your Slack workspace, and connect that app back to Atomicwork.

A manifest file is a configuration file written in JSON that defines the structure of a Slack app.

Prerequisites

• A Slack workspace with app creation privileges

• Atomicwork org admin access

• curl and jq installed locally (or any API client of your choice)

Step 1: Generate the manifest

Atomicwork exposes an API endpoint that returns a Slack app manifest pre-configured for your tenant. You'll call it, then use the response in Slack.

1. Disconnect any existing Slack app Go to your Atomicwork tenant at https://<your-domain>.atomicwork.com/settings/apps/SLACK. If a Slack app is already connected, disconnect it before continuing.

2. Create a public API token

• Navigate to Settings > API credentials (under My account) and**** create a public API token.
• Click Create token and give it a name (e.g. "Slack custom app").
• Copy the token immediately and store it somewhere secure.

3. Generate the manifest From a terminal, Postman, or any API client, run the following. Replace <your-domain> with your Atomicwork subdomain and <your-token> with the token from the previous step.

curl --location 'https://<your-domain>.atomicwork.com/api/v1/channel/slack/customise' --header 'Content-Type: application/json' --header 'X-Api-Key: <your-token>' --data '{"app_name": "<Custom App Name>", "long_description": "<Description, should be at least 170 characters>", "type": "SLACK", "short_description": "<Should be at least 20 characters>"}' | jq -r '.manifest'

The | jq -r '.manifest' at the end extracts and unescapes the manifest from the API response, giving you a clean, ready-to-paste JSON manifest. The output will look like this:

{ "display_information":{ "name":"<Custom App Name>", "description":"<Short description>", "background_color":"#676f78", "long_description":"<Long description>" }, "features":{ "app_home":{ "home_tab_enabled":true, "messages_tab_enabled":true, "messages_tab_read_only_enabled":false }, "bot_user":{ "display_name":"<Custom App Name>", "always_online":

Note: Event Subscriptions use /api/v2/slack/events/custom-app while interactivity URLs remain on /api/v1.

Copy this output — you'll paste it into Slack in the next step.

Step 2: Create the custom app in Slack

1. Create the app from your manifest

• Go to https://api.slack.com/apps. and click on Create New App.
• Select From a manifest.
• Pick a workspace and click on Next.
• Select JSON as the format and and paste in the manifest output you'd copied in the previous step.

• Confirm the requested scopes match the list below, then click Create.

|

Permission

|

Purpose

|

assistant:write

|

Allow Atom to use Slack's AI Agents and Assistants capability for AI-powered help and support.

|

app_mentions:read

|

Receive and process messages where @Atom is mentioned, so the app can respond contextually and trigger relevant workflows.

|

channels:history

|

Read messages in public channels where the app has been added. This lets Atom use configured public Slack channels for learning and fetch full thread context when a user creates a request from a conversation.

|

channels:join

|

Join public channels when prompted by a workflow action or user request, so the app can post messages and execute actions in those channels.

|

channels:read

|

Read basic information about public channels (names, IDs) to display available channels for routing and workflow configuration. Does not access message content.

|

chat:write

|

Post messages, reply in threads, and update or delete messages sent by the app. Limited to messages the app itself has sent.

|

chat:write.customize

|

Customize the display name and avatar of messages sent by the app, so replies can appear as the relevant agent or responder.

|

chat:write.public

|

Post messages in public channels where the app hasn't been added as a member. Used for workflow notifications and updates that need to reach specific channels.

|

conversations.connect:read

|

Read metadata about Slack Connect shared channels, so users can include shared channels when configuring routing or other non-learning workflows. Does not access message content.

|

files:read

|

View and download files shared in the workspace. Used when workflows need to process or reference files shared in conversations.

|

files:write

|

Upload and share files within Slack, such as reports, summaries, or workflow-related documents. Limited to files generated by the app.

|

groups:read

|

Read basic metadata of private channels (name, topic, member list) to display them for routing and workflow configuration. Does not access message content.

|

groups:write

|

Post messages in private channels where the app has been added. Used for updates, notifications, and workflow-related messages.

|

im:history

|

Read message history in direct messages between a user and the app. This lets the app reference prior interactions and maintain conversational context.

|

im:read

|

Read basic metadata for DM conversations (channel IDs, user IDs) to identify and manage DMs where the app is active. Does not access message content.

|

im:write

|

Send direct messages to users — for example, to share workflow updates, confirmations, or contextual assistance.

|

metadata.message:read

|

Read structured metadata attached to messages via the Slack Message Metadata API. This lets the app process contextual information (such as workflow identifiers) without accessing message text.

|

reactions:read

|

Read emoji reactions added to messages. Used to detect user signals like acknowledgment or approval within conversations.

|

reactions:write

|

Add emoji reactions to messages to acknowledge user actions, confirm workflow completion, or provide lightweight feedback.

|

team.preferences:read

|

Read workspace-level preferences so the app can align its behavior with workspace configurations. Limited to non-sensitive workspace information.

|

team:read

|

Read basic workspace information (name, domain, icon) to identify the workspace context the app is operating in.

|

users.profile:read

|

Read basic user profile information (name, title, contact details) to personalize interactions and attribute actions correctly. Limited to publicly available profile fields.

|

users:read

|

Identify and reference users within the workspace for routing, assignments, and workflow attribution. Limited to basic user identity information.

|

users:read.email

|

Read user email addresses to map Slack users to their corresponding Atomicwork profiles. This enables cross-system linking and ensures workflows are attributed to the correct user.

2. Verify the Request URL

• In the app settings, go to Event Subscriptions (under Features).
• In the Request URL field, confirm the endpoint is https://bot.atomicwork.com/api/v2/slack/events/custom-app, then click Retry to verify the app with Atomicwork.

• Once verified, click Save Changes.

3. Install the app to your workspace

• Go to Install app (under Settings) in the sidebar and click Install to your workspace.
• Review the permissions and click on Allow.

4. Copy the Slack credentials

• After installing, Slack displays a Bot User OAuth Token. Copy it and store it somewhere secure.

• Go to Basic information (under Settings) in the sidebar.

• Under App Credentials, copy the Signing Secret and store it securely as well.

Step 3: Connect the app to Atomicwork

1. Register the app with Atomicwork

• Use the Slack credentials you just copied and run the following from a terminal, Postman, or any API client. Replace <your-domain> with your Atomicwork subdomain, <your-token> with the Public API token from Step 1, <bot-user-token> with the Bot User OAuth Token, and <signing-secret> with the Signing Secret.

curl --location 'https://<your-domain>.atomicwork.com/api/v1/channel-access-config' --header 'Content-Type: application/json' --header 'X-Api-Key: <your-token>' --data '{"config_data": {"channel_type": "SLACK", "token": "<bot-user-token>", "signing_secret": "<signing-secret>"}, "description": "Slack channel config", "channel_type": "SLACK"}'

Step 4: Verify the connection

In Atomicwork, go to Settings → Apps → Slack. If the status shows "Connected to your Slack workspace", your custom-branded Slack app is set up and ready to go.