Slack Web API


The @slack/web-api package contains a simple, convenient, and configurable HTTP client for making requests to Slack's
Web API. Use it in your app to call any of the over 130
methods, and let it handle formatting, queuing, retrying, pagination, and more.

Requirements

This package supports Node v18 and higher. It's highly recommended to use the latest LTS version of
node, and the documentation is written using syntax and features
from that version.

Installation

``shell
$ npm install @slack/web-api
`

Usage

These examples show the most common features of the WebClient. You'll find even more extensive documentation on the
package's website.

---

$3

The package exports a WebClient class. All you need to do is instantiate it, and you're ready to go. You'll typically
initialize it with a token, so that you don't have to provide the token each time you call a method. A token usually
begins with xoxb or xoxp. You get them from each workspace an app is installed onto. The app configuration pages
help you get your first token for your development workspace.

`javascript
const { WebClient } = require('@slack/web-api');

// Read a token from the environment variables
const token = process.env.SLACK_TOKEN;

// Initialize
const web = new WebClient(token);
`

---

$3

The client instance has a named method for each of the public methods in the Web API. The most popular one is
called chat.postMessage, and it's used to send a message to a conversation. For every method, you pass arguments as
properties of an options object. This helps with the readability of your code since every argument has a name. All
named methods return a Promise which resolves with the response data or rejects with an error.

`javascript
// Given some known conversation ID (representing a public channel, private channel, DM or group DM)
const conversationId = '...';

(async () => {

// Post a message to the channel, and await the result.
// Find more arguments and details of the response: https://docs.slack.dev/reference/methods/chat.postMessage
const result = await web.chat.postMessage({
text: 'Hello world!',
channel: conversationId,
});

// The result contains an identifier for the message, ts.
console.log(Successfully send message ${result.ts} in conversation ${conversationId});
})();
`

Tip: If you're using an editor that supports TypeScript, even if you're not using TypeScript to write your code,
you'll get hints for all the arguments each method supports. This helps you save time by reducing the number of
times you need to pop out to a webpage to check the reference. There's more information about using
TypeScript with this package in the documentation website.

Tip: Use the Block Kit Builder for a playground
where you can prototype your message's look and feel.

---

$3

Errors can happen for many reasons: maybe the token doesn't have the proper scopes to
call a method, maybe it's been revoked by a user, or maybe you just used a bad argument. In these cases, the returned
Promise will reject with an Error. You should catch the error and use the information it contains to decide how your
app can proceed.

Each error contains a code property, which you can check against the ErrorCode export to understand the kind of
error you're dealing with. For example, when Slack responds to your app with an error, that is an
ErrorCode.PlatformError. These types of errors provide Slack's response body as the data property.

`javascript
// Import ErrorCode from the package
const { WebClient, ErrorCode } = require('@slack/web-api');

(async () => {

try {
// This method call should fail because we're giving it a bogus user ID to lookup.
const response = await web.users.info({ user: '...' });
} catch (error) {
// Check the code property, and when it's a PlatformError, log the whole response.
if (error.code === ErrorCode.PlatformError) {
console.log(error.data);
} else {
// Some other error, oh no!
console.log('Well, that was unexpected.');
}
}
})();
`

---

$3

Many of the Web API's methods return
lists of objects, and are known to be cursor-paginated. The result of calling these methods will contain a part of
the list, or a page, and also provide you with information on how to continue to the next page on a subsequent API call.
Instead of calling many times manually, the WebClient can manage to get each page, allowing you to determine when to
stop, and help you process the results.

The process of retrieving multiple pages from Slack's API can be described as asynchronous iteration, which means
you're processing items in a collection, but getting each item is an asynchronous operation. Fortunately, JavaScript
has this concept built-in, and in newer versions of the language there's a syntax to make it even simpler:
for await...of.

`javascript
(async () => {
let result;

// Async iteration is similar to a simple for loop.
// Use only the first two parameters to get an async iterator.
for await (const page of web.paginate('something.list', { name: 'value' })) {
// You can inspect each page, find your result, and stop the loop with a break statement
if (containsTheThing(page.something)) {
result = page.something.thing;
break;
}
}
});
`

The for await...of syntax is available in Node v10.0.0 and above. If you're using an older version of Node, see
functional iteration below.

---

$3

The WebClient will log interesting information to the console by default. You can use the logLevel to decide how
much information, or how interesting the information needs to be, in order for it to be output. There are a few possible
log levels, which you can find in the LogLevel export. By default, the value is set to LogLevel.INFO. While you're
in development, it's sometimes helpful to set this to the most verbose: LogLevel.DEBUG.

`javascript
// Import LogLevel from the package
const { WebClient, LogLevel } = require('@slack/web-api');

// Log level is one of the options you can set in the constructor
const web = new WebClient(token, {
logLevel: LogLevel.DEBUG,
});
`

All the log levels, in order of most to least information, are: DEBUG, INFO, WARN, and ERROR.

---

$3

In production systems, you want your app to be resilient to short hiccups and temporary outages. Solving for this
problem usually involves building a queuing system that handles retrying failed tasks. The WebClient comes with this
queuing system out of the box, and it's on by default! The client will retry a failed API method call up to 10 times,
spaced out over about 30 minutes. If the request doesn't succeed within that time, then the returned Promise will reject.
You can observe each of the retries in your logs by setting the log level to DEBUG. Try running the
following code with your network disconnected, and then re-connect after you see a couple of log messages:

`javascript
const { WebClient, LogLevel } = require('@slack/web-api');

const web = new WebClient('bogus token');

(async () => {
await web.auth.test();

console.log('Done!');
})();
`

Shortly after re-connecting your network, you should see the Done! message. Did you notice the program doesn't use a
valid token? The client is doing something clever and helpful here. It knows the difference between an error such as not
being able to reach api.slack.com and an error in the response from Slack about an invalid token. The former is
something that can be resolved with a retry, so it was retried. The invalid token error means that the call isn't going
to succeed until your app does something differently, so it stops attempting retries.

You might not think 10 reties in 30 minutes is a good policy for your app. No problem, you can set the retryConfig to
one that works better for you. The retryPolicies export contains a few well known options, and you can always write
your own.

`javascript
const { WebClient, retryPolicies } = require('@slack/web-api');

const web = new WebClient(token, {
retryConfig: retryPolicies.fiveRetriesInFiveMinutes,
});
`

Here are some other values that you might want to use for retryConfig:

| retryConfig | Description |
|------------------------------------------------|---------------------------------|
| retryPolicies.tenRetriesInAboutThirtyMinutes | (default) |
| retryPolicies.fiveRetriesInFiveMinutes | Five attempts in five minutes |
| retryPolicies.rapidRetryPolicy | Used to keep tests running fast |
| { retries: 0 } | No retries (other options) |

Note: If an API call results in a rate limit being exceeded, you might still notice the client automatically
retrying the API call. If you'd like to opt out of that behavior, set the rejectRateLimitedCalls option to true.

---

$3

The documentation website has information about these additional features of
the WebClient:

* Upload a file with a Buffer or a ReadableStream.
* Using a custom agent for proxying
* Rate limit handling
* Request concurrency
* Custom TLS configuration
* Custom API URL
* Exchange an OAuth grant for a token

---

Getting Help

If you get stuck, we're here to help. The following are the best ways to get assistance working through your issue:

* Issue Tracker for questions, feature requests, bug reports and
general discussion related to these packages. Try searching before you create a new issue.
* Email us: feedback@slack.com`
* Community Slack: a Slack community for developers
building all kinds of Slack apps. You can find the maintainers and users of these packages in #lang-javascript.