Merge pull request #430 from shaydewael/add-shortcuts-documentation

Add documentation for global shortcuts
slackapi · Mar 18, 2020 · 862efb7 · 862efb7
2 parents 0bfd4f8 + edf7650
commit 862efb7
Show file tree

Hide file tree

Showing 18 changed files with 154 additions and 19 deletions.
diff --git a/README.md b/README.md
@@ -38,9 +38,12 @@ app.event(eventType, fn);
 
 // Listen for an action from a block element (buttons, menus, etc)
 app.action(actionId, fn);
-// Listen for dialog submission, message action, or legacy action
+// Listen for dialog submission, message shortcut, or legacy action
 app.action({ callback_id: callbackId }, fn);
 
+// Listen for a global shortcut
+app.shortcut(callbackId, fn);
+
 // Listen for a slash command
 app.command(commandName, fn);
 
@@ -142,7 +145,7 @@ soon as possible.
 
 Depending on the type of incoming event a listener is meant for, `ack()` should be called with a parameter:
 
-*  Block actions and message actions: Call `ack()` with no parameters.
+*  Block actions, global shortcuts, and message shortcuts: Call `ack()` with no parameters.
 
 *  Dialog submissions: Call `ack()` with no parameters when the inputs are all valid, or an object describing the
    validation errors if any inputs are not valid.

diff --git a/docs/_basic/acknowledging_requests.md b/docs/_basic/acknowledging_requests.md
@@ -1,5 +1,5 @@
 ---
-title: Acknowledging events
+title: Acknowledging incoming events
 lang: en
 slug: acknowledge
 order: 7

diff --git a/docs/_basic/ja_ listening_responding_shortcuts.md b/docs/_basic/ja_ listening_responding_shortcuts.md
@@ -0,0 +1,65 @@
+---
+title: グローバルショートカットのリスニング
+lang: ja-jp
+slug: shortcuts
+order: 8
+---
+
+<div class="section-content">
+[グローバルショートカット](https://api.slack.com/interactivity/shortcuts/using#global_shortcuts)は、テキスト入力エリアや検索バーから起動できる Slack クライアント内の UI エレメントです。`shortcut()` メソッドを使って、グローバルショートカットのイベントをリスニングすることができます。このメソッドには `callback_id` を文字列または正規表現のデータ型で設定します。
+
+グローバルショートカットのイベントは Slack へイベントを受信したことを知らせるために `ack()` メソッドで確認する必要があります。
+
+グローバルショートカットのペイロードは、ユーザーの実行アクションの確認のために[モーダルを開く](#creating-modals)などの用途に使用できる `trigger_id` を含んでいます。グローバルショートカットのペイロードは **チャンネル ID は含んでいない** ことに注意してください。もしあなたのアプリがチャンネル ID を知る必要があれば、モーダル内で [`conversations_select`](https://api.slack.com/reference/block-kit/block-elements#conversation_select) エレメントを使用できます。
+
+⚠️ [メッセージショートカット](https://api.slack.com/interactivity/shortcuts/using#message_shortcuts)はh時期続き[`action()` メソッド](#action-listening)を使用するので注意してください。**Bolt の次のメジャーバージョンからはグローバルショートカットもメッセージショートカットも両方とも `shortcut()` メソッドを使用します。**
+</div>
+
+```javascript
+// open_modal というグローバルショートカットはシンプルなモーダルを開く
+app.shortcut('open_modal', async ({ payload, ack, context }) => {
+  // グローバルショートカットリクエストの確認
+  ack();
+  try {
+    // 組み込みの WebClient を使って views.open API メソッドを呼び出す
+    const result = await app.client.views.open({
+      // `context` オブジェクトに保持されたトークンを使用
+      token: context.botToken,
+      trigger_id: payload.trigger_id,
+      view: {
+        "type": "modal",
+        "title": {
+          "type": "plain_text",
+          "text": "My App"
+        },
+        "close": {
+          "type": "plain_text",
+          "text": "Close"
+        },
+        "blocks": [
+          {
+            "type": "section",
+            "text": {
+              "type": "mrkdwn",
+              "text": "About the simplest modal you could conceive of :smile:\n\nMaybe <https://api.slack.com/reference/block-kit/interactive-components|*make the modal interactive*> or <https://api.slack.com/surfaces/modals/using#modifying|*learn more advanced modal use cases*>."
+            }
+          },
+          {
+            "type": "context",
+            "elements": [
+              {
+                "type": "mrkdwn",
+                "text": "Psssst this modal was designed using <https://api.slack.com/tools/block-kit-builder|*Block Kit Builder*>"
+              }
+            ]
+          }
+        ]
+      }
+    });
+    console.log(result);
+  }
+  catch (error) {
+    console.error(error);
+  }
+});
+```
diff --git a/docs/_basic/ja_listening_actions.md b/docs/_basic/ja_listening_actions.md
@@ -6,7 +6,7 @@ order: 5
 ---
 
 <div class="section-content">
-アプリでは、ボタンのクリック、メニューの選択、メッセージアクションなどのユーザーアクションを、 `action` メソッドを使用してリスニングすることができます。
+アプリでは、ボタンのクリック、メニューの選択、メッセージショートカットなどのユーザーアクションを、 `action` メソッドを使用してリスニングすることができます。
 
 アクションは文字列型の `action_id` または RegExp オブジェクトでフィルタリングできます。 `action_id` は、Slack プラットフォーム上のインタラクティブコンポーネントの一意の識別子として機能します。 
 

diff --git a/docs/_basic/ja_listening_modals.md b/docs/_basic/ja_listening_modals.md
@@ -2,7 +2,7 @@
 title: モーダルビューでの送信のリスニング
 lang: ja-jp
 slug: view_submissions
-order: 11
+order: 12
 ---
 
 <div class="section-content">

diff --git a/docs/_basic/ja_listening_responding_commands.md b/docs/_basic/ja_listening_responding_commands.md
@@ -2,7 +2,7 @@
 title: コマンドのリスニングと応答
 lang: ja-jp
 slug: commands
-order: 8
+order: 9
 ---
 
 <div class="section-content">

diff --git a/docs/_basic/ja_listening_responding_options.md b/docs/_basic/ja_listening_responding_options.md
@@ -2,7 +2,7 @@
 title: オプションのリスニングと応答
 lang: ja-jp
 slug: options
-order: 12
+order: 13
 ---
 
 <div class="section-content">

diff --git a/docs/_basic/ja_opening_modals.md b/docs/_basic/ja_opening_modals.md
@@ -1,8 +1,8 @@
 ---
-title: モーダルビューのオープン
+title: views.open を使ったモーダルビューのオープン
 lang: ja-jp
 slug: creating-modals
-order: 9
+order: 10
 ---
 
 <div class="section-content">

diff --git a/docs/_basic/ja_updating_pushing_modals.md b/docs/_basic/ja_updating_pushing_modals.md
@@ -2,7 +2,7 @@
 title: モーダルビューの更新と多重表示
 lang: ja-jp
 slug: updating-pushing-views
-order: 10
+order: 11
 ---
 
 <div class="section-content">

diff --git a/docs/_basic/listening_actions.md b/docs/_basic/listening_actions.md
@@ -6,7 +6,7 @@ order: 5
 ---
 
 <div class="section-content">
-Your app can listen to user actions like button clicks, menu selects, and message actions using the `action` method.
+Your app can listen to user actions like button clicks, menu selects, and message shortcuts using the `action` method.
 
 Actions can be filtered on an `action_id` of type string or RegExp object. `action_id`s act as unique identifiers for interactive components on the Slack platform. 
 

diff --git a/docs/_basic/listening_modals.md b/docs/_basic/listening_modals.md
@@ -2,7 +2,7 @@
 title: Listening for view submissions
 lang: en
 slug: view_submissions
-order: 11
+order: 12
 ---
 
 <div class="section-content">

diff --git a/docs/_basic/listening_responding_commands.md b/docs/_basic/listening_responding_commands.md
@@ -2,7 +2,7 @@
 title: Listening and responding to commands
 lang: en
 slug: commands
-order: 8
+order: 9
 ---
 
 <div class="section-content">

diff --git a/docs/_basic/listening_responding_options.md b/docs/_basic/listening_responding_options.md
@@ -2,7 +2,7 @@
 title: Listening and responding to options
 lang: en
 slug: options
-order: 12
+order: 13
 ---
 
 <div class="section-content">

diff --git a/docs/_basic/listening_responding_shortcuts.md b/docs/_basic/listening_responding_shortcuts.md
@@ -0,0 +1,67 @@
+---
+title: Listening and responding to global shortcuts
+lang: en
+slug: shortcuts
+order: 8
+---
+
+<div class="section-content">
+[Global shortcuts](https://api.slack.com/interactivity/shortcuts/using#global_shortcuts) are invokable UI elements within Slack clients, available in the composer and search menus. Your app can use the `shortcut()` method to listen to incoming global shortcut events. The method requires a `callback_id` parameter of type `string` or `RegExp`.
+
+Global shortcuts must be acknowledged with `ack()` to inform Slack that your app has received the event.
+
+Global shortcut payloads include a `trigger_id` which an app can use to [open a modal](#creating-modals) which confirms the action the user is taking. Note that global shortcut payloads do **not** include a channel ID. If your app needs access to a channel ID, you may use a [`conversations_select`](https://api.slack.com/reference/block-kit/block-elements#conversation_select) element within a modal.
+
+⚠️ Note that [message shortcuts](https://api.slack.com/interactivity/shortcuts/using#message_shortcuts) still require apps to use the [`action()` method](#action-listening). **In the next major version of Bolt, both global and message shortcuts will use the `shortcut()` method.**
+</div>
+
+```javascript
+// The open_modal shortcut opens a plain old modal
+app.shortcut('open_modal', async ({ payload, ack, context }) => {
+  // Acknowledge global shortcut request
+  ack();
+
+  try {
+    // Call the views.open method using the built-in WebClient
+    const result = await app.client.views.open({
+      // The token you used to initialize your app is stored in the `context` object
+      token: context.botToken,
+      trigger_id: payload.trigger_id,
+      view: {
+        "type": "modal",
+        "title": {
+          "type": "plain_text",
+          "text": "My App"
+        },
+        "close": {
+          "type": "plain_text",
+          "text": "Close"
+        },
+        "blocks": [
+          {
+            "type": "section",
+            "text": {
+              "type": "mrkdwn",
+              "text": "About the simplest modal you could conceive of :smile:\n\nMaybe <https://api.slack.com/reference/block-kit/interactive-components|*make the modal interactive*> or <https://api.slack.com/surfaces/modals/using#modifying|*learn more advanced modal use cases*>."
+            }
+          },
+          {
+            "type": "context",
+            "elements": [
+              {
+                "type": "mrkdwn",
+                "text": "Psssst this modal was designed using <https://api.slack.com/tools/block-kit-builder|*Block Kit Builder*>"
+              }
+            ]
+          }
+        ]
+      }
+    });
+
+    console.log(result);
+  }
+  catch (error) {
+    console.error(error);
+  }
+});
+```
diff --git a/docs/_basic/opening_modals.md b/docs/_basic/opening_modals.md
@@ -1,8 +1,8 @@
 ---
-title: Opening modals
+title: Opening modals using views.open
 lang: en
 slug: creating-modals
-order: 9
+order: 10
 ---
 
 <div class="section-content">

diff --git a/docs/_basic/updating_pushing_modals.md b/docs/_basic/updating_pushing_modals.md
@@ -2,7 +2,7 @@
 title: Updating and pushing views
 lang: en
 slug: updating-pushing-views
-order: 10
+order: 11
 ---
 
 <div class="section-content">

diff --git a/docs/_tutorials/getting_started.md b/docs/_tutorials/getting_started.md
@@ -188,7 +188,7 @@ This is a basic example, but it gives you a place to start customizing your app
 
 ### Sending and responding to actions
 
-To use features like buttons, select menus, datepickers, dialogs, and message actions, you’ll need to enable interactivity. Similar to events, you'll need to specify a URL for Slack to send the action (such as *user clicked a button*).
+To use features like buttons, select menus, datepickers, dialogs, and message shortcuts, you’ll need to enable interactivity. Similar to events, you'll need to specify a URL for Slack to send the action (such as *user clicked a button*).
 
 Back on your app configuration page, click on **Interactive Components** on the left side. You'll see that there's another **Request URL** box.
 

diff --git a/docs/_tutorials/ja_getting_started.md b/docs/_tutorials/ja_getting_started.md
@@ -191,7 +191,7 @@ app.message('hello', ({ message, say }) => {
 
 ### アクションの送信と応答
 
-ボタン、選択メニュー、日付ピッカー、ダイアログ、メッセージ操作などの機能を使用するには、インタラクティブ性を有効にする必要があります。イベントと同様に、Slack の URL を指定してアクション ( 「ボタン・クリック」など) を送信する必要があります。
+ボタン、選択メニュー、日付ピッカー、ダイアログ、メッセージショートカットなどの機能を使用するには、インタラクティブ性を有効にする必要があります。イベントと同様に、Slack の URL を指定してアクション ( 「ボタン・クリック」など) を送信する必要があります。
 
 アプリ設定ページに戻り、左側の  **Interactive Components**  をクリックします。**Request URL**  ボックスがもう 1 つあることがわかります。