Skip to content

Commit

Permalink
docs: show descriptions of function listener arguments
Browse files Browse the repository at this point in the history
  • Loading branch information
@zimeg
zimeg committed Dec 11, 2024
1 parent 73bd49e commit 193654c
Show file tree
Hide file tree
Showing 2 changed files with 16 additions and 16 deletions.
16 changes: 8 additions & 8 deletions docs/content/reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,15 +39,15 @@ There are a collection of constraint objects that some methods have access to. T
### Listener function arguments
Listener functions have access to a set of arguments that may change based on the method which the function is passed to. Below is an explanation of the different arguments. The below table details the different arguments and the methods they'll be accessible in.

| Argument | Description |
| :--- | :--- |
| Argument | Method | Description |
| :--- | :--- | :--- |
| `payload` | All listeners | The unwrapped contents of the incoming event, which varies based on event. This is a subset of the information included in `body` which is detailed below. `payload` is also accessible via the alias corresponding to the method name that the listener is passed to (`message`, `event`, `action`, `shortcut`, `view`, `command`, `options`) **An easy way to understand what's in a payload is to log it**, or [use TypeScript](/tutorial/using-typescript). |
| `say` | `message`, `event`, `action` `command` | Function to send a message to the channel associated with the incoming event. This argument is only available when the listener is triggered for events that contain a channel ID (the most common being `message` events). `say` accepts simple strings (for plain-text messages) and objects (for messages containing blocks). `say` returns a promise that will resolve with a [`chat.postMessage` response](https://api.slack.com/methods/chat.postMessage). If you're using an the `action` method, or an event other than `message`, you should [ensure that the event payload contains a channel ID](https://api.slack.com/events).
| `ack` | `action`, `shortcut`, `view`, `command`, `options` | Function that **must** be called to acknowledge that an incoming event was received by your app. `ack` returns a promise that resolves when complete. Read more in [Acknowledging events](/concepts/acknowledging-events)
| `client` | All listeners | Web API client that uses the token associated with that event. For single-workspace installations, the token is provided to the constructor. For multi-workspace installations, the token is returned by the `authorize` function.
| `respond` | `action`, `shortcut`, `view`, `command` | Function that responds to an incoming event **if** it contains a `response_url`. `respond` returns a promise that resolves with the results of responding using the `response_url`. For shortcuts, `respond` will **only** work for message shortcuts (not global shortcuts). For views, `respond` will **only** work when using `response_url_enabled: true` for [conversations list](https://api.slack.com/reference/block-kit/block-elements#conversation_select) and [channels list](https://api.slack.com/reference/block-kit/block-elements#channel_select) select menus in input blocks in modals.
| `context` | All listeners | Event context. This object contains data about the event and the app, such as the `botId`. Middleware can add additional context before the event is passed to listeners.
| `body` | All listeners | Object that contains the entire body of the request (superset of `payload`). Some accessory data is only available outside of the payload (such as `trigger_id` and `authorizations`).
| `say` | `message`, `event`, `action` `command` | Function to send a message to the channel associated with the incoming event. This argument is only available when the listener is triggered for events that contain a channel ID (the most common being `message` events). `say` accepts simple strings (for plain-text messages) and objects (for messages containing blocks). `say` returns a promise that will resolve with a [`chat.postMessage` response](https://api.slack.com/methods/chat.postMessage). If you're using an the `action` method, or an event other than `message`, you should [ensure that the event payload contains a channel ID](https://api.slack.com/events). |
| `ack` | `action`, `shortcut`, `view`, `command`, `options` | Function that **must** be called to acknowledge that an incoming event was received by your app. `ack` returns a promise that resolves when complete. Read more in [Acknowledging events](/concepts/acknowledging-events) |
| `client` | All listeners | Web API client that uses the token associated with that event. For single-workspace installations, the token is provided to the constructor. For multi-workspace installations, the token is returned by the `authorize` function. |
| `respond` | `action`, `shortcut`, `view`, `command` | Function that responds to an incoming event **if** it contains a `response_url`. `respond` returns a promise that resolves with the results of responding using the `response_url`. For shortcuts, `respond` will **only** work for message shortcuts (not global shortcuts). For views, `respond` will **only** work when using `response_url_enabled: true` for [conversations list](https://api.slack.com/reference/block-kit/block-elements#conversation_select) and [channels list](https://api.slack.com/reference/block-kit/block-elements#channel_select) select menus in input blocks in modals. |
| `context` | All listeners | Event context. This object contains data about the event and the app, such as the `botId`. Middleware can add additional context before the event is passed to listeners. |
| `body` | All listeners | Object that contains the entire body of the request (superset of `payload`). Some accessory data is only available outside of the payload (such as `trigger_id` and `authorizations`). |

#### Body and payload references
The structure of the `payload` and `body` is detailed on the API site:
Expand Down
16 changes: 8 additions & 8 deletions docs/i18n/ja-jp/docusaurus-plugin-content-docs/current/reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,15 +37,15 @@ Slack アプリは通常、Slack からのイベント情報を受け取った
### リスナー関数の引数 {#listener-function-arguments}
リスナー関数がアクセスできる引数は、リスナー関数が渡されるメソッドによって決まります。以下の表は、これらの引数の説明です。この表は、それぞれの引数とそれにアクセスできるメソッドの詳細をカバーします。

| 引数 | 説明 |
| :--- | :--- |
| 引数 | メソッド | 説明 |
| :--- | :--- | :--- |
| `payload` | すべてのリスナー | 受信したイベントペイロードから装飾部分などが取り除かれた本質的な内容部分。この内容や構造はイベントの種別によって異なります。このペイロード情報は下記の `body`のサブセットです。また、`payload` には、リスナーが渡されたメソッド名と同じ名前のエイリアスを使ってアクセスすることもできます（`message`、`event`、`action`、`shortcut`、`view`、`command`、`options`）。**payload の内容を簡単に確認する方法は、それを実際にログに出力してみることです**。または、[TypeScript](/tutorial/using-typescript) を使うのもよいでしょう。 |
| `say` | `message`, `event`, `action`, `command` | 受信したイベントが紐づいているチャンネルにメッセージを送信する関数。この引数が使用できるのは、リスナーをトリガーしたイベントにチャンネル ID が含まれる場合のみです（`message` イベントが最も一般的です）。`say` は、シンプルな文字列（プレーンテキストのメッセージ）またはオブジェクト（ブロックを含むメッセージ）を受け付けます。`say` は Promise を返します。この Promise は [`chat.postMessage` の応答でresolveされます](https://api.slack.com/methods/chat.postMessage)。もし`action` メソッドや、`message` 以外のイベントを使用する場合は、[イベントの payload にチャンネル ID が含まれているかを確認するようにしてください](https://api.slack.com/events)。
| `ack` | `action`, `shortcut`, `view`, `command`, `options` | アプリが受信イベントを受け取ったことを確認するために呼び出す**必要のある関数**。`ack` は応答の完了時にresolveする Promise を返します。詳しくは、[イベントの確認](#acknowledging-events)を参照してください。
| `client` | すべてのリスナー | イベントに関連づけられたトークンを使用する Web API クライアント。単一のワークスペースへのインストールでは、トークンは Appのコンストラクターに提供されます。複数のワークスペースへのインストールでは、トークンは `authorize` 関数から返されます。
| `respond` | `action`, `shortcut`, `view`, `command` | 受信イベントに `response_url` が**含まれる場合**に、受信イベントに応答を返す関数。`respond` は Promise を返します。この Promise は、`response_url` の応答結果に resolveされます。ショートカットに関しては、`respond` はメッセージショートカットで**のみ**動作します（グローバルショートカットでは動作しません）。ビューでの `respond` は モーダル内の input ブロックの [conversations list](https://api.slack.com/reference/block-kit/block-elements#conversation_select) や [channels list](https://api.slack.com/reference/block-kit/block-elements#channel_select) のセレクトメニューで `response_url_enabled: true` というオプションが指定されている場合**のみ**動作します。
| `context` | すべてのリスナー | イベントのコンテキスト。このオブジェクトは、`botId` など、イベントやアプリに関するデータを保持します。イベントがリスナーに渡される前に、ミドルウェアで他のコンテキスト情報を追加することもできます。
| `body` | すべてのリスナー | リクエストの `body` 全体を保持するオブジェクト（`payload` のスーパーセット）。`trigger_id` や `authorizations` など、一部の付帯的なデータは payload の外側でのみ利用できます。
| `say` | `message`, `event`, `action`, `command` | 受信したイベントが紐づいているチャンネルにメッセージを送信する関数。この引数が使用できるのは、リスナーをトリガーしたイベントにチャンネル ID が含まれる場合のみです（`message` イベントが最も一般的です）。`say` は、シンプルな文字列（プレーンテキストのメッセージ）またはオブジェクト（ブロックを含むメッセージ）を受け付けます。`say` は Promise を返します。この Promise は [`chat.postMessage` の応答でresolveされます](https://api.slack.com/methods/chat.postMessage)。もし`action` メソッドや、`message` 以外のイベントを使用する場合は、[イベントの payload にチャンネル ID が含まれているかを確認するようにしてください](https://api.slack.com/events)。 |
| `ack` | `action`, `shortcut`, `view`, `command`, `options` | アプリが受信イベントを受け取ったことを確認するために呼び出す**必要のある関数**。`ack` は応答の完了時にresolveする Promise を返します。詳しくは、[イベントの確認](#acknowledging-events)を参照してください。 |
| `client` | すべてのリスナー | イベントに関連づけられたトークンを使用する Web API クライアント。単一のワークスペースへのインストールでは、トークンは Appのコンストラクターに提供されます。複数のワークスペースへのインストールでは、トークンは `authorize` 関数から返されます。|
| `respond` | `action`, `shortcut`, `view`, `command` | 受信イベントに `response_url` が**含まれる場合**に、受信イベントに応答を返す関数。`respond` は Promise を返します。この Promise は、`response_url` の応答結果に resolveされます。ショートカットに関しては、`respond` はメッセージショートカットで**のみ**動作します（グローバルショートカットでは動作しません）。ビューでの `respond` は モーダル内の input ブロックの [conversations list](https://api.slack.com/reference/block-kit/block-elements#conversation_select) や [channels list](https://api.slack.com/reference/block-kit/block-elements#channel_select) のセレクトメニューで `response_url_enabled: true` というオプションが指定されている場合**のみ**動作します。 |
| `context` | すべてのリスナー | イベントのコンテキスト。このオブジェクトは、`botId` など、イベントやアプリに関するデータを保持します。イベントがリスナーに渡される前に、ミドルウェアで他のコンテキスト情報を追加することもできます。 |
| `body` | すべてのリスナー | リクエストの `body` 全体を保持するオブジェクト（`payload` のスーパーセット）。`trigger_id` や `authorizations` など、一部の付帯的なデータは payload の外側でのみ利用できます。 |

#### body と payload について

Expand Down

0 comments on commit 193654c

Please sign in to comment.