Before reading this documentation make sure you have read the baseline documentation.

Slack Managed API implementation details can be found here.

Implementation details table contains the following columns:

  • Original Grouping - This is the original group name that Slack has given.
  • Original Function Name - This is the original function name that Slack has given.
  • Status - Managed API status, any function that has green status can be expected to have full Managed API support.
  • Remapped Grouping - Grouping used in Managed API level, please note, the Managed API grouping can differ from the official vendor's grouping strategy, mostly for convenience and consistency sake. Remapped groupings are used for following cases:
    • Denotes an import path for the function when working on HTTP API or Managed API level. For example chat.scheduledMessages.list (original grouping + name) with remapped group name Chat.ScheduledMessage with remapped function full name getChatScheduledMessagescan be imported from following locations:

      // HTTP API
      import { getChatScheduledMessages } from '@avst-hzn/slack-api/http-api/chat/scheduledMessage';
       
      // Managed API
      import { getChatScheduledMessages } from '@avst-hzn/slack-api/managed-api/chat/scheduledMessage';
      JS
    • Denotes grouping for Fluent API groups. The same chat.scheduledMessages.list(original grouping + name) with remapped group name Chat.ScheduledMessageand with remapped function short name getScheduledMessagescan be used as following:

      import { SlackConnection } from '@avst-hzn/slack-api';
       
      export async function run() {
          const Slack = SlackConnection.connect('CONNECTION_ID');
       
          Slack.Chat.ScheduledMessage.getScheduledMessages({ ... });
      }
      JS
  • Remapped Function Short Name - Short function name is used in Fluent API level as shown above, exception being when function is accessed viaAll group then the function full name will be used as following, where the chat.scheduledMessages.list(original grouping + name)  and full function name is getChatScheduledMessages:

    import { SlackConnection } from '@avst-hzn/slack-api';
     
    export async function run() {
        const Slack = SlackConnection.connect('CONNECTION_ID');
     
        Slack.All.getChatScheduledMessages({ ... });
    }
    JS
  • Remapped Function Full Name - Full function name used in HTTP API, Managed API and Fluent API level, but only on Fluent API level when the function is accessed via All group as shown above, otherwise a short name is used.

Error handling

Error handling adheres to the same rules as outlined in the base documentation, with a minor addition of one additional error type SlackErrorSlackError is thrown when something expected goes wrong in Slack. Since Slack does not make use of HTTP status codes they have a custom way of representing errors that the SlackError is encapsulating. SlackError has also a generic type where the type represents the actual error response for the specific function where the error response contains all possible error values. It can be used in following ways:

import { SlackConnection } from '@avst-hzn/slack-api';
import { SlackError } from '@avst-hzn/slack-api/managed-api/common';
import { Chat } from '@avst-hzn/slack-api/types/chat';
 
export async function run() {
    const Slack = SlackConnection.connect('CONNECTION_ID');
 
    // Promise style
    Slack.Chat.postMessage({
        body: {
            channel: 'CHANNEL_ID',
            text: 'text'
        }
    })
    .then(response => {
        // Do something with the response
    })
    .catch(error => {
        if (error instanceof SlackError) {
            console.error(error.response.body.error); // Print out Slack error
        }
    });
 
    // Async/await style
    try {
        const response = await Slack.Chat.postMessage({
            body: {
                channel: 'CHANNEL_ID',
                text: 'text'
            }
        });
        // Do something with the response
    } catch (error) {
        if (error instanceof SlackError) {
            const body = error.response.body as Chat.PostMessage.Response.Error; // Explicit type cast is needed here because SlackErrors's generic type cannot be automatically inferred the same way as it works in Promise based example
            console.error(body.error); // Print out Slack error
        }
    }
 
    // Using error strategy
    const response = await MySlack.Chat.postMessage({
        body: {
            channel: 'CHANNEL_ID',
            text: 'text'
        },
        errorStrategy: {
            handleSlackError: error => {
                console.error(error.response.body.error); // Print out Slack error
                return null; // Return null if something goes wrong
            }
        }
    });
    if (response) {
        // Do something with the response
    }
}
JS

When you want to listen to specific slack errors only then there is a convenience function called mapSlackError in ErrorStrategyBuilder that can help you listen only for specific Slack errors and ignore the rest. It can be used as following (using builder injection pattern):

import { SlackConnection } from '@avst-hzn/slack-api';
 
export async function run() {
    const Slack = SlackConnection.connect('CONNECTION_ID');
 
    // Using error strategy
    const response = await Slack.Chat.postMessage({
        body: {
            channel: 'CHANNEL_ID',
            text: 'text'
        },
        errorStrategy: builder => builder
            .mapSlackError(error => {
                switch (error) {
                    case 'channel_not_found':
                        // Do something when channel is not found
                        break;
                    case 'not_in_channel':
                        // Do something when not in channel
                        break;
                }
                return null; // Return null if something goes wrong
            }, 'channel_not_found', 'not_in_channel') // Only listening to 'channel_not_found' and 'not_in_channel' Slack errors
    });
    if (response) {
        // Do something with the response
    }
}
JS

Since each Slack error response is typed you can expect to get back proper enumeration of function specific error types as following (but only when working on Promise based approach, other styles require explicit casting as shown in async/await style example):

Common HTTP Errors

Generally Slack does not make use of HTTP status codes, except when requests are being rate limited in which case 429 is sent back.

As mentioned in the baseline documentation that in place of common HTTP errors instead of throwing HttpError a more specific error is thrown that can be caught directly. Since more specific errors derive from HttpError you can still catch that one too.

Here is a mapping of common HTTP errors and error types that they are represented by:

HTTP ErrorError Type
429TooManyRequestsError