slackapptk 2.0.3

Toolkit for creating Slack apps

Python3 Toolkit for building Slack apps

The slackapptk package is used to facilitate the development of Slack applications using Python3 and your choice of web frameworks. As a developer of Slack apps in Python, I want a library that would allow me to accomplish two primary goals:

1. Provide a mechanism to route messages received from api.slack.com to the proper code in my app. This process is sometimes referred to callback routing.

2. Create /slash-commands with a rich set of feature capabiltiies as found using the Python standard argparse package.

NOTE: The slapapptk package uses the Slack provided slackclient package and is not meant to be a replacement. That said, there are widgets defined in slackapptk.web that are not yet available in slackclient; and as slackclient is updated these widgets will be depreciated

NOTE: For SlackClient <= 2.5

If you are looking to develop on the Slack Client 2.5.0 release, please use the branch v1.

TLDR; See working example

The documentation for using slackapptk is currently under development. That said you can find a complete working example that uses the Flask web-framework in example-slackapp; see that README.md more details.

Overview

A Slack app can receive messages from api.slack.com for a number of reasons and depending on the way the app was configured in the api.slack.com portal.

For the purpose of this README the term entrypoint will be used:

• User entered a /slash-command
• User initiaties some kind of interactivity request, for example clicking a button
• User actuates a dropdown and the app has to fetch data from an external source
• User selected an action attached to a Slack message
• App receives a Slack Event as a result of its configured subscriptions

The term request will refer to the message recieved from api.slack.com as a result of any of these entrpoints.

When the app is configured in the api.slack.com portal, the developer will identify the specific app API routes to invoke. The developer would then need to write the prerequist code handlers using their API framework of choice, Flask for example.

To create a an app instance:

from slackapptk.app import SlackApp

app = SlackApp()
app.config.token = "<My app bot token value>"
app.config.signing_secret = "<My app signing secret"

You can bind your application specific code to handle inbound api.slack.com messages using the following:

• app.ic.<interactive-component>.on - where is one of the following

  • block_actions - to bind callbacks for block action request
  • select - to bind callbacks for external menu select population
  • view - to bind callbacks for View submission
  • view_closed - to bind callbacks for View closed
  • imsg - to bind callbacks to interactive message attachaments (outmoded)
  • dialog - to bind callbacks to Dialog submit (outmoded)

• app.commands.register - to register your /slash-command parser and callback handler

• app.events - to register all for any Event subscriptions

To process inbound messages from api.slack.com you will need to call one of the app handlers from the context of the API route handler. For example, if you defined an API route handler for one of your /slash-commands, you would call app.handler_slash_command() to process ihe message.

Example

A primary motivator for slackapptk is to receive the request and direct it to the app entrypoint handler that is specific to the request payload. Consider an example where the app presents the User with a surface that contains a button, and the User clicks on that button. The app code creates the button in a block, and then binds that block ID to the app "interactive component" handler for block IDs, as shown in this code snippet:

from slack.web.classes.blocks import SectionBlock
from slack.web.classes.elements import ButtonElement

from slackapptk.app import SlackApp
from slackapptk.request.interactive import BlockActionRequest, ActionEvent
from slackapptk.response import Response

def demo(app: SlackApp):

    # this function uses the provided app to send a message to the User so that
    # they can click a button.  Note this is an incomplete example, but used to
    # show the machanics of the of the entrypoint bind / callback mechanism.

    block = SectionBlock(
        block_id='this is the block id',
        text='Click the button and see what happens',
        accessory=ButtonElement(
            text='Click Me',
            action_id='button action id',
            value='10'
        )
    ) 

    # register the block-id callback to the function for handling when the User
    # clicks the button.  

    app.ic.block_actions.on(block.block_id, on_block_button)

    # ... assume some code that sends the above block in a Slack
    # surface like a message or modal view ...


def on_block_button(
    rqst: BlockActionRequest,
    action: ActionEvent
):
    # this function is called when the app receives the request message from
    # api.slack.com when the User clicked the button.

    # send a message back to the User indicating the value of the button

    resp = Response(rqst)
    resp.send("button pressed, block vlaue is: %s", action.value)

The registration / callback mechanism could also be coded as a decorator, for example:

    @app.ic.block_actions.on(block.block_id)
    def on_block_button(
        rqst: BlockActionRequest,
        action: ActionEvent
    ):
        # this function is called when the app receives the request message from
        # api.slack.com when the User clicked the button.

        # send a message back to the User indicating the value of the button

        resp = Response(rqst)
        resp.send("button pressed, block vlaue is: %s", action.value)