messaging-api-slack

messaging-api-slack

Messaging API client for Slack

Table of Contents

• Installation
• OAuth Client
  • Usage
  • API Reference
• Webhook Client
  • Usage
  • API Reference

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'
);

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 chat.postMessage | channels.info | channels.list | users.info | users.list
body	Object	Body that the method needs.

Example:

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

Chat API

postMessage(channel, text [, 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.
text	String	Text of the message to be sent.
options	Object	Other optional parameters.

Example:

client.postMessage('C8763', 'Hello!');
client.postMessage('C8763', 'Hello!', { as_user: true });

Users API

getUserList(cursor?) - Official docs

Lists all users in a Slack team.

Param	Type	Description
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.

Example:

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

getAllUserList() - Official docs

Recursively lists all users in a Slack team using cursor.

Example:

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

getUserInfo(userId) - Official docs

Gets information about an user.

Param	Type	Description
userId	String	User to get info on.

Example:

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

Channels API

getChannelList() - Official docs

Lists all channels in a Slack team.

Example:

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

getChannelInfo(channelId) - Official docs

Gets information about a channel.

Param	Type	Description
channelId	String	Channel to get info on.

Example:

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

Webhook Client

Usage

Get your webhook url by adding a Incoming Webhooks integreation 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,
    },
  ],
});

Changelog

0.5.0 / 2017-10-20

• [new] A big improvement on error message.

For example, when you catch the error and log it out:

client.sendText().catch(console.error);

You can get some useful information to help you resolve the issue.

Error: Messenger API - 2500 OAuthException An active access token must be used to query information about the current user.
    at handleError (/Users/chentsulin/Projects/yoctol/ttt/node_modules/messaging-api-messenger/lib/MessengerClient.js:64:9)
    at <anonymous>
    at process._tickCallback (internal/process/next_tick.js:188:7)

Error Message -
  Messenger API - 2500 OAuthException An active access token must be used to query information about the current user.

Request -
  POST https://graph.facebook.com/v2.10/me/messages?access_token=

Request Data -
  {
    "recipient": {
      "id": ""
    },
    "message": {
      "text": ""
    }
  }

Response -
  400 Bad Request

Response Data -
  {
    "error": {
      "message": "An active access token must be used to query information about the current user.",
      "type": "OAuthException",
      "code": 2500,
      "fbtrace_id": "GOnNuiN/ewZ"
    }
  }

The error messages are powered by axios-error package.

• [deprecated] client.getHTTPClient() method is deprecated. use client.axios getter instead.

messaging-api-messenger

• [breaking] client.version now return version number string (2.10) instead of the v-prefix version (v2.10).