Set up a custom-branded Slack app for Atom | Atomicwork

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.

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.
Create a public API token

Go to Settings > My account > Credential store and click Create token.
Click Create token and give it a name (e.g. “Slack custom app”).
Copy the token immediately and store it somewhere secure.

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":true      },      "assistant_view":{         "assistant_description":"AI-powered assistant for help and support",         "suggested_prompts":[                     ]      }   },   "oauth_config":{      "redirect_urls":[         "https://esd.atomicwork.com"      ],      "scopes":{         "bot":[            "assistant:write",            "app_mentions:read",            "channels:history",            "channels:join",            "channels:manage",            "channels:read",            "chat:write",            "chat:write.customize",            "chat:write.public",            "commands",            "conversations.connect:read",            "dnd:read",            "emoji:read",            "files:write",            "groups:history",            "groups:read",            "groups:write",            "im:history",            "im:read",            "im:write",            "links:write",            "metadata.message:read",            "mpim:write",            "reactions:read",            "reactions:write",            "team.preferences:read",            "team:read",            "users.profile:read",            "users:read",            "users:read.email",            "files:read"         ]      }   },   "settings":{      "event_subscriptions":{         "request_url":"https://bot.atomicwork.com/api/v2/slack/events/custom-app",         "bot_events":[            "assistant_thread_started",            "app_home_opened",            "app_mention",            "message.channels",            "message.groups",            "message.im",            "reaction_added",            "reaction_removed"         ]      },      "interactivity":{         "is_enabled":true,         "request_url":"https://bot.atomicwork.com/api/v1/slack/form/interactive/custom-app",         "message_menu_options_url":"https://bot.atomicwork.com/api/v1/slack/form/select-data-sources/custom-app"      },      "org_deploy_enabled":false,      "socket_mode_enabled":false,      "token_rotation_enabled":false   }}

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

Create the app from your manifest

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

Slack's Create app from manifest dialog with the JSON tab selected and a manifest pasted in.

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.

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.

The Event Subscriptions page in Slack with Enable Events on and the Atomicwork Request URL entered but not yet verified.

Once verified, click Save Changes.

The Event Subscriptions page in Slack showing the Atomicwork Request URL marked Verified.

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 Allow.

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

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.