Skip to content

Commit

Permalink
Merge pull request #702 from aoberoi/docs-updates
Browse files Browse the repository at this point in the history 
Modernize examples in documentation
  • Loading branch information
@aoberoi
aoberoi committed Feb 16, 2019
2 parents e4bf6a0 + 503e793 commit 374fd1e
Show file tree
Hide file tree
Showing 35 changed files with 570 additions and 3,165 deletions.
106 changes: 49 additions & 57 deletions README.md
View file
Expand Up @@ -6,19 +6,9 @@

Visit the [full documentation](https://slackapi.github.io/node-slack-sdk) for all the lovely details.

So you want to build a Slack app with Node.js? We've got you covered. This package is aimed at making
building Slack apps ridiculously easy. It helps you build on all aspects of the Slack platform, from dropping
notifications in channels to fully interactive bots.

**Upgrading from version 3?** The
[migration guide](https://github.com/slackapi/node-slack-sdk/wiki/Migration-Guide-for-v4) has all the information you
need to bring your app up to speed.

## Requirements

This package supports Node v6 and higher. It's highly recommended to use
[the latest LTS version of node](https://github.com/nodejs/Release#release-schedule), and the documentation is written
using syntax and features from that version.
So you want to build a Slack app with Node.js? We've got you covered. This package is aimed at making building Slack
apps ridiculously easy. It helps you build on all aspects of the Slack platform, from dropping notifications in channels
to fully interactive bots.

## Installation

Expand All @@ -30,9 +20,8 @@ $ npm install @slack/client

## Features

The Slack platform offers several APIs to build apps. Each API delivers part of the capabilities
from the platform, with a range of complexity and functionality, so that you can pick the one that
fits for your app.
The Slack platform offers several APIs to build apps. Each API delivers part of the capabilities from the platform, with
a range of complexity and functionality, so that you can pick the one that fits for your app.

| Slack API | Outgoing | Incoming | NPM Package | Documentation |
|--------------|:--------:|:--------:|---------------------|-------------------|
Expand All @@ -42,55 +31,48 @@ fits for your app.
| Events API | ⬜️ | ⬇️ | `@slack/events-api` | [README](https://github.com/slackapi/node-slack-events-api) |
| Interactive Messages | ⬜️ | ⬇️ | `@slack/interactive-messages` | [README](https://github.com/slackapi/node-slack-interactive-messages) |

**Just starting out?** We suggest starting at the
[Getting Started guide](https://slackapi.github.io/node-slack-sdk/getting_started) which will walk you
through building your first Slack app using Node.js.
**Just starting out?** The [Getting Started guide](https://slackapi.github.io/node-slack-sdk/getting_started) will walk
you through building your first Slack app using Node.js.

**Not sure about which APIs are right for your app?** Read our
[helpful blog post](https://medium.com/slack-developer-blog/getting-started-with-slacks-apis-f930c73fc889)
that explains and compares the options. If you're still not sure,
[reach out for help](#getting-help) and our community can guide you.

**Building a workspace app?** The `WebClient` can automatically [handle token rotation](https://slackapi.github.io/node-slack-sdk/web_api#using-refresh-tokens) for your app. [Learn more](https://api.slack.com/docs/rotating-and-refreshing-credentials#why) about why you should enable token expiration (hint: it's required for App Directory distribution).
**Not sure about which APIs are right for your app?** Read our [helpful blog
post](https://medium.com/slack-developer-blog/getting-started-with-slacks-apis-f930c73fc889) that explains and compares
the options. If you're still not sure, [reach out for help](#getting-help) and our community can guide you.

## Examples

### Posting a message with Web API

Your app will interact with the Web API through the `WebClient` object, which a top level export
from this package. At a minimum, you need to instantiate it with a token. The example below shows
how to post a message into a channel, DM, MPDM, or group. This will require either the
`chat:user:write` or `chat:bot:write` scopes.
Your app will interact with the Web API through the `WebClient` object, which a top level export from this package. You
need to instantiate it with a token. The example below shows how to post a message into a channel, DM, MPDM, or group.
This will require either the `bot`, `chat:user:write` or `chat:bot:write` scopes.

```javascript
const { WebClient } = require('@slack/client');

// An access token (from your Slack app or custom integration - xoxa, xoxp, or xoxb)
// An access token (from your Slack app or custom integration - xoxp, xoxb)
const token = process.env.SLACK_TOKEN;

const web = new WebClient(token);

// This argument can be a channel ID, a DM ID, a MPDM ID, or a group ID
const conversationId = 'C1232456';

// See: https://api.slack.com/methods/chat.postMessage
web.chat.postMessage({ channel: conversationId, text: 'Hello there' })
.then((res) => {
// `res` contains information about the posted message
console.log('Message sent: ', res.ts);
})
.catch(console.error);
(async () => {
// See: https://api.slack.com/methods/chat.postMessage
const res = await web.chat.postMessage({ channel: conversationId, text: 'Hello there' });

// `res` contains information about the posted message
console.log('Message sent: ', res.ts);
})();
```

The `WebClient` object makes it simple to call any of the
[**over 130 Web API methods**](https://api.slack.com/methods). See the
[guide](http://slackapi.github.io/node-slack-sdk/web_api) for details.
The `WebClient` object makes it simple to call any of the [**over 130 Web API methods**](https://api.slack.com/methods).
See the [guide](http://slackapi.github.io/node-slack-sdk/web_api) for details.

### Posting a message with the Real-Time Messaging API
### Using the Real-Time Messaging API

Your app will interact with the RTM API through the `RTMClient` object, which is a top level
export from this package. At a minimum, you need to instantiate it with a token, usually a
bot token.
Your app will interact with the RTM API through the `RTMClient` object, which is another top level export from this
package. You need to instantiate it with a token, usually a bot token.

```javascript
const { RTMClient } = require('@slack/client');
Expand All @@ -102,23 +84,27 @@ const token = process.env.SLACK_TOKEN;
const rtm = new RTMClient(token);
rtm.start();

// This argument can be a channel ID, a DM ID, a MPDM ID, or a group ID
const conversationId = 'C1232456';
// Calling `rtm.on(eventName, eventHandler)` allows you to handle events
// When the connection is active, the 'ready' event will be triggered
rtm.on('ready', async () => {

// The RTM client can send simple string messages
rtm.sendMessage('Hello there', conversationId)
.then((res) => {
// `res` contains information about the posted message
console.log('Message sent: ', res.ts);
})
.catch(console.error);
// Once the connection is open, your app will start receiving other events. It can also send messages.

// Sending a message requires a channel ID, a DM ID, an MPDM ID, or a group ID
// The following value is used as an example
const conversationId = 'C1232456';

// The RTM client can send simple string messages
const res = await rtm.sendMessage('Hello there', conversationId);

// `res` contains information about the sent message
console.log('Message sent: ', res.ts);
});
```

The `RTMClient` object makes it simple to listen for [events](https://api.slack.com/rtm#events) from a workspace
and send simple messages to a workspace. See the
[guide](http://slackapi.github.io/node-slack-sdk/rtm_api) for details.
See the [guide](http://slackapi.github.io/node-slack-sdk/rtm_api) for more details.

## Posting a message with Incoming Webhooks
### Posting a message with Incoming Webhooks

[Incoming webhooks](https://api.slack.com/incoming-webhooks) are an easy way to send notifications
to a Slack channel with a minimum of setup. You'll need a webhook URL from a Slack app or a custom
Expand All @@ -139,6 +125,12 @@ webhook.send('Hello there', function(err, res) {
});
```

## Requirements

This package supports Node v6 LTS and higher. It's highly recommended to use [the latest LTS version of
node](https://github.com/nodejs/Release#release-schedule), and the documentation is written using syntax and features
from that version.

## Getting Help

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

0 comments on commit 374fd1e

Please sign in to comment.