Skip to main content
You can connect Guild to your Slack workspace. The @guildai-services/guildai~slack package gives your agents authenticated access to the Slack Web API. This allows your agents to monitor channels, respond to user messages, and post automated updates.

​
Feature overview

What your Guild Slack integration can do depends entirely on which agents you choose to connect. The integration is highly flexible. The exact capabilities depend on how you configure your Guild agents. Here are a few examples:
Ask questionsAsk questions
File feature requestsFile feature requests
Post rule-based alertsPost rule-based alerts

​
Authentication

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

​
Setup

1

Open Credentials

Go to Credentials in Guild.
2

Connect Slack

Click Slack and authorize Guild in your workspace.
3

Create a trigger

Go to triggers and create a new trigger.
4

Invite the agent

Invite the Slack agent to channels where you want message events. app_mention works without an invite.

​
OAuth scopes

CategoryScopes
Channelschannels:history, channels:read
Groupsgroups:history, groups:read
Messageschat:write, app_mentions:read
Reactionsreactions:read, reactions:write

​
Usage

You can create a Guild agent that interacts with your Slack workspace by importing the Slack tools using the Guild Agents SDK. This configuration registers all available Slack operations as tools on your agent: 
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 agent-scoped webhook model — a single webhook receives all events and Guild routes them to matching triggers.
EventDescription
app_mentionThe Slack agent is mentioned in a channel.
app_uninstalledThe Slack workspace uninstalls the Slack agent.
member_joined_channelA user joins a public or private channel.
message.channelsA user posts a message in a public channel.
message.groupsA user posts a message in a private channel.
reaction_addedA user adds an emoji reaction to a message.
reaction_removedA user removes an emoji reaction from a message.
tokens_revokedThe workspace revokes API tokens for the Slack agent.
Events can be filtered to specific channels by setting channel_ids in the service configuration. Messages from the Slack agent itself are automatically excluded to prevent feedback loops.

​
How the integration works

Guild uses Slack’s OAuth v2 flow. When you connect Slack, Guild receives a bot access token scoped to the installed workspace.
  • Long-lived token — Slack bot tokens do not expire. Guild stores the token once; no refresh flow is required.
  • Bot only — Guild does not receive a user token. All API calls run as the bot, not as the installing user.
  • One workspace per connection — Each Slack install maps to one team_id and one bot token.
  • Bot user ID — Guild captures this at install time and uses it to filter out the agent’s own messages and prevent feedback loops.

​
Inbound events

Slack pushes events to a single agent webhook. Guild validates payloads with HMAC-SHA256 (X-Slack-Signature and X-Slack-Request-Timestamp), deduplicates by event_id, and routes events to matching triggers. Use channel_ids in trigger service_config to limit which channels fire your agent. An empty channel_ids array matches all channels.

​
Outbound API calls

Agents call the Slack Web API through Guild’s proxy, which injects the bot token. The runtime exposes operations as slack_* tools (for example, slack_chat_post_message). Messages always appear from the bot — you cannot post as a specific user. Guild scrubs URLs, thumbnails, avatars, and permalinks from webhook payloads before they reach agents to reduce token usage.

​
Limitations

  • You must invite the Slack agent to channels to receive message events (app_mention works without an invite)
  • If channel_ids is empty in trigger config, events from all channels are processed
  • If someone uninstalls the Slack agent from the workspace, reconnect credentials in Guild. Guild does not receive a revocation webhook.
  • Configure SLACK_WEBHOOK_SIGNING_SECRET for webhook verification

​
AI disclaimers

Because Guild agents use large language models to generate responses, they may occasionally produce inaccurate or incorrect information. Please verify any critical outputs generated by the agent. Guild does not use your Slack data, messages, or files to train large language models. All LLM operations use real-time processing and zero-copy retrieval.

​
Support

If you need help or have questions about the Guild Slack integration, you can contact our support team. Submit a request via our in-app chat or email support@guild.ai.

​
Privacy policy

Your privacy is important to us. Read our full Privacy Policy to learn how we collect, use, and retain your data.