Conversation Management

/**
 * Create a new conversation (channel or group)
 * @param options - Creation parameters
 * @returns Promise resolving to new conversation details
 */
conversations.create(options: ConversationsCreateArguments): Promise<ConversationsCreateResponse>;

interface ConversationsCreateArguments {
  /** Name of the conversation to create */
  name: string;
  /** Whether the conversation should be private */
  is_private?: boolean;
  /** Team ID to create the conversation in (Enterprise Grid) */
  team_id?: string;
}

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

const web = new WebClient(token);

// Create public channel
const publicChannel = await web.conversations.create({
  name: 'project-alpha',
  is_private: false
});

// Create private channel  
const privateChannel = await web.conversations.create({
  name: 'confidential-planning',
  is_private: true
});

console.log('Created channel:', publicChannel.channel.id);

/**
 * List conversations the user has access to
 * @param options - List parameters
 * @returns Promise resolving to conversations list
 */
conversations.list(options?: ConversationsListArguments): Promise<ConversationsListResponse>;

interface ConversationsListArguments {
  /** Paginate through collections of data by cursor */
  cursor?: string;
  /** Set to true to exclude archived channels */
  exclude_archived?: boolean;
  /** Maximum number of conversations to return (1-1000, default: 100) */
  limit?: number;
  /** Mix and match conversation types (public_channel, private_channel, mpim, im) */
  types?: string;
  /** Team ID (Enterprise Grid) */
  team_id?: string;
}

// List all public channels
const publicChannels = await web.conversations.list({
  types: 'public_channel',
  exclude_archived: true,
  limit: 200
});

// List all conversation types
const allConversations = await web.conversations.list({
  types: 'public_channel,private_channel,mpim,im'
});

// Paginate through all channels
let cursor;
const allChannels = [];
do {
  const result = await web.conversations.list({
    types: 'public_channel,private_channel',
    cursor,
    limit: 100
  });
  
  allChannels.push(...result.channels);
  cursor = result.response_metadata?.next_cursor;
} while (cursor);

/**
 * Get information about a conversation
 * @param options - Info parameters
 * @returns Promise resolving to conversation details
 */
conversations.info(options: ConversationsInfoArguments): Promise<ConversationsInfoResponse>;

interface ConversationsInfoArguments {
  /** Conversation ID to get info about */
  channel: string;
  /** Include number of members in the response */
  include_num_members?: boolean;
  /** Include locale information */
  include_locale?: boolean;
}

// Get basic channel info
const channelInfo = await web.conversations.info({
  channel: 'C1234567890'
});

console.log('Channel name:', channelInfo.channel.name);
console.log('Is archived:', channelInfo.channel.is_archived);

// Get channel info with member count
const detailedInfo = await web.conversations.info({
  channel: 'C1234567890',
  include_num_members: true
});

console.log('Member count:', detailedInfo.channel.num_members);

/**
 * Invite users to a conversation
 * @param options - Invitation parameters
 * @returns Promise resolving to invitation result
 */
conversations.invite(options: ConversationsInviteArguments): Promise<ConversationsInviteResponse>;

/**
 * Remove a user from a conversation
 * @param options - Removal parameters
 * @returns Promise resolving to removal result
 */
conversations.kick(options: ConversationsKickArguments): Promise<ConversationsKickResponse>;

/**
 * List members of a conversation
 * @param options - List parameters
 * @returns Promise resolving to members list
 */
conversations.members(options: ConversationsMembersArguments): Promise<ConversationsMembersResponse>;

interface ConversationsInviteArguments {
  /** Conversation to invite users to */
  channel: string;
  /** Comma-separated list of user IDs */
  users: string;
}

interface ConversationsKickArguments {
  /** Conversation to remove user from */
  channel: string;
  /** User ID to remove */
  user: string;
}

interface ConversationsMembersArguments {
  /** Conversation to list members for */
  channel: string;
  /** Cursor for pagination */
  cursor?: string;
  /** Maximum number of members to return */
  limit?: number;
}

// Invite users to channel
await web.conversations.invite({
  channel: 'C1234567890',
  users: 'U1111111111,U2222222222,U3333333333'
});

// Remove user from channel
await web.conversations.kick({
  channel: 'C1234567890',
  user: 'U1111111111'
});

// List all channel members
const members = [];
for await (const page of web.paginate('conversations.members', {
  channel: 'C1234567890'
})) {
  members.push(...page.members);
}

console.log(`Channel has ${members.length} members`);

/**
 * Join an existing conversation
 * @param options - Join parameters
 * @returns Promise resolving to join result
 */
conversations.join(options: ConversationsJoinArguments): Promise<ConversationsJoinResponse>;

/**
 * Leave a conversation
 * @param options - Leave parameters
 * @returns Promise resolving to leave result
 */
conversations.leave(options: ConversationsLeaveArguments): Promise<ConversationsLeaveResponse>;

interface ConversationsJoinArguments {
  /** Conversation to join */
  channel: string;
}

interface ConversationsLeaveArguments {
  /** Conversation to leave */
  channel: string;
}

// Join a public channel
await web.conversations.join({
  channel: 'C1234567890'
});

// Leave a conversation
await web.conversations.leave({
  channel: 'C1234567890'
});

/**
 * Archive a conversation
 * @param options - Archive parameters
 * @returns Promise resolving to archive result
 */
conversations.archive(options: ConversationsArchiveArguments): Promise<ConversationsArchiveResponse>;

/**
 * Unarchive a conversation
 * @param options - Unarchive parameters
 * @returns Promise resolving to unarchive result  
 */
conversations.unarchive(options: ConversationsUnarchiveArguments): Promise<ConversationsUnarchiveResponse>;

interface ConversationsArchiveArguments {
  /** Conversation to archive */
  channel: string;
}

interface ConversationsUnarchiveArguments {
  /** Conversation to unarchive */
  channel: string;
}

// Archive a channel
await web.conversations.archive({
  channel: 'C1234567890'
});

// Unarchive a channel
await web.conversations.unarchive({
  channel: 'C1234567890'
});

/**
 * Set the topic of a conversation
 * @param options - Topic parameters
 * @returns Promise resolving to topic update result
 */
conversations.setTopic(options: ConversationsSetTopicArguments): Promise<ConversationsSetTopicResponse>;

/**
 * Set the purpose of a conversation
 * @param options - Purpose parameters
 * @returns Promise resolving to purpose update result
 */
conversations.setPurpose(options: ConversationsSetPurposeArguments): Promise<ConversationsSetPurposeResponse>;

/**
 * Rename a conversation
 * @param options - Rename parameters
 * @returns Promise resolving to rename result
 */
conversations.rename(options: ConversationsRenameArguments): Promise<ConversationsRenameResponse>;

interface ConversationsSetTopicArguments {
  /** Conversation to set topic for */
  channel: string;
  /** New topic text */
  topic: string;
}

interface ConversationsSetPurposeArguments {
  /** Conversation to set purpose for */
  channel: string;
  /** New purpose text */
  purpose: string;
}

interface ConversationsRenameArguments {
  /** Conversation to rename */
  channel: string;
  /** New name for conversation */
  name: string;
}

// Set channel topic
await web.conversations.setTopic({
  channel: 'C1234567890',
  topic: 'Weekly team updates and announcements'
});

// Set channel purpose
await web.conversations.setPurpose({
  channel: 'C1234567890',
  purpose: 'Discuss project alpha development progress'
});

// Rename channel
await web.conversations.rename({
  channel: 'C1234567890',
  name: 'project-alpha-v2'
});

/**
 * Get conversation history
 * @param options - History parameters
 * @returns Promise resolving to message history
 */
conversations.history(options: ConversationsHistoryArguments): Promise<ConversationsHistoryResponse>;

/**
 * Get replies to a message
 * @param options - Replies parameters
 * @returns Promise resolving to thread replies
 */
conversations.replies(options: ConversationsRepliesArguments): Promise<ConversationsRepliesResponse>;

interface ConversationsHistoryArguments {
  /** Conversation to fetch history for */
  channel: string;
  /** Cursor for pagination */
  cursor?: string;
  /** Include all metadata associated with this channel */
  include_all_metadata?: boolean;
  /** Return messages with oldest timestamp in list (default: false) */
  inclusive?: boolean;
  /** End of time range of messages to include */
  latest?: string;
  /** Maximum number of messages to return (1-1000, default: 100) */
  limit?: number;
  /** Start of time range of messages to include */
  oldest?: string;
}

interface ConversationsRepliesArguments {
  /** Conversation to fetch thread from */
  channel: string;
  /** Thread timestamp */
  ts: string;
  /** Cursor for pagination */
  cursor?: string;
  /** Return messages with oldest timestamp in list */
  inclusive?: boolean;
  /** End of time range */
  latest?: string;
  /** Maximum number of messages to return */
  limit?: number;
  /** Start of time range */
  oldest?: string;
}

// Get recent messages
const history = await web.conversations.history({
  channel: 'C1234567890',
  limit: 50
});

console.log(`Retrieved ${history.messages.length} messages`);

// Get messages from specific time range
const todayStart = Math.floor(new Date().setHours(0, 0, 0, 0) / 1000);
const todayMessages = await web.conversations.history({
  channel: 'C1234567890',
  oldest: todayStart.toString(),
  limit: 1000
});

// Get thread replies
const threadReplies = await web.conversations.replies({
  channel: 'C1234567890',
  ts: '1234567890.123456'
});

console.log(`Thread has ${threadReplies.messages.length} replies`);

/**
 * Open a direct message conversation
 * @param options - Open parameters
 * @returns Promise resolving to DM channel info
 */
conversations.open(options: ConversationsOpenArguments): Promise<ConversationsOpenResponse>;

/**
 * Close a direct message conversation
 * @param options - Close parameters
 * @returns Promise resolving to close result
 */
conversations.close(options: ConversationsCloseArguments): Promise<ConversationsCloseResponse>;

interface ConversationsOpenArguments {
  /** User ID to open DM with */
  users?: string;
  /** Conversation ID to reopen */
  channel?: string;
  /** Set to true to prevent creating a new conversation */
  prevent_creation?: boolean;
  /** Set to true to return existing conversation */
  return_im?: boolean;
}

interface ConversationsCloseArguments {
  /** Conversation to close */
  channel: string;
}

// Open DM with single user
const dm = await web.conversations.open({
  users: 'U1234567890'
});

console.log('DM channel ID:', dm.channel.id);

// Open group DM with multiple users
const groupDM = await web.conversations.open({
  users: 'U1234567890,U2222222222,U3333333333'
});

// Close a DM
await web.conversations.close({
  channel: 'D1234567890'
});

interface ConversationsCreateResponse extends WebAPICallResult {
  channel: {
    id: string;
    name: string;
    is_channel: boolean;
    is_group: boolean;
    is_im: boolean;
    is_mpim: boolean;
    is_private: boolean;
    created: number;
    creator: string;
    is_archived: boolean;
    is_general: boolean;
    unlinked: number;
    name_normalized: string;
    is_shared: boolean;
    is_org_shared: boolean;
    context_team_id: string;
    updated: number;
    parent_conversation?: string;
    pending_shared?: string[];
    pending_connected_team_ids?: string[];
    is_pending_ext_shared?: boolean;
  };
}

interface ConversationsListResponse extends WebAPICallResult {
  channels: Conversation[];
  response_metadata?: {
    next_cursor?: string;
  };
}

interface Conversation {
  id: string;
  name?: string;
  is_channel: boolean;
  is_group: boolean;
  is_im: boolean;
  is_mpim: boolean;
  is_private: boolean;
  created: number;
  creator?: string;
  is_archived: boolean;
  is_general?: boolean;
  unlinked?: number;
  name_normalized?: string;
  is_shared: boolean;
  is_org_shared: boolean;
  context_team_id?: string;
  updated: number;
  topic?: {
    value: string;
    creator: string;
    last_set: number;
  };
  purpose?: {
    value: string;
    creator: string;
    last_set: number;
  };
  num_members?: number;
}