Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Expand on getting access token documentation #1609

Merged
merged 1 commit into from Apr 20, 2023
Merged

Expand on getting access token documentation #1609

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
13 changes: 9 additions & 4 deletions docs/_packages/socket_mode.md
View file
Open in desktop
Expand Up @@ -16,14 +16,19 @@ $ npm install @slack/socket-mode

---

### Initialize the client
### Prerequisites

This package is designed to support [**Socket Mode**](https://api.slack.com/socket-mode), which allows your app to receive events from Slack over a WebSocket connection.
This package requires a Slack app with an **App-level token**.

To create a new Slack app, head over to [api.slack.com/apps/new](https://api.slack.com/apps?new_app=1).

The package exports a `SocketModeClient` class. Your app will create an instance of the class for each workspace it communicates with. Creating an instance requires an **app-level token** from Slack. Apps connect to the **Socket Mode** API using an **app-level token**, which starts with `xapp`.
To generate an **App Token** for your app, on your app's page on [api.slack.com/apps](https://api.slack.com/apps), under the main **Basic Information** page, scroll down to **App-Level Tokens**. Click **Generate Token and Scopes**, add a name for your app token, and click **Add Scope**. Choose `connections:write` and then click **Generate**. Copy and safely store the generated token!

Note: **Socket Mode** requires the `connections:write` scope. Navigate to your [app configuration](https://api.slack.com/apps) and go to the **OAuth and Permissions** section to add the scope.
### Initialize the client

This package is designed to support [**Socket Mode**](https://api.slack.com/socket-mode), which allows your app to receive events from Slack over a WebSocket connection.

The package exports a `SocketModeClient` class. Your app will create an instance of the class for each workspace it communicates with.

```javascript
const { SocketModeClient } = require('@slack/socket-mode');
Expand Down
36 changes: 27 additions & 9 deletions docs/_packages/web_api.md
View file
Open in desktop
Expand Up @@ -21,12 +21,30 @@ $ npm install @slack/web-api

---

### Prerequisites

To use this package, you must have a Slack access token. Access tokens are issued
to Slack applications. Each application _installation_, that is, the unique combination
of an application and a specific Slack workspace it is installed to, will generate
a workspace-specific access token for the application.

We recommend you read our documentation on [Basic app setup](https://api.slack.com/authentication/basics).
This article contains the steps you must follow to get your access token:

1. [Create a new Slack application](https://api.slack.com/authentication/basics#creating)
2. [Set permissions your app will request](https://api.slack.com/authentication/basics#scopes)
3. [Install the app to a workspace](https://api.slack.com/authentication/basics#installing)
4. Finally, [get your access token](https://api.slack.com/authentication/basics#getting-your-authentication-token)

You can also read the [Getting Started guide](../getting-started) which guides
you through creating an app, retrieving an access token, and using this `@slack/web-api`
package to post a message.

### Initialize the client

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.
The package exports a `WebClient` class. You must initialize it with an access
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`.

```javascript
const { WebClient } = require('@slack/web-api');
Expand All @@ -43,7 +61,7 @@ const web = new WebClient(token);
<strong><i>Initializing without a token</i></strong>
</summary>

Alternatively, you can create a client without an token, and use it with multiple workspaces as long as you supply a
Alternatively, you can create a client without a token, and use it with multiple workspaces as long as you supply a
`token` when you call a method.

```javascript
Expand Down Expand Up @@ -448,7 +466,7 @@ retrying the API call. If you'd like to opt out of that behavior, set the `rejec
---

### Upload a file
As of @slack/web-api v6.8.0, we have introduced a modified way to upload files.
As of @slack/web-api v6.8.0, we have introduced a modified way to upload files.

We've received many reports on the performance issue of the existing `files.upload` API. So, to cope with the problem, our Platform team decided to unlock a new way to upload files to Slack via public APIs. To utilize the new approach, developers need to implement the following steps on their code side:

Expand Down Expand Up @@ -481,7 +499,7 @@ const result = await web.files.upload({
console.log('File uploaded: ', result.file.id);
```

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

Expand All @@ -491,7 +509,7 @@ const result = await web.files.uploadV2({
file: './path/to/logo.png', // also accepts Buffer or ReadStream
filename: 'logo.png',
// Note that channels still works but going with channel_id="C12345" is recommended.
// channels="C111,C222" is no longer supported. In this case, an exception will be thrown
// channels="C111,C222" is no longer supported. In this case, an exception will be thrown
channels: 'C12345',
initial_comment: 'Here is the new company logo',
});
Expand Down Expand Up @@ -763,7 +781,7 @@ look at the [@aoberoi/passport-slack Passport Strategy](https://github.com/aober

**Sign in With Slack** via [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) gives users the ability to sign into your service using their Slack profile.

The `@slack/web-api` package supports the following API methods which you can use to implement **Sign in With Slack**:
The `@slack/web-api` package supports the following API methods which you can use to implement **Sign in With Slack**:

- [`openid.connect.token`](https://api.slack.com/methods/openid.connect.token)
- [`openid.connect.userInfo`](https://api.slack.com/methods/openid.connect.userInfo)
Expand Down
6 changes: 3 additions & 3 deletions docs/_reference/web-api.md
View file
Open in desktop
Expand Up @@ -24,7 +24,7 @@ slug: web-api
<td align="center">token</td>
<td align="center"><code>string</code></td>
<td align="center">✗</td>
<td><p>An API token to authenticate/authorize with Slack (usually start with <code>xoxp</code>, <code>xoxb</code>)</p></td>
<td><p>An API token to authenticate/authorize with Slack (usually start with <code>xoxp</code>, <code>xoxb</code>). To learn how to get an access token, check out our <a href="https://api.slack.com/authentication/basics">Authentication Basics documentation</a>, and in particular the <a href="https://api.slack.com/authentication/basics#getting-your-authentication-token">Getting your access token section</a>.</p></td>
</tr>
<tr>
<td align="center">opts</td>
Expand Down Expand Up @@ -109,7 +109,7 @@ slug: web-api
<tr>
<td align="center">token</td>
<td align="center"><code>string</code></td>
<td><p>Authentication and authorization token for accessing Slack Web API (usually begins with <code>xoxp</code> or <code>xoxb</code>)</p></td>
<td><p>An API token to authenticate/authorize with Slack (usually start with <code>xoxp</code>, <code>xoxb</code>). To learn how to get an access token, check out our <a href="https://api.slack.com/authentication/basics">Authentication Basics documentation</a>, and in particular the <a href="https://api.slack.com/authentication/basics#getting-your-authentication-token">Getting your access token section</a>.</p></td>
</tr>
</tbody>
</table>
Expand Down Expand Up @@ -661,4 +661,4 @@ One of:
<li><a href="#webapirequesterror" title=""><code>WebAPIRequestError</code></a></li>
<li><a href="#webapihttperror" title=""><code>WebAPIHTTPError</code></a></li>
<li><a href="#webapiratelimitederror" title=""><code>WebAPIRateLimitedError</code></a></li>
</ul>
</ul>
6 changes: 4 additions & 2 deletions docs/_tutorials/local_development.md
View file
Open in desktop
Expand Up @@ -27,7 +27,7 @@ Feel free to skip around to the specific sections relevant to you — we won't m
Head over to our [Bolt JS Getting Started Guide's section "Create an App"](https://slack.dev/bolt-js/tutorial/getting-started#create-an-app) for the latest up-to-date instructions on how to create a new app on [api.slack.com/apps](https://api.slack.com/apps).

## Tokens and installing apps
Head over to our [Bolt JS Getting Started Guide's section "Tokens and installing apps"](https://slack.dev/bolt-js/tutorial/getting-started#tokens-and-installing-apps) for the latest up-to-date information on what tokens are, the [different kinds of tokens available](https://api.slack.com/docs/token-types), how to create them on [api.slack.com/apps](https://api.slack.com/apps) and finally how to install your app to a live Slack workspace.
Head over to our [Bolt JS Getting Started Guide's section "Tokens and installing apps"](https://slack.dev/bolt-js/tutorial/getting-started#tokens-and-installing-apps) for the latest up-to-date information on what tokens are, the [different kinds of tokens available](https://api.slack.com/docs/token-types), how to create them on [api.slack.com/apps](https://api.slack.com/apps), how to install your app to a live Slack workspace and finally how to retrieve your access token.

## Socket Mode vs. HTTP
Your app can [communicate with Slack using one of two methods](https://api.slack.com/apis/connections):
Expand All @@ -39,7 +39,9 @@ This tutorial will cover how to set up your app using either approach.

### Socket Mode

Setting up your Node.js application for Socket Mode development is fast and easy with the [`@slack/socket-mode`](https://slack.dev/node-slack-sdk/socket-mode) package. In the previous [Tokens and installing apps](#tokens-and-installing-apps) section, you should have created and saved an App Token. You'll need that when following the [Socket Mode package setup instructions](../socket-mode).
Setting up your Node.js application for Socket Mode development is fast and easy with the [`@slack/socket-mode`](https://slack.dev/node-slack-sdk/socket-mode) package.

Once you've [created an app](#create-an-app), you will need to generate an **App Token**. On your app's page on [api.slack.com/apps](https://api.slack.com/apps), under the main **Basic Information** page, scroll down to **App-Level Tokens**. Click **Generate Token and Scopes**, add a name for your app token, and click **Add Scope**. Choose `connections:write` and then click **Generate**. Copy and safely store the generated token - you'll need that when following the [Socket Mode package setup instructions](../socket-mode).

### HTTP

Expand Down