Skip to main content
The @guildai-services/guildai~slack package provides agents with access to the Slack Web API through Guild’s OAuth integration.

​
Authentication

  • Type: OAuth 2.0
  • Token management: Slack tokens don’t expire — no refresh needed

​
Setup

​
OAuth scopes

CategoryScopes
Channelschannels:history, channels:join, channels:manage, channels:read
Groupsgroups:history, groups:read, groups:write
Direct messagesim:history, im:read
Group DMsmpim:history, mpim:read
Messageschat:write, app_mentions:read
Filesfiles:read, files:write
Reactionsreactions:read, reactions:write
Usersusers:read, users:read.email, users.profile:read
User groupsusergroups:read, usergroups:write
Teamteam:read

​
Usage

import { slackTools } from "@guildai-services/guildai~slack"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that manages Slack messages",
  tools: { ...slackTools },
})

​
Selecting specific tools

Agents perform better with fewer tools. Use pick() to include only what your agent needs. Tools are named with the slack_ prefix — for example, chat_post_message becomes slack_chat_post_message. 
import { slackTools } from "@guildai-services/guildai~slack"
import { llmAgent, pick } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that posts Slack updates",
  tools: {
    ...pick(slackTools, [
      "slack_chat_post_message",
      "slack_conversations_list",
      "slack_conversations_history",
    ]),
  },
})

​
API endpoints

OperationMethodPath
chat_post_messagePOST/chat.postMessage
chat_updatePOST/chat.update
chat_deletePOST/chat.delete
chat_post_ephemeralPOST/chat.postEphemeral
chat_schedule_messagePOST/chat.scheduleMessage
chat_scheduled_messages_listGET/chat.scheduledMessages.list
chat_delete_scheduled_messagePOST/chat.deleteScheduledMessage
chat_get_permalinkGET/chat.getPermalink
OperationMethodPath
conversations_listGET/conversations.list
conversations_infoGET/conversations.info
conversations_historyGET/conversations.history
conversations_repliesGET/conversations.replies
conversations_membersGET/conversations.members
conversations_joinPOST/conversations.join
conversations_leavePOST/conversations.leave
conversations_invitePOST/conversations.invite
conversations_archivePOST/conversations.archive
conversations_unarchivePOST/conversations.unarchive
conversations_set_topicPOST/conversations.setTopic
conversations_set_purposePOST/conversations.setPurpose
OperationMethodPath
reactions_addPOST/reactions.add
reactions_getGET/reactions.get
reactions_listGET/reactions.list
reactions_removePOST/reactions.remove
OperationMethodPath
files_infoGET/files.info
files_deletePOST/files.delete
OperationMethodPath
pins_addPOST/pins.add
pins_listGET/pins.list
pins_removePOST/pins.remove
OperationMethodPath
reminders_addPOST/reminders.add
reminders_completePOST/reminders.complete
reminders_deletePOST/reminders.delete
reminders_listGET/reminders.list
OperationMethodPath
users_infoGET/users.info
users_listGET/users.list
users_lookup_by_emailGET/users.lookupByEmail
users_profile_getGET/users.profile.get
OperationMethodPath
usergroups_createPOST/usergroups.create
usergroups_listGET/usergroups.list
usergroups_updatePOST/usergroups.update
usergroups_users_listGET/usergroups.users.list
usergroups_users_updatePOST/usergroups.users.update
OperationMethodPath
team_infoGET/team.info
emoji_listGET/emoji.list
bots_infoGET/bots.info

​
Webhook events

Slack uses an app-scoped webhook model — a single webhook receives all events and Guild routes them to matching triggers.
EventDescription
app_mentionThe Guild bot is mentioned in a channel
messageA message is posted in a channel the bot is in
reaction_addedA reaction is added to a message
reaction_removedA reaction is removed from a message
member_joined_channelA user joins a channel
channel_createdA new channel is created
Events can be filtered to specific channels by setting channel_ids in the service configuration. Messages sent by the Guild bot itself are automatically excluded to prevent feedback loops.

​
Limitations

  • The bot must be invited to channels to receive message events (except app_mention, which works without an invite)
  • If the app is uninstalled from the workspace, credentials must be reconnected in Guild

​
How the Slack Integration Works

  Auth: OAuth 2.0, Bot Token Only  Guild uses Slack’s OAuth v2 flow. When a user connects Slack, they go through the standard redirect dance and Guild gets back a bot access token — a single token scoped to the installed workspace. Key things about this token:   - Never expires. Slack bot tokens are long-lived with no expiry. Guild stores it once and uses it forever — no refresh logic needed.   - No user token. Guild only gets a bot token, not a per-user token. All API calls are made as the bot, not as the user who installed it.   - One workspace per connection. A single Slack install = one team_id + one bot token. If you want multiple Slack workspaces in one Guild workspace, that’s not   supported.   - Bot user ID is captured at install time and stored alongside the token — this is used to filter out the bot’s own messages to prevent infinite loops.   Slack’s Architecture and What It Means Here   Slack’s API is split into two worlds:   1. Events (inbound) — via webhooks   Slack pushes events to a single registered URL (/webhooks/slack). Guild validates the payload with HMAC-SHA256 (using X-Slack-Signature + X-Slack-Request-Timestamp), deduplicates by event_id, and routes to matching triggers.  Supported events: message, app_mention, reaction_added/removed, member_joined_channel, channel_created.  Limitations of the event model:   - The bot must be invited to a channel to receive message events there. app_mention is the exception — that works everywhere.   - If channel_ids is empty in the trigger config, all channels are processed (no default filtering). Easy to accidentally flood an agent with events.   - Events are app-scoped — there’s no per-user event subscription.   2. API calls (outbound) — via Web API proxy  Agents make Slack API calls (post messages, list channels, etc.) through Guild’s HTTP proxy, which injects the bot token. The runtime exposes ~45 operations as agent tools (slack_chat_post_message, slack_conversations_list, etc.). Because everything uses the bot token, all messages come from the bot — you can’t post as a specific user. Other Noteworthy Limitations   - App uninstall = silent breakage. If someone uninstalls the Slack app from their workspace, the token goes invalid. There’s no revocation webhook handling — the user just has to reconnect.   - Payload scrubbing. Before webhooks reach agents, Guild strips URLs, thumbnails, avatars, and permalinks to reduce token usage. Agents won’t see file previews or image URLs from Slack.   - Signing secret is required. SLACK_WEBHOOK_SIGNING_SECRET must be configured or the webhook handler will error — no graceful degradation.