Skip to content

Latest commit

 

History

History
 
 

messaging-api-slack

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
src
src
 
 
README.md
README.md
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 

README.md

messaging-api-slack

Messaging API client for Slack

Slack

Table of Contents

Installation

npm i --save messaging-api-slack

or

yarn add messaging-api-slack

OAuth Client

Usage

Get your bot user OAuth access token by setup OAuth & Permissions function to your app or check the Using OAuth 2.0 document.

const { SlackOAuthClient } = require('messaging-api-slack');

// get access token by setup OAuth & Permissions function to your app.
// https://api.slack.com/docs/oauth
const client = SlackOAuthClient.connect(
  'xoxb-000000000000-xxxxxxxxxxxxxxxxxxxxxxxx'
);

Error Handling

messaging-api-slack uses axios as HTTP client. We use axios-error package to wrap API error instances for better formatting error messages. Directly console.log on the error instance will return formatted message. If you'd like to get the axios request, response, or config, you can still get them via those keys on the error instance.

client.callMethod(method, body).catch(error => {
  console.log(error); // formatted error message
  console.log(error.stack); // error stack trace
  console.log(error.config); // axios request config
  console.log(error.request); // HTTP request
  console.log(error.response); // HTTP response
});

API Reference

All methods return a Promise.


Call available methods

callMethod(method, body) - Official docs

Calling any API methods which follow slack calling conventions.

Param Type Description
method String One of API Methods
body Object Body that the method needs.

Example:

client.callMethod('chat.postMessage', { channel: 'C8763', text: 'Hello!' });

Chat API

postMessage(channel, message [, options]) - Official docs

Sends a message to a channel.

Param Type Description
channel String Channel, private group, or IM channel to send message to. Can be an encoded ID, or a name.
message String | Object The message to be sent, can be text message or attachment message.
options Object Other optional parameters.
options.accessToken String Custom access token of the request.

Example:

client.postMessage('C8763', { text: 'Hello!' });
client.postMessage('C8763', { attachments: [someAttachments] });
client.postMessage('C8763', 'Hello!');
client.postMessage('C8763', 'Hello!', { as_user: true });

If you send message with attachments, messaging-api-slack will automatically stringify the attachments field for you.

client.postMessage(
  'C8763',
  {
    text: 'Hello!',
    attachments: [
      {
        text: 'Choose a game to play',
        fallback: 'You are unable to choose a game',
        callback_id: 'wopr_game',
        color: '#3AA3E3',
        attachment_type: 'default',
        actions: [
          {
            name: 'game',
            text: 'Chess',
            type: 'button',
            value: 'chess',
          },
        ],
      },
    ],
  },
  {
    as_user: true,
  }
);

postEphemeral(channel, user, message [, options]) - Official docs

Sends an ephemeral message to a user in a channel.

Param Type Description
channel String Channel, private group, or IM channel to send message to. Can be an encoded ID, or a name.
user String id of the user who will receive the ephemeral message. The user should be in the channel specified by the channel argument.
message String | Object The message to be sent, can be text message or attachment message.
options Object Other optional parameters.
options.accessToken String Custom access token of the request.

Example:

client.postEphemeral('C8763', 'U56781234', { text: 'Hello!' });
client.postEphemeral('C8763', 'U56781234', { attachments: [someAttachments] });
client.postEphemeral('C8763', 'U56781234', 'Hello!');
client.postEphemeral('C8763', 'U56781234', 'Hello!', { as_user: true });

Users API

getUserList(options?) - Official docs

Lists all users in a Slack team.

Param Type Description
options Object Other optional parameters.
options.cursor String Paginate through collections of data by setting the cursor parameter to a next_cursor attribute returned by a previous request's response_metadata.
options.accessToken String Custom access token of the request.

Example:

client.getUserList({ cursor }).then(res => {
  console.log(res);
  // {
  //   members: [
  //     { ... },
  //     { ... },
  //   ],
  //   next: 'abcdefg',
  // }
});

getAllUserList(options?) - Official docs

Recursively lists all users in a Slack team using cursor.

Param Type Description
options Object Other optional parameters.
options.accessToken String Custom access token of the request.

Example:

client.getAllUserList().then(res => {
  console.log(res);
  // [
  //   { ... },
  //   { ... },
  // ]
});

getUserInfo(userId, options?) - Official docs

Gets information about an user.

Param Type Description
userId String User to get info on.
options Object Other optional parameters.
options.accessToken String Custom access token of the request.

Example:

client.getUserInfo(userId).then(res => {
  console.log(res);
  // {
  //   id: 'U123456',
  //   name: 'bobby',
  //   ...
  // }
});

Channels API

getChannelList(options?) - Official docs

Param Type Description
options Object Other optional parameters.
options.accessToken String Custom access token of the request.

Lists all channels in a Slack team.

Example:

client.getChannelList().then(res => {
  console.log(res);
  // [
  //   { ... },
  //   { ... },
  // ]
});

getChannelInfo(channelId, options?) - Official docs

Gets information about a channel.

Param Type Description
channelId String Channel to get info on.
options Object Other optional parameters.
options.accessToken String Custom access token of the request.

Example:

client.getChannelInfo(channelId).then(res => {
  console.log(res);
  // {
  //   id: 'C8763',
  //   name: 'fun',
  //   ...
  // }
});

Conversasions API

getConversationInfo(channelId, options?) - Official docs

Retrieve information about a conversation.

Param Type Description
channelId String Channel to get info on.
options Object Other optional parameters.
options.accessToken String Custom access token of the request.

Example:

client.getConversationInfo(channelId).then(res => {
  console.log(res);
  // {
  //   id: 'C8763',
  //   name: 'fun',
  //   ...
  // }
});

getConversationMembers(channelId, options?) - Official docs

Retrieve members of a conversation.

Param Type Description
channelId String Channel to get info on.
options Object Optional arguments.
options.accessToken String Custom access token of the request.

Example:

client.getConversationMembers(channelId, { cursor: 'xxx' });
client.getConversationMembers(channelId).then(res => {
  console.log(res);
  // {
  //   members: ['U061F7AUR', 'U0C0NS9HN'],
  //   next: 'cursor',
  // }
});

getAllConversationMembers(channelId, options?) - Official docs

Recursively retrieve members of a conversation using cursor.

Param Type Description
channelId String Channel to get info on.
options Object Other optional parameters.
options.accessToken String Custom access token of the request.

Example:

client.getAllConversationMembers(channelId).then(res => {
  console.log(res);
  // ['U061F7AUR', 'U0C0NS9HN', ...]
});

getConversationList(options?) - Official docs

Lists all channels in a Slack team.

Param Type Description
options Object Optional arguments.
options.accessToken String Custom access token of the request.

Example:

client.getConversationList({ cursor: 'xxx' });
client.getConversationList().then(res => {
  console.log(res);
  // {
  //   channels: [
  //     {
  //       id: 'C012AB3CD',
  //       name: 'general',
  //       ...
  //     },
  //     {
  //       id: 'C012AB3C5',
  //       name: 'random',
  //       ...
  //     },
  //   ],
  //   next: 'cursor',
  // }
});

getAllConversationList(options?) - Official docs

Recursively lists all channels in a Slack team using cursor.

Param Type Description
options Object Optional arguments.
options.accessToken String Custom access token of the request.

Example:

client.getAllConversationList().then(res => {
  console.log(res);
  // [
  //   {
  //     id: 'C012AB3CD',
  //     name: 'general',
  //     ...
  //   },
  //   {
  //     id: 'C012AB3C5',
  //     name: 'random',
  //     ...
  //   },
  // ],
});

Webhook Client

Usage

Get your webhook url by adding a Incoming Webhooks integration to your team or setup Incoming Webhooks function to your app.

const { SlackWebhookClient } = require('messaging-api-slack');

// get webhook URL by adding a Incoming Webhook integration to your team.
// https://my.slack.com/services/new/incoming-webhook/
const client = SlackWebhookClient.connect(
  'https://hooks.slack.com/services/XXXXXXXX/YYYYYYYY/zzzzzZZZZZ'
);

API Reference

All methods return a Promise.


Send API - Official docs

sendRawBody(body)

Param Type Description
body Object Raw data to be sent.

Example:

client.sendRawBody({ text: 'Hello!' });

sendText(text)

Param Type Description
text String Text of the message to be sent.

Example:

client.sendText('Hello!');

sendAttachments(attachments) - Official docs

Send multiple attachments which let you add more context to a message.

Param Type Description
attachments Array<Object> Messages are attachments, defined as an array. Each object contains the parameters to customize the appearance of a message attachment.

Example:

client.sendAttachments([
  {
    fallback: 'some text',
    pretext: 'some pretext',
    color: 'good',
    fields: [
      {
        title: 'aaa',
        value: 'bbb',
        short: false,
      },
    ],
  },
  {
    fallback: 'some other text',
    pretext: 'some pther pretext',
    color: '#FF0000',
    fields: [
      {
        title: 'ccc',
        value: 'ddd',
        short: false,
      },
    ],
  },
]);

sendAttachment(attachment) - Official docs

Send only one attachment.

Param Type Description
attachments Object Message is an attachment. The object contains the parameters to customize the appearance of a message attachment.

Example:

client.sendAttachment({
  fallback: 'some text',
  pretext: 'some pretext',
  color: 'good',
  fields: [
    {
      title: 'aaa',
      value: 'bbb',
      short: false,
    },
  ],
});

Debug Tips

Log requests details

To enable default request debugger, use following DEBUG env variable:

DEBUG=messaging-api-slack

If you want to use custom request logging function, just define your own onRequest:

// for SlackOAuthClient
const client = SlackOAuthClient.connect({
  accessToken: ACCESS_TOKEN,
  onRequest: ({ method, url, headers, body }) => {
    /* */
  },
});

// for SlackWebhookClient
const client = SlackWebhookClient.connect({
  url: URL,
  onRequest: ({ method, url, headers, body }) => {
    /* */
  },
});

Test

Point requests to your dummy server

To avoid sending requests to real Slack server, specify origin option when constructing your client:

const { SlackOAuthClient } = require('messaging-api-slack');

const client = SlackOAuthClient.connect({
  accessToken: ACCESS_TOKEN,
  origin: 'https://mydummytestserver.com',
});

Warning: Don't do this on production server.

Manual Mock with Jest

create __mocks__/messaging-api-slack.js in your project root:

// __mocks__/messaging-api-slack.js
const jestMock = require('jest-mock');
const { SlackOAuthClient, SlackWebhookClient } = require.requireActual(
  'messaging-api-slack'
);

module.exports = {
  SlackOAuthClient: {
    connect: jest.fn(() => {
      const Mock = jestMock.generateFromMetadata(
        jestMock.getMetadata(SlackOAuthClient)
      );
      return new Mock();
    }),
  },
  SlackWebhookClient: {
    connect: jest.fn(() => {
      const Mock = jestMock.generateFromMetadata(
        jestMock.getMetadata(SlackWebhookClient)
      );
      return new Mock();
    }),
  },
};

Then, mock messaging-api-slack package in your tests:

// __tests__/mytest.spec.js
jest.mock('messaging-api-slack');