Installation and Usage

Installation

pip install omnibot-receiver

Usage

Routing

Here’s a really basic example, that’ll route message events, and interactive commands, when received at endpoint /api/v1/bot:

 from omnibot_receiver.router import (
     OmnibotMessageRouter,
     OmnibotInteractiveRouter,
     OmnibotRouter,
 )

 message_router = OmnibotMessageRouter(
     help='This bot is used for pings and pongs.'
 )
 interactive_router = OmnibotInteractiveRouter()
 router = OmnibotRouter(
     message_router=message_router,
     interactive_router=interactive_router
 )


 @message_router.route(
     'ping',
     match_type='command',
     help='Responds to pings with pongs'
 )
 def ping(message):
     ret = {'actions': []}
     ret['actions'].append({
         'action': 'chat.postMessage',
         'kwargs': {'text': 'pong'}
     })
     return ret

@interactive_router.route('ping_callback')
def ping(event):
    ret = {'actions': []}
    ret['actions'].append({
        'action': 'chat.postMessage',
        'kwargs': {'text': 'pong'}
    })
    return ret

 @flask_app.route('/api/v1/bot', methods=['POST'])
 def pingbot_route():
     message = request.get_json()
     ret = router.handle_event(message)
     return jsonify(ret)

The above example will respond with pong, when a user sends @pingbot ping, or when an user interacts with an interactive component, which sends the ping_callback event.

Here is an example of an event payload for an interactive event (in this case, the “Continue Cleanup” button was clicked):

"event": {
    "actions": [
      {
        "action_id": "continue_cleanup",
        "action_ts": "1709149728.078244",
        "block_id": "oktabot_events",
        "style": "primary",
        "text": {
          "emoji": true,
          "text": "Continue Cleanup",
          "type": "plain_text"
        },
        "type": "button"
      }
    ],
    "bot": {
      "bot_id": "A123456",
      "name": "oktabot"
    },
    "callback_id": "oktabot_events",
    "channel": {
      "id": "C123456",
      "name": "privategroup"
    },
    "message": {
      "app_id": "A123456",
      "blocks": [
        {
          "block_id": "ZocFS",
          "text": {
            "emoji": true,
            "text": ":oktacircle: Okta Cleanup :clean:",
            "type": "plain_text"
          },
          "type": "header"
        },
        {
          "block_id": "eFD0m",
          "fields": [
            {
              "text": "*Inactive Users:*\n22",
              "type": "mrkdwn",
              "verbatim": false
            },
            {
              "text": "*Suspended Users:*\n5",
              "type": "mrkdwn",
              "verbatim": false
            },
            {
              "text": "*Service Accounts:*\n59",
              "type": "mrkdwn",
              "verbatim": false
            },
            {
              "text": "*Groups with no Apps:*\n48",
              "type": "mrkdwn",
              "verbatim": false
            },
            {
              "text": "*Groups with no Users:*\n15",
              "type": "mrkdwn",
              "verbatim": false
            },
            {
              "text": "*Inactive Apps:*\n18",
              "type": "mrkdwn",
              "verbatim": false
            },
            {
              "text": "*Apps with No Users:*\n2",
              "type": "mrkdwn",
              "verbatim": false
            },
            {
              "text": "*Apps with No Usage:*\n1",
              "type": "mrkdwn",
              "verbatim": false
            }
          ],
          "type": "section"
        },
        {
          "block_id": "oktabot_events",
          "elements": [
            {
              "action_id": "continue_cleanup",
              "style": "primary",
              "text": {
                "emoji": true,
                "text": "Continue Cleanup",
                "type": "plain_text"
              },
              "type": "button"
            },
            {
              "action_id": "cancel_cleanup",
              "style": "danger",
              "text": {
                "emoji": true,
                "text": "Cancel Cleanup",
                "type": "plain_text"
              },
              "type": "button"
            }
          ],
          "type": "actions"
        }
      ],
      "bot_id": "B123456",
      "channels": [],
      "emails": [],
      "emojis": {
        ":clean:": "clean",
        ":oktacircle:": "oktacircle"
      },
      "parsed_text": ":oktacircle: Okta Cleanup :clean: *Inactive Users:*\n22 *Suspended Users:*\n5 *Service Accounts:*\n59 *Groups with no Apps:*\n48 *Groups with no Users:*\n15 *Inactive Apps:*\n18 *Apps with No Users:*\n2 *Apps with No Usage:*\n1 Continue Cleanup button Cancel Cleanup button",
      "parsed_user": {
        "color": "2b6836",
        "deleted": false,
        "enterprise_user": {
          "enterprise_id": "11111111",
          "enterprise_name": "Lyft Org",
          "id": "12345678",
          "is_admin": false,
          "is_owner": false,
          "is_primary_owner": false,
          "teams": [
            "T123456"
          ]
        },
        "id": "11111111",
        "is_admin": false,
        "is_app_user": false,
        "is_bot": true,
        "is_email_confirmed": false,
        "is_owner": false,
        "is_primary_owner": false,
        "is_restricted": false,
        "is_ultra_restricted": false,
        "name": "oktabot",
        "profile": {
          "always_active": true,
          "api_app_id": "A123456",
          "avatar_hash": "ecbc05b8018e",
          "bot_id": "B123456",
          "display_name": "",
          "display_name_normalized": "",
          "first_name": "oktabot",
          "image_1024": "https://avatars.slack-edge.com/2020-04-10/1054481108146_ecbc05b8018e1f0a8d74_1024.jpg",
          "image_192": "https://avatars.slack-edge.com/2020-04-10/1054481108146_ecbc05b8018e1f0a8d74_192.jpg",
          "image_24": "https://avatars.slack-edge.com/2020-04-10/1054481108146_ecbc05b8018e1f0a8d74_24.jpg",
          "image_32": "https://avatars.slack-edge.com/2020-04-10/1054481108146_ecbc05b8018e1f0a8d74_32.jpg",
          "image_48": "https://avatars.slack-edge.com/2020-04-10/1054481108146_ecbc05b8018e1f0a8d74_48.jpg",
          "image_512": "https://avatars.slack-edge.com/2020-04-10/1054481108146_ecbc05b8018e1f0a8d74_512.jpg",
          "image_72": "https://avatars.slack-edge.com/2020-04-10/1054481108146_ecbc05b8018e1f0a8d74_72.jpg",
          "image_original": "https://avatars.slack-edge.com/2020-04-10/1054481108146_ecbc05b8018e1f0a8d74_original.jpg",
          "is_custom_image": true,
          "last_name": "",
          "phone": "",
          "real_name": "oktabot",
          "real_name_normalized": "oktabot",
          "skype": "",
          "status_emoji": "",
          "status_emoji_display_info": [],
          "status_expiration": 0,
          "status_text": "",
          "status_text_canonical": "",
          "team": "T123456",
          "title": ""
        },
        "real_name": "oktabot",
        "team_id": "T123456",
        "tz": "America/Los_Angeles",
        "tz_label": "Pacific Standard Time",
        "tz_offset": -28800,
        "updated": 1621408361,
        "who_can_share_contact_card": "EVERYONE"
      }
    }
}

See omnibot_receiver.router module documentation for more detailed OmnibotRouter usage.

Responding

See omnibot_receiver.response module documentation for response helper functions.