Salesforce Docs Portal

Sample Apex SDK for Slack App

The sample app includes a variety of view definitions and Apex handlers to demonstrate its core functionalities.

Prerequisites

Before you download the sample app, make sure you've set up the prerequisites.

Download the Sample App

There are several versions of the sample app.

  • apex-end-to-end-example-v5.zip: This file has new changes.

    • Added the TestEventDispatcherEventExample test example
    • Added the ActionDispatcherViewSelectedRecord class that handles the onsubmit event on the view_oppportunities_by_account view definition.
    • Fixed the ApexSlackApp.slackapp app definition for the reaction_added and reaction_removed events.

  • apex-end-to-end-example-v4.zip: This file has new changes.

    • Replaced the field component with mrkdwn.
    • Added the EventDispatcherEventExample class to demonstrate event support.
    • Added the test suite ApexEndToEndTestSuite.
    • Added test classes TestDataProviderAccountLookup, TestDataProviderOpportunityLookup, and TestDataProviderSObjectRecord.
    • Deleted TestOpportunityLookupDataProvider.
    • Renamed RecordDataProvider to EventDispatcherAppHomeOpened.
    • Renamed the following test classes.
      • TestAppHomeOpened is now TestEventDispatcherAppHomeOpened
      • TestCreateRecordDispatcher is now TestShortcutDispatcherCreateRecord
      • TestReactionsGetShortcutDispatcher is now TestShortcutDispatcherReactionsGet
      • TestViewOppByAccountCommandDispatcher is now TestCommandDispatcherViewOppByAccount
      • TestViewRecordCommandDispatcher is now TestCommandDispatcherViewRecord.
    • Renamed the following action dispatchers.
      • CreateRecordCommandDispatcher is now CommandDispatcherCreateRecord
      • CreateRecordShortcutDispatcher is now ShortcutDispatcherCreateRecord
      • ViewOppByAccountCommandDispatcher is now CommandDispatcherViewOppByAccount
      • ViewRecordCommandDispatcher is now ShortcutDispatcherReactionsGet.

  • apex-end-to-end-example-v3.zip: This file has new changes.

    • Added a test suite for the Apex handlers.
    • Added example classes OpportunityLookupDataProvider and ViewOppByAccountCommandDispatcher to demonstrate how to use the Select Component using List<Slack.Option> and List<Slack.OptionGroup>.

  • apex-end-to-end-example-v2.zip: Added a ReactionsGetResponse example

  • apex-end-to-end-example.zip

tip: After you download the sample app, unzip the file, and move the content of the force-app folder into your SFDX project.

Create a Slack App

After setting up your prerequisites, create a Slack app to work with your sample app.

  1. Create an app on api.slack.com and use the following app manifest.

    _metadata:
    major_version: 1
    minor_version: 1
display_information:
    name: Apex Example App
features:
    app_home:
        home_tab_enabled: true
        messages_tab_enabled: false
        messages_tab_read_only_enabled: false
    bot_user:
        display_name: apex-end-to-end-example-app
        always_online: true
    shortcuts:
        - name: apex create record
          type: message
          callback_id: apex-create-record-message
          description: apex create record global
        - name: apex create record
          type: global
          callback_id: apex-create-record-global
          description: Create a record with Apex
         - name: apex reactions get
           type: message
           callback_id: apex-reactions-get
           description: Retrieve reactions for a message with the ReactionsGet api
    slash_commands:
        - command: /apex-create-record
          url: https://slack-apps.salesforce.com:9443/a/<your-app-ID>
          description: Create a record with Apex
          should_escape: false
        - command: /apex-view-record
          url: https://slack-apps.salesforce.com:9443/a/<your-app-ID>
          description: View a record with Apex
          should_escape: false
        - command: /apex-find-opp-by-account-id
          url: https://slack-apps.salesforce.com:9443/a/<your-app-ID>
          description: view opportunities by accountId
          should_escape: false
oauth_config:
    redirect_urls:
        - https://auth.slack-apps.salesforce.com/slack_oauth_callback/<your-app-ID>
    scopes:
        user:
            - channels:read
        bot:
            - chat:write
            - commands
            - channels:history
            - groups:history
            - im:history
settings:
    event_subscriptions:
        bot_events:
            - app_home_opened
            - app_uninstalled
            - channel_rename
            - group_rename
            - reaction_added
            - reaction_removed
            - tokens_revoked
        request_url: https://slack-apps.salesforce.com:9443/a/<your-app-ID>
    interactivity:
        is_enabled: true
        message_menu_options_url: https://slack-apps.salesforce.com:9443/a/<your-app-Id>
        request_url: https://slack-apps.salesforce.com:9443/a/<your-app-ID>
    org_deploy_enabled: false
    socket_mode_enabled: false
    token_rotation_enabled: false

important: The app_uninstalled and tokens_revoked events are required if you expect to disconnect your Slack app from an org and reconnect to a different org. See Org Connections.

An app manifest enables you to create, configure, and copy your Slack apps easily. If you see an error while saving the manifest, check your indentation. For the manifest schema, see Create and configure apps with manifests.

  1. Install the app to your workspace.
  2. Update the app manifest with your app ID.

note: Alternatively, update your app ID via the OAuth & Permissions page. Under Redirect URLs, replace <your-app-id> with the app ID on the Basic Information page.

Configure the Sample App

  1. From your local SFDX directory, open slackapp/ApexSlackApp.slackapp-meta.xml.
  • Replace the appKey, appToken, clientKey, clientSecret, and signingSecret with values from the app you created on api.slack.com. The app Key (as App Id), client Key (as Client Id), client key, and client secret are available on the app's Basic Information page at api.slack.com.
  • Generate the app token under App-Level Tokens.
  1. Make sure the commands, shortcuts, and events defined in ApexSlackApp.slackapp match the values in your app manifest on api.slack.com.
  • If you're installing your app to a shared workspace, prefix your commands with a unique identifier in both places. This identifier ensures your commands don't break if another user installs a second example app to the same workspace.

tip: To use a different name for your app besides "ApexSlackApp," you can change the name of the .slackapp and .slackapp-meta.xml files, like myApp.slackapp and myApp.slackapp-meta.xml. Update any references to your app name in apex classes. For example in EventDispatcherAppHomeOpened, replace Slack.App.ApexSlackApp.get() with Slack.App.myApp.get().

Next, you can deploy your sample app to a scratch org using sf project deploy start. If you haven't set up a scratch org, see Create a Scratch Org.

Explore the Sample App

After you push your sample app to a scratch org, you can test the commands in your Slack workspace as discussed in this section.

For example, when you run /apex-create-record the first time, you get a prompt to connect your Salesforce org. Click the link and log in with your scratch org's username and password. After you successfully connect your Salesforce org, run your command again.

tip: To see your username, run sf org list. To generate a password, run sf org generate password --target-org <yourusername>@example.com.

The sample app demonstrates the following areas.

  • Slash Commands
  • Global Shortcuts
  • Message Shortcuts
  • Events
  • Test Suite

Slash Commands

The ApexSlackApp.slackapp file configures these commands and the Apex actions they call.

commands:
  /apex-create-record:
    action:
      definition: apex__action__CommandDispatcherCreateRecord
    title: Create Record Command
    description: Create a record using a slack command.
  /apex-view-record:
    action:
      definition: apex__action__CommandDispatcherViewRecord
    title: View Record Command
    description: View record details by objectApiName and recordId.
# More shortcut definitions here

/apex-create-record calls the CommandDispatcherCreateRecord Apex class to open a modal using the create_record view definition.

/apex-view-record calls the CommandDispatcherViewRecord Apex class to open a modal to view record details for Accounts, Contacts, or Opportunities using the corresponding view definitions: view_account, view_contact, or view_opportunity.

The CommandDispatcherViewRecord Apex class extends Slack.SlashCommandDispatcher to handle the slash command that's registered with the Slack app.

For example, you can enter a command like /apex-view-record Account 00Bxx0000029bnsEAA and the Apex action returns a modal described by the view_account definition.

Global Shortcuts

The ApexSlackApp.slackapp file configures a global shortcut and its Apex action.

globalShortcuts:
  apex-create-record-global:
    action:
      definition: apex__action__ShortcutDispatcherCreateRecord
    title: Create Record Global Shortcut
    description: Create a record using a slack global shortcut.

The apex-create-record-global global shortcut calls the ShortcutDispatcherCreateRecord Apex class to open a modal using the create_record view definition.

The ShortcutDispatcherCreateRecord Apex class extends Slack.ShortcutDispatcher to handle the global and message shortcuts that are registered with the Slack app.

To test out the global shortcut, press the shortcuts button in the message composer or from within search in your Slack workspace. For more information, see Shortcuts.

Message Shortcuts

The ApexSlackApp.slackapp file configures a message shortcut to call an Apex action.

messageShortcuts:
  apex-create-record-message:
    action:
      definition: apex__action__ShortcutDispatcherCreateRecord
    title: Create Record Message Shortcut
    description: Create a record using a slack message shortcut.

The apex-create-record-message message shortcut calls the ShortcutDispatcherCreateRecord Apex class to open a modal using the create_record view definition.

The ShortcutDispatcherCreateRecord Apex class extends Slack.ShortcutDispatcher to handle the slash command registered with the Slack app.

To test out the message shortcut, go to the overflow menu on a message. If the shortcut isn't available on the menu, click "More message shortcuts..." and find the shortcut by typing it in the search field in your Slack workspace.

Events

The ApexSlackApp.slackapp file configures the app_home_opened event to call an Apex action.

events:
  app_home_opened:
    action:
      definition: apex__action__EventDispatcherAppHomeOpened
    title: Example event handler for app_home_opened
    description: event fires when a user opens the home tab.
# More event definitions here

When a user clicks into the App Home tab, the EventDispatcherAppHomeOpened Apex class returns the app_home view definition.

The EventDispatcherAppHomeOpened Apex class extends Slack.EventDispatcher to handle the app_home_opened event.

Run Test Suite

The example app includes an implementation of the test harness. The ApexExampleEndToEndTestSuite test suite in force-app/main/default/testSuites contains tests for commands, shortcuts, and event handlers in the example app that are currently supported by the test harness.

To run the Apex test suite:

sf apex run test --suite-names ApexExampleEndToEndTestSuite

To run the Apex test suite with coverage:

sf apex run test --suite-names ApexExampleEndToEndTestSuite --code-coverage --result-format human

tip: See the apex run test command.

Alternatively, run the test suite in the Developer Console after logging into the scratch org.