sym.sdk.integrations.slack¶
Helpers for interacting with a Slack workspace.
Functions
|
A reference to a Slack channel. |
|
Returns a |
|
Get information about a Slack user. |
|
A reference to a Slack group DM. |
|
Check if the provided |
|
Returns a list of all users in the workspace. |
|
Returns a string that mentions a Slack user given their identifier. |
|
Sends a simple message to a destination in Slack. |
|
Sends a simple message as a threaded reply to the current request message in Slack. |
|
A reference to a Slack user. |
|
Retrieves the users in a given Slack channel as a list of |
- sym.sdk.integrations.slack.channel(name: str, allow_self: bool = False, timeout: Optional[int] = None) Union[sym.sdk.request_destination.SlackChannelID, sym.sdk.request_destination.SlackChannelName] ¶
A reference to a Slack channel.
- Parameters
name – The unique channel name or channel ID. (e.g. ‘#sym-requests’ or ‘C12345’).
allow_self – A boolean indicating whether the requester may approve this Request.
timeout – An integer representing the number of seconds for the request to remain active for this user. After timeout elapses, the request message will expire and can no longer be interacted with.
- sym.sdk.integrations.slack.fallback(*destinations: sym.sdk.request_destination.RequestDestination, continue_on_delivery_failure: Optional[bool] = True, continue_on_timeout: Optional[bool] = False) sym.sdk.request_destination.RequestDestinationFallback ¶
Returns a
RequestDestinationFallback
that contains the specifiedRequestDestination
objects, with continue_on_delivery_failure=True.If used as the return value of a get_approvers reducer, when a Sym Request is made, each
RequestDestination
will be attempted in sequence until one succeeds.For example:
def get_approvers(event): return slack.fallback(slack.channel("#missing"), slack.user("@david"))
- Parameters
destinations – At least 2
RequestDestination
objects.continue_on_delivery_failure – A boolean representing whether to deliver to the next destination if a failure occurs while delivering to the current destination.
continue_on_timeout – A boolean representing whether to deliver to the next destination if the Request at the current destination times out.
- sym.sdk.integrations.slack.get_user_info(user: sym.sdk.user.User) dict ¶
Get information about a Slack user.
Refer to Slack’s users.info API documentation for the details on the response format: https://api.slack.com/methods/users.info
- Parameters
user – A Sym
User
instance to get info about.
- sym.sdk.integrations.slack.group(users: Sequence[Union[str, sym.sdk.user.User]], allow_self: bool = False, timeout: Optional[int] = None) sym.sdk.request_destination.SlackUserGroup ¶
A reference to a Slack group DM.
- Parameters
users – A list of Slack Users to include in the group. Users can be specified with a Slack user ID, email, a string version of an @mention. (e.g. “U12345”, “jane@symops.io”, “@Jane Austen”, or a Sym
User
instance).timeout – An integer representing the number of seconds for the request to remain active for this user. After timeout elapses, the request message will expire and can no longer be interacted with.
- sym.sdk.integrations.slack.is_user_in_group(user: sym.sdk.user.User, *, group_id: str) bool ¶
Check if the provided
User
is a member of the Slack user group specified.Login to Slack via web and retrieve the Slack user group ID in the left menu bar: More -> People & user groups -> User groups and select your user group. You can see the Slack user group ID in the URL:
https://app.slack.com/client/{workspaceID}/browse-user-groups/user_groups/{usergroupID}
.If you have installed the Sym app before Aug 22nd 2023, then you may need to reinstall the Sym app to use this feature. Refer to the main docs for more details.
- Parameters
user – The
User
to check group membership of.group_id – The ID of the Slack user group in which to search for the user.
- sym.sdk.integrations.slack.list_users(active_only: bool = True) list ¶
Returns a list of all users in the workspace.
Refer to Slack’s users.info API documentation for the details on the response format: https://api.slack.com/methods/users.list
- Parameters
active_only – A boolean indicating whether to exclude deactivated and deleted users.
- sym.sdk.integrations.slack.mention(identifier: Union[str, sym.sdk.user.User]) str ¶
Returns a string that mentions a Slack user given their identifier.
Users can be specified with a Slack user ID, email, a string version of an @mention. (e.g. “U12345”, “jane@symops.io”, “@Jane Austen”, or a Sym
User
instance).
- sym.sdk.integrations.slack.send_message(destination: Union[sym.sdk.user.User, sym.sdk.request_destination.RequestDestination], message: str) None ¶
Sends a simple message to a destination in Slack. Accepts either a
User
or aRequestDestination
, which may represent a user, group, or channel in Slack.For example:
# To send to #general: slack.send_message(slack.channel("#general"), "Hello, world!") # To DM a specific user: slack.send_message(slack.user("me@symops.io"), "It works!") # To DM the user who triggered an event: slack.send_message(event.user, "You did a thing!")
- Parameters
destination – Where the message should go.
message – The text contents of the message to send.
- sym.sdk.integrations.slack.send_thread_message(message: str) None ¶
Sends a simple message as a threaded reply to the current request message in Slack.
- Parameters
message – The text contents of the message to send.
- Raises
SlackError – If the current request was not sent to Slack via get_request_notifications or get_approvers, so there is no message to reply to.
- sym.sdk.integrations.slack.user(identifier: Union[str, sym.sdk.user.User], allow_self: bool = False, timeout: Optional[int] = None) sym.sdk.request_destination.SlackUser ¶
A reference to a Slack user.
- Parameters
identifier – The unique Slack user ID, email, or @mention for a Slack user, or a Sym
User
instance. (e.g. “U12345”, “jane@symops.io”, “@Jane Austen”).allow_self – A boolean indicating whether the requester may approve this Request.
timeout – An integer representing the number of seconds for the request to remain active for this user. After timeout elapses, the request message will expire and can no longer be interacted with.
- sym.sdk.integrations.slack.users_in_channel(channel: Union[sym.sdk.request_destination.SlackChannelID, sym.sdk.request_destination.SlackChannelName, str]) List[sym.sdk.user.User] ¶
Retrieves the users in a given Slack channel as a list of
User
objects.“Channel” here includes all Slack conversation types, including public and private channels as well as groups.
The
channel
argument can either be given as the output of thechannel()
function, or as a string containing a Slack channel name or ID. If a channel name is given in a string, it must be prefixed with#
.The output is a list of
User
objects, suitable for use in other areas of the Sym SDK. For example, to easily restrict the ability to approve or deny requests (including in the Sym webapp) to members of a Slack channel, one can use:@reducer def get_permissions(event): return RequestPermission( webapp_view=PermissionLevel.MEMBER, approve_deny=user_ids(slack.users_in_channel("#managers")), allow_self_approval=False )
However, please see the “Cautions” below for some important caveats when using this function.
(For more information on the
get_permissions()
reducer, please see the docs.)Cautions:
Using this function introduces a hard dependency on Slack in your Sym Flow, which may have unintended effects; for example, during a Slack outage when the Slack API is unavailable. If you must use this function in such a way, wrap the call in a
try
/except
block and include backup logic in theexcept
block. In the above example, you may wish to setapprove_deny=PermissionLevel.ADMIN
in theexcept
block, for instance, so that admins can still action requests in the webapp even if Slack is down.This function may cause your Flow to experience a reducer timeout for large Slack channels, or if your Slack workspace has a very large number of total users or total channels. Test your usage to ensure that it works as expected. Using a channel ID instead of a channel name may improve performance.
To use this function with a private channel, the Sym app for Slack must be a member of that channel; otherwise, this function will raise a channel not found exception.
If this function is used with a Slack Connect channel or in a channel containing Slack guest users, any users from outside your organization will be included in the output.
- Parameters
channel – A
SlackChannelID
,SlackChannelName
, or string representing the channel ID or name.- Returns
A list of User objects representing the users in the channel, or an empty list if the channel is empty.
- Raises
SlackError – If the channel is not found or another error occurs while interacting with the Slack API.