Chat Operations

/**
 * Post a message to a conversation
 * @param options - Message parameters
 * @returns Promise resolving to message details
 */
chat.postMessage(options: ChatPostMessageArguments): Promise<ChatPostMessageResponse>;

interface ChatPostMessageArguments {
  /** Channel, private group, or DM channel to send message to */
  channel: string;
  /** Text of the message to send (required if no blocks/attachments) */
  text?: string;
  /** Post as the authed user instead of as a bot */
  as_user?: boolean;
  /** Structured message attachments (legacy) */
  attachments?: MessageAttachment[];
  /** Structured blocks for rich message layout */
  blocks?: Block[];
  /** Emoji to use as the icon for this message */
  icon_emoji?: string;
  /** URL to an image to use as the icon for this message */
  icon_url?: string;
  /** How this message should be linked to other messages */
  link_names?: boolean;
  /** Additional message metadata */
  metadata?: {
    event_type: string;
    event_payload: Record<string, any>;
  };
  /** Disable Slack markup parsing */
  mrkdwn?: boolean;
  /** Change how messages are treated */
  parse?: 'full' | 'none';
  /** Used with thread_ts to make reply visible to channel */
  reply_broadcast?: boolean;
  /** Thread timestamp to reply to a specific message */
  thread_ts?: string;
  /** Unfurl primarily text-based content */
  unfurl_links?: boolean;
  /** Unfurl media content */  
  unfurl_media?: boolean;
  /** Set your bot's user name */
  username?: string;
}

import { WebClient } from "@slack/web-api";

const web = new WebClient(token);

// Simple text message
const result = await web.chat.postMessage({
  channel: '#general',
  text: 'Hello, world!'
});

// Message with formatting
await web.chat.postMessage({
  channel: 'C1234567890',
  text: 'Check out this *bold* text and ~strikethrough~',
  unfurl_links: false
});

// Thread reply
await web.chat.postMessage({
  channel: '#general',
  text: 'This is a reply',
  thread_ts: '1234567890.123456'
});

// Message with blocks (rich formatting)
await web.chat.postMessage({
  channel: '#general',
  blocks: [
    {
      type: 'section',
      text: {
        type: 'mrkdwn',
        text: '*Welcome to the team!* 🎉'
      }
    },
    {
      type: 'actions',
      elements: [
        {
          type: 'button',
          text: { type: 'plain_text', text: 'Get Started' },
          action_id: 'get_started_button'
        }
      ]
    }
  ]
});

/**
 * Update a message
 * @param options - Update parameters
 * @returns Promise resolving to updated message details
 */
chat.update(options: ChatUpdateArguments): Promise<ChatUpdateResponse>;

interface ChatUpdateArguments {
  /** Channel containing the message to update */
  channel: string;
  /** Timestamp of the message to update */
  ts: string;
  /** New text for the update */
  text?: string;
  /** Post as the authed user instead of as a bot */
  as_user?: boolean;
  /** Updated structured attachments */
  attachments?: MessageAttachment[];
  /** Updated structured blocks */
  blocks?: Block[];
  /** How this message should be linked to other messages */
  link_names?: boolean;
  /** Additional message metadata */
  metadata?: {
    event_type: string;
    event_payload: Record<string, any>;
  };
  /** Change how messages are treated */
  parse?: 'full' | 'none';
  /** Broadcast thread reply to channel */
  reply_broadcast?: boolean;
}

// Update message text
const updated = await web.chat.update({
  channel: '#general',
  ts: '1234567890.123456',
  text: 'Updated message content'
});

// Update with new blocks
await web.chat.update({
  channel: 'C1234567890',
  ts: '1234567890.123456',
  blocks: [
    {
      type: 'section',
      text: {
        type: 'mrkdwn',
        text: '*Updated:* Task completed ✅'
      }
    }
  ]
});

/**
 * Delete a message
 * @param options - Delete parameters
 * @returns Promise resolving to deletion confirmation
 */
chat.delete(options: ChatDeleteArguments): Promise<ChatDeleteResponse>;

interface ChatDeleteArguments {
  /** Channel containing the message to delete */
  channel: string;
  /** Timestamp of the message to delete */
  ts: string;
  /** Pass true to delete as the authed user */
  as_user?: boolean;
}

// Delete a message
const result = await web.chat.delete({
  channel: '#general',
  ts: '1234567890.123456'
});

if (result.ok) {
  console.log('Message deleted successfully');
}

/**
 * Schedule a message to be sent later
 * @param options - Scheduling parameters
 * @returns Promise resolving to scheduled message details
 */
chat.scheduleMessage(options: ChatScheduleMessageArguments): Promise<ChatScheduleMessageResponse>;

interface ChatScheduleMessageArguments {
  /** Channel to send the scheduled message to */
  channel: string;
  /** Unix timestamp when the message should be sent */
  post_at: number;
  /** Text of the message */
  text?: string;
  /** Structured attachments */
  attachments?: MessageAttachment[];
  /** Structured blocks */
  blocks?: Block[];
  /** Pass true to post as the authed user */
  as_user?: boolean;
  /** How this message should be linked to other messages */
  link_names?: boolean;
  /** Change how messages are treated */
  parse?: 'full' | 'none';
  /** Thread timestamp to reply to a message */
  thread_ts?: string;
  /** Unfurl links in message text */
  unfurl_links?: boolean;
  /** Unfurl media in message */
  unfurl_media?: boolean;
}

// Schedule message for tomorrow at 9 AM
const tomorrow9AM = Math.floor(Date.now() / 1000) + (24 * 60 * 60) + (9 * 60 * 60);

const scheduled = await web.chat.scheduleMessage({
  channel: '#general',
  text: 'Good morning! Daily standup in 30 minutes.',
  post_at: tomorrow9AM
});

console.log('Scheduled message ID:', scheduled.scheduled_message_id);

/**
 * Send an ephemeral message to a user in a channel
 * @param options - Ephemeral message parameters
 * @returns Promise resolving to message details
 */
chat.postEphemeral(options: ChatPostEphemeralArguments): Promise<ChatPostEphemeralResponse>;

interface ChatPostEphemeralArguments {
  /** Channel to send the ephemeral message in */
  channel: string;
  /** User who will receive the ephemeral message */
  user: string;
  /** Text of the message */
  text?: string;
  /** Structured attachments */
  attachments?: MessageAttachment[];
  /** Structured blocks */
  blocks?: Block[];
  /** Pass true to post as the authed user */
  as_user?: boolean;
  /** Emoji to use as icon */
  icon_emoji?: string;
  /** URL to image for icon */
  icon_url?: string;
  /** Link names in the message */
  link_names?: boolean;
  /** Change how messages are treated */
  parse?: 'full' | 'none';
  /** Thread timestamp to reply to */
  thread_ts?: string;
  /** Set bot's username */
  username?: string;
}

// Send private message visible only to specific user
await web.chat.postEphemeral({
  channel: '#general',
  user: 'U1234567890',
  text: 'This message is only visible to you!'
});

// Ephemeral message with blocks
await web.chat.postEphemeral({
  channel: '#general',
  user: 'U1234567890',
  blocks: [
    {
      type: 'section',
      text: {
        type: 'mrkdwn',
        text: ':warning: *Private reminder:* Your task deadline is approaching.'
      }
    }
  ]
});

/**
 * Get a permalink URL for a message
 * @param options - Permalink parameters
 * @returns Promise resolving to permalink details
 */
chat.getPermalink(options: ChatGetPermalinkArguments): Promise<ChatGetPermalinkResponse>;

interface ChatGetPermalinkArguments {
  /** Channel containing the message */
  channel: string;
  /** Timestamp of the message */
  message_ts: string;
}

const permalink = await web.chat.getPermalink({
  channel: '#general',
  message_ts: '1234567890.123456'
});

console.log('Message permalink:', permalink.permalink);
// https://example.slack.com/archives/C1234567890/p1234567890123456

/**
 * List scheduled messages
 * @param options - List parameters
 * @returns Promise resolving to scheduled messages list
 */
chat.scheduledMessages.list(options?: ChatScheduledMessagesListArguments): Promise<ChatScheduledMessagesListResponse>;

/**
 * Delete a scheduled message
 * @param options - Delete parameters  
 * @returns Promise resolving to deletion confirmation
 */
chat.deleteScheduledMessage(options: ChatDeleteScheduledMessageArguments): Promise<ChatDeleteScheduledMessageResponse>;

interface ChatDeleteScheduledMessageArguments {
  /** Channel containing the scheduled message */
  channel: string;
  /** ID of the scheduled message to delete */
  scheduled_message_id: string;
  /** Pass true to delete as the authed user */
  as_user?: boolean;
}

// List all scheduled messages
const scheduledMessages = await web.chat.scheduledMessages.list();

for (const message of scheduledMessages.scheduled_messages) {
  console.log(`Message "${message.text}" scheduled for ${new Date(message.post_at * 1000)}`);
}

// Delete a scheduled message
await web.chat.deleteScheduledMessage({
  channel: '#general',
  scheduled_message_id: 'Q1234567890'
});

interface ChatPostMessageResponse extends WebAPICallResult {
  channel: string;
  ts: string;
  message: {
    text: string;
    user: string;
    ts: string;
    team: string;
    bot_id?: string;
    app_id?: string;
  };
}

interface MessageAttachment {
  color?: string;
  fallback?: string;
  title?: string;
  title_link?: string;
  text?: string;
  fields?: { title: string; value: string; short?: boolean }[];
  footer?: string;
  footer_icon?: string;
  ts?: number;
}

interface Block {
  type: string;
  block_id?: string;
  [key: string]: any;
}