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
• Debug Tips
• Testing

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 = new SlackOAuthClient({
  accessToken: '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

• chat.postMessage
• chat.postEphemeral

Users API

• getUserList
• getAllUserList
• getUserInfo

Channels API

• getChannelInfo

Conversations API

• getConversationInfo
• getConversationMembers
• getAllConversationMembers
• getConversationList
• getAllConversationList

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 = new SlackWebhookClient({
  url: 'https://hooks.slack.com/services/XXXXXXXX/YYYYYYYY/zzzzzZZZZZ',
});

API Reference

All methods return a Promise.

Send API - Official docs

• sendRawBody
• sendText
• sendAttachments
• sendAttachment

Debug Tips

Log Requests Details

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

DEBUG=messaging-api:request

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

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

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

Testing

Point Requests to Your Dummy Server

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

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

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

Warning: Don't do this on your production server.

Changelog

1.0.1 / 2020-09-21

• chore: remove namespace and export types from module instead #627