@ingestkorea/client-slack

Description

INGESTKOREA SDK - Slack Client for Node.js.

INGESTKOREA SDK - Slack Client for Node.js is a lightweight library that contains only the essential features frequently used in Slack bots.

This SDK performs tasks such as the following automatically.

• Authentication using an Bot User OAuth Token
• Retry requests
• Handle error responses

Installing

npm install @ingestkorea/client-slack

Getting Started

Pre-requisites

Slack

• Create the app in your workspace.
• Add the chat:write scope to the Bot Token Scopes under the OAuth & Permissions category.
• Generate a OAuth Token under the OAuth & Permissions category. (A token is automatically generated when you installed the app to your workspace)
• Enter /invite @YOUR_APP_NAME in the channel where you want to add the bot.

Node.js

• Use TypeScript v5.x

• Includes the TypeScript definitions for node.

  npm install -D @types/node # save dev mode

Support Methods

• SendMessage
• DeleteMessage
• UpdateMessage
• SendScheduleMessage
• DeleteScheduledMessage
• ListScheduledMessages

Import

The INGESTKOREA SDK - Slack Client is modulized by client and commands.

To send a request, you only need to import the SlackClient and the commands you need, for example SendMessageCommand:

import { SlackClient, SendMessageCommand } from "@ingestkorea/client-slack";

Usage

To send a request, you:

• Initiate client with configuration.
• Initiate command with input parameters.
• Call send operation on client with command object as input.

import { SendMessageCommandInput } from "@ingestkorea/client-slack";

// a client can be shared by different commands.
const client = new SlackClient({
  credentials: {
    token: "YOUR_OAuth_TOKEN", // required // xoxb-xxxxxxxx
    channel: "YOUR_CHANNEL_ID", // required
  },
});

const params: SendMessageCommandInput = {
  text: "Hello client-slack : " + new Date().toISOString(), // required
  channel: "YOUR_CHANNEL_ID", // optional // this channelId overrides SlackClient config
};

const command = new SendMessageCommand(params);

SendMessage (with Blocks)

These are the currently supported Blocks, and more will be added in the future.

• HeaderBlock
• DividerBlock
• SectionBlock
• ContextBlock

If you need more information about Blocks, please visit Slack Blocks Reference

import { SendMessageCommand, SendMessageCommandInput } from "@ingestkorea/client-slack";

const params: SendMessageCommandInput = {
  text: "Hello client-slack",
  blocks: [
    {
      type: "header",
      text: { type: "plain_text", text: "HeaderBlock" },
    },
    { type: "divider" },
    {
      type: "section",
      text: { type: "mrkdwn", text: "*SectionBlock-01*" },
    },
    {
      type: "section",
      text: { type: "mrkdwn", text: "_SectionBlock-02_" },
      fields: [
        { type: "mrkdwn", text: "*Region:*\n ap-northeast-2" },
        { type: "mrkdwn", text: `*Date:*\n ${new Date().toISOString()}` },
      ],
    },
  ],
};

const command = new SendMessageCommand(params);

DeleteMessage

• If you provide the channel ID as an input to the command object, it will override the SlackClient configuration.

import { DeleteMessageCommand, DeleteMessageCommandInput } from "@ingestkorea/client-slack";

const params: DeleteMessageCommandInput = {
  ts: "1234567890.123456", // required
};

const command = new DeleteMessageCommand(params);

UpdateMessage

• If you provide the channel ID as an input to the command object, it will override the SlackClient configuration.

import { UpdateMessageCommand, UpdateMessageCommandInput } from "@ingestkorea/client-slack";

const params: UpdateMessageCommandInput = {
  ts: "1234567890.123456", // required
  text: "Hello client-slack", // required
};

const command = new UpdateMessageCommand(params);

SendScheduleMessage

Usage info

• SendScheduleMessageCommand is an extension of SendMessageCommand.
• post_at type must be in UTC string format, such as 2025-02-15T12:35:17Z or 2025-02-15T12:35:17.456Z.
• post_at must differ from the current time by at least 30 seconds.
• You can only delete a scheduled message if post_at differs from request_time by at least 10 minutes.
• If you provide the channel ID as an input to the command object, it will override the SlackClient configuration.

import { SendScheduleMessageCommand, SendScheduleMessageCommandInput } from "@ingestkorea/client-slack";

const params: SendScheduleMessageCommandInput = {
  post_at: "2025-02-15T12:35:17.456Z", // required
  text: "Hello client-slack", // required
};

const command = new SendScheduleMessageCommand(params);

DeleteScheduledMessage

Usage info

• You can only delete a scheduled message if post_at differs from request_time by at least 10 minutes.
• If you provide the channel ID as an input to the command object, it will override the SlackClient configuration.

import { DeleteScheduledMessageCommand, DeleteScheduledMessageCommandInput } from "@ingestkorea/client-slack";

const params: DeleteScheduledMessageCommandInput = {
  scheduled_message_id: "xxxxx", // required
};

const command = new DeleteScheduledMessageCommand(params);

ListScheduledMessages

Usage info

• latest or oldest params type must be in UTC string format, such as 2025-02-15T12:35:17Z or 2025-02-15T12:35:17.456Z.
• If you provide the channel ID as an input to the command object, it will override the SlackClient configuration.
• The results are sorted in ascending order by post_at.

import { ListScheduledMessagesCommand, ListScheduledMessagesCommandInput } from "@ingestkorea/client-slack";

const params: ListScheduledMessagesCommandInput = {
  oldest: "2025-02-20T12:35:17.456Z", // optional // default: current
  latest: "2025-02-27T12:35:17.456Z", // optional // default: current + 7 days
  limit: 1 ~ 100, // optional // default: 20 // max: 100
  cursor: "xxxxx", // optional
  team_id: "xxxx", // optional
};

const command = new ListScheduledMessagesCommand(params);

Async/await

We recommend using await operator to wait for the promise returned by send operation as follows:

(async () => {
  const start = process.hrtime.bigint();
  try {
    // a client can be shared by different commands.
    const data = await client.send(command);
    console.dir(data, { depth: 5 });
  } catch (err) {
    console.log(err);
  } finally {
    let end = process.hrtime.bigint();
    let duration = Number(end - start) / 1000000;
    console.log("duration: " + duration + "ms");
  }
})();

Promises

• You can also use Promise chaining to execute send operation.
• Promises can also be called using .catch() and .finally() as follows:

const start = process.hrtime.bigint();

client
  .send(command)
  .then((data) => {
    console.dir(data, { depth: 5 });
  })
  .catch((err) => {
    console.log(err);
  })
  .finally(() => {
    let end = process.hrtime.bigint();
    let duration = Number(end - start) / 1000000;
    console.log("duration: " + duration + "ms");
  });

Getting Help

We use the GitHub issues for tracking bugs and feature requests.

If it turns out that you may have found a bug, please open an issue.

License

This SDK is distributed under the MIT License, see LICENSE for more information.

Client Commands

SendMessage

| Arguments | Type | Required | Description | | --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | | text | string | true | Describe the content of the message. When blocks are included, text will be used as fallback text for notifications only. | | channel | string | false | This channelId overrides SlackClient config. | | blocks | object[] | false | Array of SupportBlocks. | | thread_ts | string | false | Provide another message's ts value to make this message a reply. | | mrkdwn | boolean | false | Disable Slack markup parsing by setting to false. Enabled by default. |

DeleteMessage

| Arguments | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------- | | ts | string | true | Timestamp of the message to be deleted. | | channel | string | false | This channelId overrides SlackClient config |

UpdateMessage

| Arguments | Type | Required | Description | | --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | | ts | string | true | Timestamp of the message to be updated. | | text | string | true | Describe the content of the message. When blocks are included, text will be used as fallback text for notifications only. | | channel | string | false | This channelId overrides SlackClient config. | | blocks | object[] | false | Array of SupportBlocks. |

SendScheduleMessage

| Arguments | Type | Required | Description | | --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | | post_at | string | true | UTC ISO8601 format representing the future time the message should post to Slack. (ex.2025-02-20T12:35:17.456Z) | | text | string | true | Describe the content of the message. When blocks are included, text will be used as fallback text for notifications only. | | channel | string | false | This channelId overrides SlackClient config | | blocks | object[] | false | Array of SupportBlocks. | | thread_ts | string | false | Provide another message's ts value to make this message a reply. |

DeleteScheduledMessage

| Arguments | Type | Required | Description | | -------------------- | ------ | -------- | ------------------------------------------------------------------------------------------- | | scheduled_message_id | string | true | scheduled_message_id returned from call to SendScheduleMessage or ListScheduledMessages | | channel | string | false | This channelId overrides SlackClient config |

ListScheduledMessages

| Arguments | Type | Required | Description | | --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | channel | string | false | This channelId overrides SlackClient config | | cursor | string | false | For pagination | | oldest | string | false | UTC ISO8601 format of the oldest value in the time range. default: current. (ex.2025-02-20T12:35:17.456Z) | | latest | string | false | UTC ISO8601 format of the latest value in the time range. default: current + 7 days. (ex.2025-02-27T12:35:17.456Z) | | limit | integer | false | Maximum number of original entries to return. default: 20. max: 100 | | team_id | string | false | Encoded team id to list channels in, required if org token is used |