Slack Bot

npm install agent-messenger

import { SlackBotClient, SlackBotCredentialManager, SlackBotError, SlackBotListener } from 'agent-messenger/slackbot'

import { SlackBotClient } from 'agent-messenger/slackbot'

const client = await new SlackBotClient().login({ token: 'xoxb-...' })

const client = await new SlackBotClient().login()

// Verify bot credentials and resolve the bot's identity in the workspace
const me = await client.testAuth()
// → { user_id, team_id, bot_id?, user?, team? }

// Send a message to a channel
const msg = await client.postMessage('C0ACZKTDDC0', 'Hello world')

// Reply in a thread
const reply = await client.postMessage('C0ACZKTDDC0', 'Reply', { thread_ts: '1234567890.123456' })
// → SlackMessage { ts, text, type, user?, thread_ts? }

// Send a Block Kit message — `text` is used as the fallback/notification text
await client.postMessage('C0ACZKTDDC0', 'Build finished', {
  blocks: [{ type: 'section', text: { type: 'mrkdwn', text: '*Build finished*' } }],
})

// Other supported pass-through options (forwarded as-is to chat.postMessage):
//   attachments?: unknown[]
//   unfurl_links?: boolean
//   unfurl_media?: boolean
//   mrkdwn?: boolean

// Read a channel's recent messages (default limit: 20, supports cursor pagination)
const history = await client.getConversationHistory('C0ACZKTDDC0')
const limited = await client.getConversationHistory('C0ACZKTDDC0', { limit: 50 })
const next = await client.getConversationHistory('C0ACZKTDDC0', { cursor: 'dXNlcjpVMD...' })
// → SlackMessage[]

// Get a single message by timestamp
const message = await client.getMessage('C0ACZKTDDC0', '1234567890.123456')
// → SlackMessage | null

// Get all replies in a thread (parent message included as the first entry)
const replies = await client.getThreadReplies('C0ACZKTDDC0', '1234567890.123456')
const paginated = await client.getThreadReplies('C0ACZKTDDC0', '1234567890.123456', { limit: 100 })
// → SlackMessage[]

// Update a message (bot can only edit its own messages)
const edited = await client.updateMessage('C0ACZKTDDC0', '1234567890.123456', 'Updated text')
// → SlackMessage

// Delete a message (bot can only delete its own messages)
await client.deleteMessage('C0ACZKTDDC0', '1234567890.123456')

// Show a typing/status indicator in an AI Assistant thread (e.g. "Bot is typing...")
await client.setAssistantStatus('C0ACZKTDDC0', '1234567890.123456', 'is typing...')
await client.setAssistantStatus('C0ACZKTDDC0', '1234567890.123456', 'is analyzing your code...')

// Clear the status manually (status also auto-clears when the bot posts a message,
// or after a 2-minute timeout). Only works inside AI Assistant threads — requires `chat:write`.
await client.setAssistantStatus('C0ACZKTDDC0', '1234567890.123456', '')

// Add a reaction (emoji can be wrapped in colons or bare)
await client.addReaction('C0ACZKTDDC0', '1234567890.123456', 'thumbsup')
await client.addReaction('C0ACZKTDDC0', '1234567890.123456', ':white_check_mark:')

// Remove a reaction the bot added
await client.removeReaction('C0ACZKTDDC0', '1234567890.123456', 'thumbsup')

// List channels the bot can see (auto-paginates unless a `limit` is given)
const channels = await client.listChannels()
const firstPage = await client.listChannels({ limit: 50 })
const next = await client.listChannels({ limit: 50, cursor: 'dGVhbTpD...' })
// → SlackChannel[]

// Get a specific channel
const channel = await client.getChannelInfo('C0ACZKTDDC0')
// → SlackChannel { id, name, is_private, is_archived, created, creator, topic?, purpose? }

// Resolve a channel by ID or name — returns the channel ID
const id = await client.resolveChannel('C0ACZKTDDC0')
const sameId = await client.resolveChannel('#general')
const fromName = await client.resolveChannel('general')

// Join a public channel (required before posting in some workspaces)
await client.joinChannel('C0ACZKTDDC0')

// List workspace members (auto-paginates unless a `limit` is given)
const users = await client.listUsers()
const firstPage = await client.listUsers({ limit: 100 })
// → SlackUser[]

// Get a single user
const user = await client.getUserInfo('U012ABC3DE')
// → SlackUser { id, name, real_name, is_admin, is_owner, is_bot, is_app_user, profile? }

import { SlackBotClient, SlackBotListener } from 'agent-messenger/slackbot'

const client = await new SlackBotClient().login({ token: 'xoxb-...' })
const listener = new SlackBotListener(client, {
  appToken: process.env.SLACK_APP_TOKEN!, // xapp-...
})

listener.on('connected', (info) => {
  console.log(`Connected to Slack (app ${info.app_id})`)
})

listener.on('message', ({ ack, event }) => {
  ack()
  if (event.subtype || event.bot_id) return
  console.log(`#${event.channel} <${event.user}>: ${event.text}`)
})

listener.on('slash_commands', ({ ack, body }) => {
  ack({ text: `Got \`${body.command} ${body.text}\`` })
})

listener.on('error', (err) => console.error(err))

await listener.start() // opens the Socket Mode WebSocket
// listener.stop()      // clean shutdown

listener.on('message', ({ ack, event }) => {
  // Always ack first so Slack stops retrying. Do this even if you decide to
  // ignore the event — failure to ack causes duplicate deliveries.
  ack()
  // ...your work
})

// Slash commands and interactive components support a response payload that
// becomes the immediate user-visible reply (when accepts_response_payload is
// true on the envelope).
listener.on('slash_commands', ({ ack, body }) => {
  ack({ text: 'Working on it...' })
})

listener.on('interactive', ({ ack, body }) => {
  if (body.type === 'view_submission') {
    ack({ response_action: 'clear' })
  } else {
    ack()
  }
})

const listener = new SlackBotListener(client, {
  appToken: process.env.SLACK_APP_TOKEN!,
  debugReconnects: true,
})

import { SlackBotCredentialManager } from 'agent-messenger/slackbot'

const manager = new SlackBotCredentialManager()
// Custom path: new SlackBotCredentialManager('/custom/config/dir')

// Load full config from disk (returns defaults if file doesn't exist)
const config = await manager.load()
// → SlackBotConfig { current, workspaces }

// Save full config to disk (also enforces 0o600 permissions)
await manager.save(config)

// Get the credentials for the current bot, a specific bot ID, or
// "workspace_id/bot_id" to disambiguate a bot ID that exists in multiple
// workspaces.
const creds = await manager.getCredentials()
const specific = await manager.getCredentials('deploy')
const disambiguated = await manager.getCredentials('T0ABCDE/deploy')
// → SlackBotCredentials | null

// Store credentials for a bot (also marks it as the current bot)
await manager.setCredentials({
  token: 'xoxb-...',
  workspace_id: 'T0ABCDE',
  workspace_name: 'Acme Corp',
  bot_id: 'deploy',
  bot_name: 'Deploy Bot',
})

// Switch the active bot — accepts the same lookup formats as getCredentials
await manager.setCurrent('alerts')

// List all stored bots (across workspaces) with current marker
const bots = await manager.listAll()
// → Array<SlackBotCredentials & { is_current: boolean }>

// Remove a stored bot (drops the workspace too if it was the last bot in it)
await manager.removeBot('alerts')

// Clear all stored credentials
await manager.clearCredentials()

import type {
  SlackBotConfig,
  SlackBotCredentials,
  SlackBotListenerEventMap,
  SlackBotListenerOptions,
  SlackChannel,
  SlackFile,
  SlackMessage,
  SlackReaction,
  SlackSocketModeAck,
  SlackSocketModeAppMentionEvent,
  SlackSocketModeChannelEvent,
  SlackSocketModeDisconnectEnvelope,
  SlackSocketModeDisconnectReason,
  SlackSocketModeEnvelope,
  SlackSocketModeEvent,
  SlackSocketModeEventsApiArgs,
  SlackSocketModeEventsApiEnvelope,
  SlackSocketModeGenericEnvelope,
  SlackSocketModeGenericEvent,
  SlackSocketModeHelloEnvelope,
  SlackSocketModeInteractiveArgs,
  SlackSocketModeInteractiveEnvelope,
  SlackSocketModeMemberChannelEvent,
  SlackSocketModeMessageEvent,
  SlackSocketModeReactionEvent,
  SlackSocketModeSlashCommandArgs,
  SlackSocketModeSlashCommandEnvelope,
  SlackUser,
} from 'agent-messenger/slackbot'

import {
  SlackBotConfigSchema,
  SlackBotCredentialsSchema,
  SlackChannelSchema,
  SlackFileSchema,
  SlackMessageSchema,
  SlackReactionSchema,
  SlackUserSchema,
} from 'agent-messenger/slackbot'

import { SlackBotError } from 'agent-messenger/slackbot'

try {
  await client.postMessage('C0ACZKTDDC0', 'Hello')
} catch (err) {
  if (err instanceof SlackBotError && err.code === 'slack_webapi_rate_limited_error') {
    console.log(`Rate limited; retry after ${err.retryAfter}s`)
  }
}

import { SlackBotClient, SlackBotListener } from 'agent-messenger/slackbot'

const client = await new SlackBotClient().login()
const listener = new SlackBotListener(client, { appToken: process.env.SLACK_APP_TOKEN! })

listener.on('app_mention', async ({ ack, event }) => {
  ack()
  await client.postMessage(event.channel, `👋 Hi <@${event.user}>! How can I help?`, {
    thread_ts: event.thread_ts ?? event.ts,
  })
})

await listener.start()

import { SlackBotClient, SlackBotListener } from 'agent-messenger/slackbot'

const client = await new SlackBotClient().login()
const me = await client.testAuth()
const listener = new SlackBotListener(client, { appToken: process.env.SLACK_APP_TOKEN! })

const post = await client.postMessage('C0DEPLOY', '🚀 Deploy v2.1.0 to production?')
await client.addReaction('C0DEPLOY', post.ts, 'white_check_mark')
await client.addReaction('C0DEPLOY', post.ts, 'x')

listener.on('reaction_added', async ({ ack, event }) => {
  ack()
  if (event.item.channel !== 'C0DEPLOY' || event.item.ts !== post.ts) return
  if (event.user === me.user_id) return

  if (event.reaction === 'white_check_mark') {
    await client.updateMessage('C0DEPLOY', post.ts, '🚀 Deploy v2.1.0 — *approved*')
  } else if (event.reaction === 'x') {
    await client.updateMessage('C0DEPLOY', post.ts, '🚀 Deploy v2.1.0 — *rejected*')
  }
})

await listener.start()

import { SlackBotClient, SlackBotListener } from 'agent-messenger/slackbot'

const client = await new SlackBotClient().login()
const listener = new SlackBotListener(client, { appToken: process.env.SLACK_APP_TOKEN! })

listener.on('slash_commands', async ({ ack, body }) => {
  if (body.command !== '/deploy') {
    ack()
    return
  }

  // Reply immediately so Slack shows feedback to the user.
  ack({ text: `Queued deploy of \`${body.text}\`...` })

  // Then do the long-running work and post a follow-up.
  await runDeploy(body.text)
  await client.postMessage(body.channel_id, `✅ Deploy of \`${body.text}\` complete`)
})

await listener.start()

import { SlackBotClient, SlackBotListener } from 'agent-messenger/slackbot'

const client = await new SlackBotClient().login()
const listener = new SlackBotListener(client, { appToken: process.env.SLACK_APP_TOKEN! })

listener.on('interactive', async ({ ack, body }) => {
  ack()

  if (body.type !== 'block_actions') return
  const action = body.actions?.[0] as { action_id?: string; value?: string } | undefined
  if (action?.action_id !== 'approve_pr') return

  await client.postMessage(
    (body as { channel?: { id: string } }).channel!.id,
    `<@${body.user!.id}> approved PR ${action.value}`,
  )
})

await listener.start()

import { SlackBotClient, SlackBotListener } from 'agent-messenger/slackbot'

const client = await new SlackBotClient().login()
const listener = new SlackBotListener(client, { appToken: process.env.SLACK_APP_TOKEN! })

listener.on('message', async ({ ack, event }) => {
  ack()
  // Only handle messages inside an AI Assistant thread (skip top-level posts and bot echoes).
  if (!event.thread_ts || event.subtype === 'bot_message') return

  // Show "Bot is typing..." while the agent thinks.
  await client.setAssistantStatus(event.channel, event.thread_ts, 'is typing...')

  try {
    const reply = await runAgent(event.text ?? '')
    // Posting a reply auto-clears the status indicator.
    await client.postMessage(event.channel, reply, { thread_ts: event.thread_ts })
  } catch (err) {
    // Clear the status on failure so it doesn't linger until the 2-minute timeout.
    await client.setAssistantStatus(event.channel, event.thread_ts, '')
    throw err
  }
})

await listener.start()

import { SlackBotClient } from 'agent-messenger/slackbot'

const client = await new SlackBotClient().login()
const channel = 'C0BUILDS'

const start = await client.postMessage(channel, `🛠️ Build #${runId} started`)
await client.addReaction(channel, start.ts, 'hourglass_flowing_sand')

try {
  await runBuild()
  await client.removeReaction(channel, start.ts, 'hourglass_flowing_sand')
  await client.addReaction(channel, start.ts, 'white_check_mark')
  await client.postMessage(channel, `✅ Build #${runId} succeeded`, { thread_ts: start.ts })
} catch (err) {
  await client.removeReaction(channel, start.ts, 'hourglass_flowing_sand')
  await client.addReaction(channel, start.ts, 'x')
  await client.postMessage(channel, `❌ Build #${runId} failed: ${(err as Error).message}`, {
    thread_ts: start.ts,
  })
  throw err
}

import { SlackBotClient, SlackBotCredentialManager } from 'agent-messenger/slackbot'

const manager = new SlackBotCredentialManager()

// Two bots in the same workspace
await manager.setCredentials({
  token: 'xoxb-DEPLOY',
  workspace_id: 'T0ACME',
  workspace_name: 'Acme Corp',
  bot_id: 'deploy',
  bot_name: 'Deploy Bot',
})
await manager.setCredentials({
  token: 'xoxb-ALERTS',
  workspace_id: 'T0ACME',
  workspace_name: 'Acme Corp',
  bot_id: 'alerts',
  bot_name: 'Alerts Bot',
})

// A bot in a second workspace, with the same bot_id
await manager.setCredentials({
  token: 'xoxb-DEPLOY-2',
  workspace_id: 'T0WIDGET',
  workspace_name: 'Widget Co',
  bot_id: 'deploy',
  bot_name: 'Widget Deploy Bot',
})

// Switch using "workspace_id/bot_id" to disambiguate
await manager.setCurrent('T0WIDGET/deploy')
const creds = await manager.getCredentials()
const client = await new SlackBotClient().login({ token: creds!.token })

await client.postMessage('C0RELEASES', '🚀 Widget Co release v3.0.0 deployed')