Node-slack-sdk: Documentation about the web API is missing.

[uxdiogenes]

A couple things I noticed trying to get started with the web API:

• There are no usage instruction for the web client in the readme, just for the rtm client
• It was unclear to me from the readme that I could use just the web client part of it to interact with our web API, so I went with another REST client library. Later I discovered this package fit my uses exactly when Don told me it definitely should (and then I found the example folder).
• It looks like you need to instantiate the web client with a token, but you may not necessarily have a token and might be trying to get one using the oauth flow (and specifically the oauth.access method). I think it might make the most sense to instantiate a client without a token, and then it adds the token to itself automatically as part of calling oauth.access. Then, so I can reuse it for different calls for different users if I wanted to it could have methods (or properties?) to swap out the token on the client object I already have.

[ekmartin]

You can actually use the web client without a token, so you could actually do something like this right now:

const client = new WebClient();
return client.oauth.access(clientId, clientSecret, code)
  .then(data => {
    const authClient = new WebClient(data.access_token);
  });

But I agree that it's unclear.

[tylucaskelley]

Bumping this; somewhat disappointing that the official client library contains almost no useful documentation. Having to search through the code and guess isn't exactly efficient. Any updates from the maintainers?

[tr4nquility]

Bump: I somehow got in the same situation here.
Documentation of Web Client usage is too minimal, which can also be considered as non-existant.
Is there any update on this documentation?

[ekmartin]

While you're waiting for more docs, it might be helpful to know that the web client's method names are equal to the API methods defined here. Arguments that are listed as required in the docs are passed as positional arguments, while optional ones are passed through the options object, which all the web client functions accept.

The ordering of the required arguments also seem to be the same as what's defined in the Slack docs, but here it's probably easier to check the code itself. All the API methods are defined in the facets folder, here.

Other than that, all the methods accept an optional callback. If no callback is provided, the methods return a promise. The resolved promise value (and the second callback argument) matches the response object in the Slack docs (i.e. the "Response" section here).

Example:

const webClient = new WebClient(token);
webClient.chat.postMessage('channel-id', 'friendly message', { username: 'cat' })
  .then(response => handleMessage(response.message))

webClient['files.comments'].add('file-id', 'what a comment', (err, response) => {
  // do something
});

[DEGoodmanWilson]

Howdy! Just want to let y'all know that we're starting to allocate dedicated engineering resources to this stuff. Documentation is very high on our priority list!

[tylucaskelley]

Glad to hear it! And yeah, for now just reading the web api docs is good enough for what I'm doing but looking forward to seeing some real docs / examples from you guys!