From 0c94e88b3c57825738b55936bb8d015ea59b22a0 Mon Sep 17 00:00:00 2001 From: Shane DeWael Date: Tue, 17 Mar 2020 11:33:17 -0700 Subject: [PATCH 1/5] Add shortcut documentation --- docs/_basic/acknowledging_requests.md | 2 +- docs/_basic/listening_actions.md | 2 +- docs/_basic/listening_modals.md | 2 +- docs/_basic/listening_responding_commands.md | 2 +- docs/_basic/listening_responding_options.md | 2 +- docs/_basic/listening_responding_shortcuts.md | 65 +++++++++++++++++++ docs/_basic/opening_modals.md | 4 +- docs/_basic/updating_pushing_modals.md | 2 +- docs/_tutorials/getting_started.md | 2 +- 9 files changed, 74 insertions(+), 9 deletions(-) create mode 100644 docs/_basic/listening_responding_shortcuts.md diff --git a/docs/_basic/acknowledging_requests.md b/docs/_basic/acknowledging_requests.md index 2464e86c0..078af3cf8 100644 --- 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/listening_actions.md b/docs/_basic/listening_actions.md index b77bee62f..c05bc268c 100644 --- a/docs/_basic/listening_actions.md +++ b/docs/_basic/listening_actions.md @@ -6,7 +6,7 @@ order: 5 ---
-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 index 46cbbdcf2..5f85b453e 100644 --- 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 ---
diff --git a/docs/_basic/listening_responding_commands.md b/docs/_basic/listening_responding_commands.md index 9fccd3b18..a3dea38c0 100644 --- 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 ---
diff --git a/docs/_basic/listening_responding_options.md b/docs/_basic/listening_responding_options.md index 0f5e10418..9f6ce4417 100644 --- 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 ---
diff --git a/docs/_basic/listening_responding_shortcuts.md b/docs/_basic/listening_responding_shortcuts.md new file mode 100644 index 000000000..a409d9165 --- /dev/null +++ b/docs/_basic/listening_responding_shortcuts.md @@ -0,0 +1,65 @@ +--- +title: Listening and responding to global shortcuts +lang: en +slug: shortcuts +order: 8 +--- + +
+[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 `callbackId` 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. +
+ +```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 or ." + } + }, + { + "type": "context", + "elements": [ + { + "type": "mrkdwn", + "text": "Psssst this modal was designed using " + } + ] + } + ] + } + }); + + console.log(result); + } + catch (error) { + console.error(error); + } +}); +``` diff --git a/docs/_basic/opening_modals.md b/docs/_basic/opening_modals.md index 750a7a4df..710e9f513 100644 --- 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 ---
diff --git a/docs/_basic/updating_pushing_modals.md b/docs/_basic/updating_pushing_modals.md index 1492eea8f..8e1d10eb1 100644 --- 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 ---
diff --git a/docs/_tutorials/getting_started.md b/docs/_tutorials/getting_started.md index e3001e163..c9515bf04 100644 --- 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. From 13d68c0e234bcfc57c684512d035536f21291969 Mon Sep 17 00:00:00 2001 From: Shane DeWael Date: Tue, 17 Mar 2020 11:33:36 -0700 Subject: [PATCH 2/5] Add readme --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7c192ece8..a377f8924 100644 --- 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. From dbab80a1d6f78d48e374f93ba5cd2af05fd4380e Mon Sep 17 00:00:00 2001 From: Shane DeWael Date: Tue, 17 Mar 2020 11:59:12 -0700 Subject: [PATCH 3/5] Add disclaimer --- docs/_basic/listening_responding_shortcuts.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/_basic/listening_responding_shortcuts.md b/docs/_basic/listening_responding_shortcuts.md index a409d9165..51262c5ca 100644 --- a/docs/_basic/listening_responding_shortcuts.md +++ b/docs/_basic/listening_responding_shortcuts.md @@ -10,7 +10,9 @@ order: 8 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. +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.**
```javascript From 7cf779e7e99b99869f3b714974db58ef27603da8 Mon Sep 17 00:00:00 2001 From: Kazuhiro Sera Date: Wed, 18 Mar 2020 07:17:14 +0900 Subject: [PATCH 4/5] Add Japanese shortcuts docs --- .../ja_ listening_responding_shortcuts.md | 65 +++++++++++++++++++ docs/_basic/ja_listening_actions.md | 2 +- docs/_basic/ja_listening_modals.md | 2 +- .../ja_listening_responding_commands.md | 2 +- .../_basic/ja_listening_responding_options.md | 2 +- docs/_basic/ja_opening_modals.md | 4 +- docs/_basic/ja_updating_pushing_modals.md | 2 +- docs/_tutorials/ja_getting_started.md | 2 +- 8 files changed, 73 insertions(+), 8 deletions(-) create mode 100644 docs/_basic/ja_ listening_responding_shortcuts.md diff --git a/docs/_basic/ja_ listening_responding_shortcuts.md b/docs/_basic/ja_ listening_responding_shortcuts.md new file mode 100644 index 000000000..ff76e0b4d --- /dev/null +++ b/docs/_basic/ja_ listening_responding_shortcuts.md @@ -0,0 +1,65 @@ +--- +title: グローバルショートカットのリスニング +lang: ja-jp +slug: shortcuts +order: 8 +--- + +
+[グローバルショートカット](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()` メソッドを使用します。** +
+ +```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 or ." + } + }, + { + "type": "context", + "elements": [ + { + "type": "mrkdwn", + "text": "Psssst this modal was designed using " + } + ] + } + ] + } + }); + console.log(result); + } + catch (error) { + console.error(error); + } +}); +``` diff --git a/docs/_basic/ja_listening_actions.md b/docs/_basic/ja_listening_actions.md index 5fc3b50af..c41df2626 100644 --- a/docs/_basic/ja_listening_actions.md +++ b/docs/_basic/ja_listening_actions.md @@ -6,7 +6,7 @@ order: 5 ---
-アプリでは、ボタンのクリック、メニューの選択、メッセージアクションなどのユーザーアクションを、 `action` メソッドを使用してリスニングすることができます。 +アプリでは、ボタンのクリック、メニューの選択、メッセージショートカットなどのユーザーアクションを、 `action` メソッドを使用してリスニングすることができます。 アクションは文字列型の `action_id` または RegExp オブジェクトでフィルタリングできます。 `action_id` は、Slack プラットフォーム上のインタラクティブコンポーネントの一意の識別子として機能します。 diff --git a/docs/_basic/ja_listening_modals.md b/docs/_basic/ja_listening_modals.md index 1e7e92c88..e13a7ad13 100644 --- 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 ---
diff --git a/docs/_basic/ja_listening_responding_commands.md b/docs/_basic/ja_listening_responding_commands.md index 5cde858c5..bf6c4ac67 100644 --- 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 ---
diff --git a/docs/_basic/ja_listening_responding_options.md b/docs/_basic/ja_listening_responding_options.md index 14844abb8..baf3465c9 100644 --- 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 ---
diff --git a/docs/_basic/ja_opening_modals.md b/docs/_basic/ja_opening_modals.md index fd59010a8..b0f52919a 100644 --- 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 ---
diff --git a/docs/_basic/ja_updating_pushing_modals.md b/docs/_basic/ja_updating_pushing_modals.md index 67529eb24..302a6fd55 100644 --- 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 ---
diff --git a/docs/_tutorials/ja_getting_started.md b/docs/_tutorials/ja_getting_started.md index 234bc9611..5351e41fc 100644 --- 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 つあることがわかります。 From 201468c87b5d80aad50f0308299e5f8588873252 Mon Sep 17 00:00:00 2001 From: Shane DeWael Date: Tue, 17 Mar 2020 15:22:32 -0700 Subject: [PATCH 5/5] kaz edit --- docs/_basic/listening_responding_shortcuts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_basic/listening_responding_shortcuts.md b/docs/_basic/listening_responding_shortcuts.md index 51262c5ca..be6b6d3ab 100644 --- a/docs/_basic/listening_responding_shortcuts.md +++ b/docs/_basic/listening_responding_shortcuts.md @@ -6,7 +6,7 @@ order: 8 ---
-[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 `callbackId` parameter of type `string` or `RegExp`. +[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.