Class SlackService

java.lang.Object
edu.ucsb.cs156.frontiers.services.SlackService

@Service public class SlackService extends Object
Service for interacting with the Slack Web API.

A Slack bot token (xoxb-...) is already associated with a specific workspace, so the token alone is sufficient to identify where API calls go.

Note that the Slack Web API typically returns HTTP 200 even for failures; the ok field of the response indicates success, and error contains an error code (e.g. invalid_auth, missing_scope).

Tokens are secrets; they must never be logged.

  • Field Details

    • AUTH_TEST_ENDPOINT

      public static final String AUTH_TEST_ENDPOINT
      See Also:
    • USERS_LIST_ENDPOINT

      public static final String USERS_LIST_ENDPOINT
      See Also:
    • MAX_USER_PAGES

      public static final int MAX_USER_PAGES
      Upper bound on the number of pages of users fetched (200 users per page), so that a misbehaving cursor can never cause an endless loop.
      See Also:
    • SLACK_UNREACHABLE

      public static final String SLACK_UNREACHABLE
      Error code used when Slack could not be reached or returned an unusable response.
      See Also:
    • SLACK_API

      public static final String SLACK_API
      See Also:
    • CONVERSATIONS_LIST_ENDPOINT

      public static final String CONVERSATIONS_LIST_ENDPOINT
      See Also:
    • PRIVATE_CONVERSATIONS_LIST_ENDPOINT

      public static final String PRIVATE_CONVERSATIONS_LIST_ENDPOINT
      See Also:
    • MAX_PAGES

      public static final int MAX_PAGES
      Upper bound on the number of pages fetched for any paginated method; see MAX_USER_PAGES.
      See Also:
    • RATE_LIMITED

      public static final String RATE_LIMITED
      Error code used when Slack kept rate limiting a call, even after waiting as it asked.
      See Also:
    • RESTRICTED_ACTION

      public static final String RESTRICTED_ACTION
      Slack's error code when a workspace preference forbids the action: for conversations.kick, when the workspace does not let this bot remove members from public channels (by default only Workspace Owners and Admins may).
      See Also:
    • REMOVAL_RESTRICTED_ADVICE

      public static final String REMOVAL_RESTRICTED_ADVICE
      What to tell the instructor when removing a member fails with RESTRICTED_ACTION.
      See Also:
    • MAX_RATE_LIMIT_RETRIES

      public static final int MAX_RATE_LIMIT_RETRIES
      How many times a rate limited (HTTP 429) call is tried again, after waiting.
      See Also:
    • MAX_RETRY_AFTER_SECONDS

      public static final long MAX_RETRY_AFTER_SECONDS
      Longest wait, in seconds, before trying a rate limited call again.
      See Also:
  • Constructor Details

    • SlackService

      public SlackService(org.springframework.boot.web.client.RestTemplateBuilder builder)
  • Method Details

    • setSleeper

      public void setSleeper(SlackService.Sleeper sleeper)
    • authTest

      public SlackAuthTestResponse authTest(String token)
      Calls the Slack auth.test method to check whether a bot token is valid.
      Parameters:
      token - the (plaintext) Slack bot token
      Returns:
      the response from Slack; if ok is true, team and teamId identify the workspace the token belongs to. If Slack cannot be reached, a response with ok false and error SLACK_UNREACHABLE is returned.
    • listUsers

      public List<SlackUser> listUsers(String token)
      Calls the Slack users.list method (following pagination) to get all members of the workspace the token belongs to. This includes bots, deactivated accounts, and users who have been invited but have not yet signed in; see SlackUser.isActivePerson().

      Requires the users:read scope; emails are only included if the token also has the users:read.email scope.

      Parameters:
      token - the (plaintext) Slack bot token
      Returns:
      all members of the workspace
      Throws:
      SlackApiException - with the Slack error code (e.g. missing_scope) if Slack reports an error, or SLACK_UNREACHABLE if Slack cannot be reached
    • listPublicChannels

      public List<SlackChannel> listPublicChannels(String token)
      Calls the Slack conversations.list method (following pagination) to get all public channels of the workspace, including archived ones (the name of an archived channel is still taken). Requires the channels:read scope.
      Parameters:
      token - the (plaintext) Slack bot token
      Returns:
      the public channels of the workspace
      Throws:
      SlackApiException - with the Slack error code if the call fails
    • listPrivateChannels

      public List<SlackChannel> listPrivateChannels(String token)
      Calls the Slack conversations.list method (following pagination) to get the private channels that the bot is a member of, including archived ones; Slack does not tell a bot about any other private channels. Requires the groups:read scope.
      Parameters:
      token - the (plaintext) Slack bot token
      Returns:
      the private channels of the workspace that the bot is a member of
      Throws:
      SlackApiException - with the Slack error code if the call fails
    • createPublicChannel

      public SlackChannel createPublicChannel(String token, String name)
      Calls the Slack conversations.create method to create a public channel; the bot becomes a member of the channel it creates. Requires the channels:manage scope.
      Parameters:
      token - the (plaintext) Slack bot token
      name - name of the channel (lowercase letters, digits, hyphens and underscores)
      Returns:
      the new channel
      Throws:
      SlackApiException - with the Slack error code (e.g. name_taken, invalid_name_specials) if the call fails
    • createPrivateChannel

      public SlackChannel createPrivateChannel(String token, String name)
      Calls the Slack conversations.create method to create a private channel; the bot becomes a member of the channel it creates. Requires the groups:write scope.
      Parameters:
      token - the (plaintext) Slack bot token
      name - name of the channel (lowercase letters, digits, hyphens and underscores)
      Returns:
      the new channel
      Throws:
      SlackApiException - with the Slack error code (e.g. name_taken) if the call fails
    • renameChannel

      public void renameChannel(String token, String channelId, String name)
      Calls the Slack conversations.rename method to rename a channel that the bot created. Requires the channels:manage scope for a public channel, and the groups:write scope for a private one.
      Parameters:
      token - the (plaintext) Slack bot token
      channelId - id of the channel
      name - the new name of the channel
      Throws:
      SlackApiException - with the Slack error code (e.g. name_taken, not_authorized) if the call fails
    • joinChannel

      public void joinChannel(String token, String channelId)
      Calls the Slack conversations.join method so that the bot is a member of a public channel, which it has to be to invite or remove members. Joining a channel the bot is already in is not an error. Requires the channels:join scope.
      Parameters:
      token - the (plaintext) Slack bot token
      channelId - id of the channel
      Throws:
      SlackApiException - with the Slack error code if the call fails
    • listChannelMembers

      public List<String> listChannelMembers(String token, String channelId)
      Calls the Slack conversations.members method (following pagination). Requires the channels:read scope for a public channel, and the groups:read scope for a private one.
      Parameters:
      token - the (plaintext) Slack bot token
      channelId - id of the channel
      Returns:
      the Slack user ids of the members of the channel
      Throws:
      SlackApiException - with the Slack error code if the call fails
    • inviteToChannel

      public void inviteToChannel(String token, String channelId, List<String> userIds)
      Calls the Slack conversations.invite method to add users to a channel that the bot is a member of. Slack adds either all of the users or none of them. Requires the channels:manage scope for a public channel, and the groups:write scope for a private one.
      Parameters:
      token - the (plaintext) Slack bot token
      channelId - id of the channel
      userIds - Slack user ids; at most 1000
      Throws:
      SlackApiException - with the Slack error code (e.g. already_in_channel) if the call fails
    • removeFromChannel

      public void removeFromChannel(String token, String channelId, String userId)
      Calls the Slack conversations.kick method to remove a user from a channel that the bot is a member of. Requires the channels:manage scope for a public channel, and the groups:write scope for a private one. Whether the bot is allowed to remove members is also a workspace setting; if it is not, Slack answers RESTRICTED_ACTION, and for public channels REMOVAL_RESTRICTED_ADVICE says how to fix that.
      Parameters:
      token - the (plaintext) Slack bot token
      channelId - id of the channel
      userId - Slack user id
      Throws:
      SlackApiException - with the Slack error code (e.g. restricted_action) if the call fails