From 18d0229d10496753d0c312152d913261241d16d3 Mon Sep 17 00:00:00 2001
From: "slackapi[bot]" <186980925+slackapi[bot]@users.noreply.github.com>
Date: Thu, 3 Apr 2025 10:28:36 -0700
Subject: [PATCH] docs: organize documentation as markdown files to match web
 pages (#422)

Co-authored-by: lukegalbraithrussell <31357343+lukegalbraithrussell@users.noreply.github.com>
---
 docs/additional-configurations.md             | 116 ++++++++++++++
 .../direct-message-author.md                  |  13 ++
 .../invite-usergroup-to-channel.md            |  13 ++
 .../sending-data-slack-api-method.md          | 145 ++++++++++++++++++
 .../post-blocks-found-in-file.md              |  19 +++
 .../post-inline-block-message.md              |  13 ++
 .../post-inline-text-message.md               |  13 ++
 .../sending-data-slack-incoming-webhook.md    |  51 ++++++
 .../format-generated-files.md                 |  31 ++++
 .../post-release-announcements.md             |  30 ++++
 .../sending-data-webhook-slack-workflow.md    |  78 ++++++++++
 .../update-a-channel-topic.md                 |  25 +++
 docs/sending-techniques/sending-techniques.md |  55 +++++++
 docs/sending-variables.md                     |   0
 docs/slack-github-action.md                   |  32 ++++
 15 files changed, 634 insertions(+)
 create mode 100644 docs/additional-configurations.md
 create mode 100644 docs/sending-techniques/sending-data-slack-api-method/direct-message-author.md
 create mode 100644 docs/sending-techniques/sending-data-slack-api-method/invite-usergroup-to-channel.md
 create mode 100644 docs/sending-techniques/sending-data-slack-api-method/sending-data-slack-api-method.md
 create mode 100644 docs/sending-techniques/sending-data-slack-incoming-webhook/post-blocks-found-in-file.md
 create mode 100644 docs/sending-techniques/sending-data-slack-incoming-webhook/post-inline-block-message.md
 create mode 100644 docs/sending-techniques/sending-data-slack-incoming-webhook/post-inline-text-message.md
 create mode 100644 docs/sending-techniques/sending-data-slack-incoming-webhook/sending-data-slack-incoming-webhook.md
 create mode 100644 docs/sending-techniques/sending-data-webhook-slack-workflow/format-generated-files.md
 create mode 100644 docs/sending-techniques/sending-data-webhook-slack-workflow/post-release-announcements.md
 create mode 100644 docs/sending-techniques/sending-data-webhook-slack-workflow/sending-data-webhook-slack-workflow.md
 create mode 100644 docs/sending-techniques/sending-data-webhook-slack-workflow/update-a-channel-topic.md
 create mode 100644 docs/sending-techniques/sending-techniques.md
 create mode 100644 docs/sending-variables.md
 create mode 100644 docs/slack-github-action.md

diff --git a/docs/additional-configurations.md b/docs/additional-configurations.md
new file mode 100644
index 0000000..0d99651
--- /dev/null
+++ b/docs/additional-configurations.md
@@ -0,0 +1,116 @@
+# Additional configurations
+
+There are some additional, possibly useful, customization options for workflows.
+
+## Exiting with errors
+
+Invalid API requests or unexpected webhook payloads cause a failing response that can be used to fail the GitHub Actions step with the `errors` option.
+
+The `errors` option defaults to `false` so failed requests do not cause the step to fail. This result can still be gathered from the `ok` output.
+
+```yaml
+- name: Attempt to call an unknown method
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    errors: true
+    method: chat.reverse
+    token: ${{ secrets.SLACK_BOT_TOKEN }}
+    payload: |
+      text: "palindrome"
+```
+
+Invalid inputs to the GitHub Action, such as not including a payload, will always cause the GitHub step to fail.
+
+## Flattening nested payloads
+
+Variables and data provided in the payload might contain nested fields that need to be flattened before being sent with a [webhook trigger](/slack-github-action/sending-techniques/sending-data-webhook-slack-workflow) to match the expected input format of [Workflow Builder](https://slack.com/features/workflow-automation).
+
+The `payload-delimiter` option will flatten the input payload using the provided delimiter and will also make values stringified:
+
+```yaml
+- name: Flatten the default GitHub payload
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    payload-delimiter: "_"
+    webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
+    webhook-type: webhook-trigger
+```
+
+Reference to the flattening implementation is available for exploration from within the [`flat`](https://www.npmjs.com/package/flat) package.
+
+## Parsing templated variables
+
+Additional variables provided in the Github event [context](https://github.com/actions/toolkit/blob/main/packages/github/src/context.ts#L6) and event [payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads) can be used to replace templated variables in the input payload with the `payload-templated` option:
+
+```yaml
+- name: Send custom JSON data to Slack workflow
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    payload-file-path: "./payload-slack-content.json"
+    payload-templated: true
+    webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
+    webhook-type: webhook-trigger
+```
+
+This replaces variables templated as `${{ github.payload.repository.html_url }}` with the values found in the GitHub Action event [payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads).
+
+## Proxying HTTPS requests
+
+If you need to use a proxy to connect to Slack, you can use the `proxy` option. In this example we use the technique that calls a Slack API method, but configuring a proxy is the same for all techniques:
+
+```yaml
+- name: Post to a Slack channel via a proxy
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    method: chat.postMessage
+    proxy: "http://proxy.example.org:8080" # Change this to a custom value
+    token: ${{ secrets.SLACK_BOT_TOKEN }}
+    payload: |
+      channel: ${{ secrets.SLACK_CHANNEL_ID }}
+      text: "This message was sent through a proxy"
+```
+
+The `proxy` option can also be provided with the `HTTPS_PROXY` or `https_proxy` [environment variable](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) from within the GitHub Actions step.
+
+## Retrying failed requests
+
+Sometimes outgoing requests fail due to [rate limits](https://api.slack.com/apis/rate-limits) or similar [HTTP responses](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) and can be retried later.
+
+The `retries` option can be configured to the needs of your workflow with one of these values:
+
+- `0`: No retries, just hope that things go alright.
+- `5`: Five retries in five minutes. **Default**.
+- `10`: Ten retries in about thirty minutes.
+- `RAPID`: A burst of retries to keep things running fast.
+
+```yaml
+- name: Attempt a burst of requests
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    method: chat.postMessage
+    retries: RAPID
+    token: ${{ secrets.SLACK_BOT_TOKEN }}
+    payload: |
+      channel: ${{ secrets.SLACK_CHANNEL_ID }}
+      text: "status: all things are going good"
+```
+
+Behind the scenes, [automatic retries](https://tools.slack.dev/node-slack-sdk/web-api/#automatic-retries) are handled with the [`@slack/web-api`](https://tools.slack.dev/node-slack-sdk/web-api) package for Slack API methods, and [`axios-retry`](https://www.npmjs.com/package/axios-retry) when sending with a webhook.
+
+## Sending to a custom API URL
+
+In certain circumstances, such as testing the sent payload, a [custom API URL](https://tools.slack.dev/node-slack-sdk/web-api/#custom-api-url) can be used to change where `method` requests are sent:
+
+```yaml
+- name: Send to a custom API URL
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    api: http://localhost:8080
+    method: chat.postMessage
+    token: ${{ secrets.SLACK_BOT_TOKEN }}
+    payload: |
+      channel: ${{ secrets.SLACK_CHANNEL_ID }}
+      text: "What's happening on localhost?"
+```
+
+The default value of `api` is `https://slack.com/api/` for steps using `method`.
\ No newline at end of file
diff --git a/docs/sending-techniques/sending-data-slack-api-method/direct-message-author.md b/docs/sending-techniques/sending-data-slack-api-method/direct-message-author.md
new file mode 100644
index 0000000..92f2d2f
--- /dev/null
+++ b/docs/sending-techniques/sending-data-slack-api-method/direct-message-author.md
@@ -0,0 +1,13 @@
+# Example workflow: direct message the author
+
+This workflow sends a direct message to the user that pushed the most recent commits.
+
+This example uses the email of the pusher to find the user to send a message to.
+
+## Files
+
+### GitHub Actions workflow
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_2_Slack_API_Method/author.yml
+```
\ No newline at end of file
diff --git a/docs/sending-techniques/sending-data-slack-api-method/invite-usergroup-to-channel.md b/docs/sending-techniques/sending-data-slack-api-method/invite-usergroup-to-channel.md
new file mode 100644
index 0000000..a5d183e
--- /dev/null
+++ b/docs/sending-techniques/sending-data-slack-api-method/invite-usergroup-to-channel.md
@@ -0,0 +1,13 @@
+# Example workflow: invite a usergroup to channel
+
+This workflow creates a channel after a bug is reported and add members of a usergroup.
+
+This example chains multiple Slack API methods together to help fix bugs fast.
+
+## Files
+
+### GitHub Actions workflow
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_2_Slack_API_Method/invite.yml
+```
\ No newline at end of file
diff --git a/docs/sending-techniques/sending-data-slack-api-method/sending-data-slack-api-method.md b/docs/sending-techniques/sending-data-slack-api-method/sending-data-slack-api-method.md
new file mode 100644
index 0000000..c9a7378
--- /dev/null
+++ b/docs/sending-techniques/sending-data-slack-api-method/sending-data-slack-api-method.md
@@ -0,0 +1,145 @@
+---
+sidebar_label: Overview
+---
+
+# Sending data using a Slack API method
+
+A bot token or user token or [token of some other kind](https://api.slack.com/concepts/token-types) must be used to call one of [the Slack API methods](https://api.slack.com/methods) with this technique.
+
+## Setup
+
+Different [Slack API methods](https://api.slack.com/methods) require different [scopes](https://api.slack.com/scopes), but setup should be similar for all methods:
+
+1. [Create a Slack app](https://api.slack.com/apps/new) for your workspace or use an existing app.
+2. Depending on the Slack API [method](https://api.slack.com/methods) you wish to call, add the required **scopes** to your app under the **OAuth & Permissions** page on [app settings](https://api.slack.com/apps).
+3. Install the app to your workspace using the **Install App** page.
+4. Once your app is installed to a workspace, a new [token](https://api.slack.com/concepts/token-types) with your app's specified scopes will be minted for that workspace. It is worth noting that tokens are only valid for a single workspace! Find the token on the **OAuth & Permissions** page.
+5. Add the token as [a repository secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) called `SLACK_BOT_TOKEN` or something similar and memorable.
+6. [Add this Action as a step](https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idsteps) to your GitHub workflow and provide an input payload to send to the method.
+
+Methods that require an app configuration token should gather this token from the [app configuration token](https://api.slack.com/reference/manifests#config-tokens) settings instead of from a specific app since this token is associated with the workspace.
+
+## Usage
+
+Choosing inputs for these steps is left as an exercise for the actioneer since each of the Slack API methods requires certain values and specific parameters, but these snippets might be helpful when starting.
+
+### Posting a message with text
+
+Posting a message with the [`chat.postMessage`](https://api.slack.com/methods/chat.postMessage) method can be achieved by adding this step to a job in your GitHub workflow and inviting the bot associated with your app to the channel for posting:
+
+```yaml
+- name: Post text to a Slack channel
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    method: chat.postMessage
+    token: ${{ secrets.SLACK_BOT_TOKEN }}
+    payload: |
+      channel: ${{ secrets.SLACK_CHANNEL_ID }}
+      text: "howdy <@channel>!"
+```
+
+### Posting a message with blocks
+
+More complex message layouts, such as messages made with [Block Kit](https://api.slack.com/surfaces/messages#complex_layouts) blocks, can also be sent with one of the Slack API methods:
+
+```yaml
+- name: Post blocks to a Slack channel
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    method: chat.postMessage
+    token: ${{ secrets.SLACK_BOT_TOKEN }}
+    payload: |
+      channel: ${{ secrets.SLACK_CHANNEL_ID }}
+      text: "GitHub Action build result: ${{ job.status }}\n${{ github.event.pull_request.html_url || github.event.head_commit.url }}"
+      blocks:
+        - type: "section"
+          text:
+            type: "mrkdwn"
+            text: "GitHub Action build result: ${{ job.status }}\n${{ github.event.pull_request.html_url || github.event.head_commit.url }}"
+```
+
+### Updating a message
+
+Updating a message after it's posted can be done with the [`chat.update`](https://api.slack.com/methods/chat.update) method and chaining multiple steps together using outputs from past steps as inputs to current ones:
+
+```yaml
+- name: Initiate the deployment launch sequence
+  id: launch_sequence
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    method: chat.postMessage
+    token: ${{ secrets.SLACK_BOT_TOKEN }}
+    payload: |
+      channel: ${{ secrets.SLACK_CHANNEL_ID }}
+      text: "Deployment started :eyes:"
+      attachments:
+        - color: "dbab09"
+          fields:
+            - title: "Status"
+              short: true
+              value: "In Progress"
+- name: Countdown until launch
+  run: sleep 10
+- name: Update the original message with success
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    method: chat.update
+    token: ${{ secrets.SLACK_BOT_TOKEN }}
+    payload: |
+      channel: ${{ secrets.SLACK_CHANNEL_ID }}
+      ts: "${{ steps.launch_sequence.outputs.ts }}"
+      text: "Deployment finished! :rocket:"
+      attachments:
+        - color: "28a745"
+          fields:
+            - title: "Status"
+              short: true
+              value: "Completed"
+```
+
+### Replying to a message
+
+Posting [threaded replies to a message](https://api.slack.com/messaging/sending#threading) from a past job can be done by including the `thread_ts` attribute of the parent message in the `payload`:
+
+```yaml
+- name: Initiate a deployment
+  uses: slackapi/slack-github-action@v2.0.0
+  id: deployment_message
+  with:
+    method: chat.postMessage
+    token: ${{ secrets.SLACK_BOT_TOKEN }}
+    payload: |
+      channel: ${{ secrets.SLACK_CHANNEL_ID }}
+      text: "Deployment started :eyes:"
+- name: Conclude the deployment
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    method: chat.postMessage
+    token: ${{ secrets.SLACK_BOT_TOKEN }}
+    payload: |
+      channel: ${{ secrets.SLACK_CHANNEL_ID }}
+      thread_ts: "${{ steps.deployment_message.outputs.ts }}"
+      text: "Deployment finished! :rocket:"
+```
+
+### Uploading a file
+
+Calling [a Slack API method](https://api.slack.com/methods) with [`@slack/web-api`](https://tools.slack.dev/node-slack-sdk/web-api) makes [uploading a file](https://api.slack.com/messaging/files#upload) just another API call with all of the convenience of the [`files.uploadV2`](https://tools.slack.dev/node-slack-sdk/web-api/#upload-a-file) method:
+
+```yaml
+- name: Share a file to that channel
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    method: files.uploadV2
+    token: ${{ secrets.SLACK_BOT_TOKEN }}
+    payload: |
+      channel_id: ${{ secrets.SLACK_CHANNEL_ID }}
+      initial_comment: "the results are in!"
+      file: "./path/to/results.out"
+      filename: "results-${{ github.sha }}.out"
+```
+
+## Example workflows
+
+* [**Direct message the author**](/slack-github-action/sending-techniques/sending-data-slack-api-method/direct-message-author): Write to the Slack user with a matching email.
+* [**Invite a usergroup to channel**](/slack-github-action/sending-techniques/sending-data-slack-api-method/invite-usergroup-to-channel): Create a channel and invite members.
\ No newline at end of file
diff --git a/docs/sending-techniques/sending-data-slack-incoming-webhook/post-blocks-found-in-file.md b/docs/sending-techniques/sending-data-slack-incoming-webhook/post-blocks-found-in-file.md
new file mode 100644
index 0000000..516c280
--- /dev/null
+++ b/docs/sending-techniques/sending-data-slack-incoming-webhook/post-blocks-found-in-file.md
@@ -0,0 +1,19 @@
+# Example workflow: post blocks found in a file
+
+This workflow links to the GitHub Actions job in progress.
+
+This example uses file data when posting to an incoming webhook.
+
+## Files
+
+### Payload file being sent
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_3_Slack_Incoming_Webhook/saved.data.json
+```
+
+### GitHub Actions workflow
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_3_Slack_Incoming_Webhook/saved.gha.yml
+```
\ No newline at end of file
diff --git a/docs/sending-techniques/sending-data-slack-incoming-webhook/post-inline-block-message.md b/docs/sending-techniques/sending-data-slack-incoming-webhook/post-inline-block-message.md
new file mode 100644
index 0000000..fbc05a0
--- /dev/null
+++ b/docs/sending-techniques/sending-data-slack-incoming-webhook/post-inline-block-message.md
@@ -0,0 +1,13 @@
+# Example workflow: post an inline block message
+
+This workflow formats a response to recent adventures.
+
+This example uses incoming webhooks to post a message with Block Kit.
+
+## Files
+
+### GitHub Actions workflow
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_3_Slack_Incoming_Webhook/blocks.yml
+```
\ No newline at end of file
diff --git a/docs/sending-techniques/sending-data-slack-incoming-webhook/post-inline-text-message.md b/docs/sending-techniques/sending-data-slack-incoming-webhook/post-inline-text-message.md
new file mode 100644
index 0000000..e19ac6a
--- /dev/null
+++ b/docs/sending-techniques/sending-data-slack-incoming-webhook/post-inline-text-message.md
@@ -0,0 +1,13 @@
+# Example workflow: post an inline text message
+
+This workflow writes a line of text after a push event is received.
+
+This example uses incoming webhooks to post a plain text message.
+
+## Files
+
+### GitHub Actions workflow
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_3_Slack_Incoming_Webhook/text.yml
+```
\ No newline at end of file
diff --git a/docs/sending-techniques/sending-data-slack-incoming-webhook/sending-data-slack-incoming-webhook.md b/docs/sending-techniques/sending-data-slack-incoming-webhook/sending-data-slack-incoming-webhook.md
new file mode 100644
index 0000000..4d9cd37
--- /dev/null
+++ b/docs/sending-techniques/sending-data-slack-incoming-webhook/sending-data-slack-incoming-webhook.md
@@ -0,0 +1,51 @@
+---
+sidebar_label: Overview
+---
+
+# Sending data as a message with a Slack incoming webhook URL
+
+This technique uses this Action to post a message to a channel or direct message with [incoming webhooks](https://api.slack.com/messaging/webhooks) and a Slack app.
+
+Incoming webhooks follow the same [formatting](https://api.slack.com/reference/surfaces/formatting) patterns as other Slack messaging APIs. Posted messages can be as short as a single line of text, include additional interactivity with [interactive components](https://api.slack.com/messaging/interactivity), or be formatted with [Block Kit](https://api.slack.com/surfaces/messages#complex_layouts) to build visual components.
+
+## Setup
+
+Gather a Slack incoming webhook URL:
+
+1. [Create a Slack app](https://api.slack.com/apps/new) for your workspace or use an existing app.
+2. Add the [`incoming-webhook`](https://api.slack.com/scopes/incoming-webhook) bot scope under **OAuth & Permissions** page on [app settings](https://api.slack.com/apps).
+3. Install the app to your workspace and select a channel to notify from the **Install App** page.
+4. Create additional webhooks from the **Incoming Webhooks** page.
+5. Add the generated incoming webhook URL as [a repository secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) called `SLACK_WEBHOOK_URL`.
+6. [Add this Action as a step](https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idsteps) to your GitHub workflow and provide an input payload to send as a message.
+
+The webhook URL will resemble something like so:
+
+```txt
+https://hooks.slack.com/services/T0123456789/B1001010101/7IsoQTrixdUtE971O1xQTm4T
+```
+
+## Usage
+
+Add the collected webhook from above to a GitHub workflow and configure the step using [`mrkdwn`](https://api.slack.com/reference/surfaces/formatting) formatting values for a message or [Block Kit](https://api.slack.com/surfaces/messages#complex_layouts) blocks:
+
+```yaml
+- name: Post a message in a channel
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
+    webhook-type: incoming-webhook
+    payload: |
+      text: "*GitHub Action build result*: ${{ job.status }}\n${{ github.event.pull_request.html_url || github.event.head_commit.url }}"
+      blocks:
+        - type: "section"
+          text:
+            type: "mrkdwn"
+            text: "GitHub Action build result: ${{ job.status }}\n${{ github.event.pull_request.html_url || github.event.head_commit.url }}"
+```
+
+## Example workflows
+
+* [**Post an inline text message**](/slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/post-inline-text-message)
+* [**Post an inline block message**](/slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/post-inline-block-message)
+* [**Post blocks found in a file**](/slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/post-blocks-found-in-file)
\ No newline at end of file
diff --git a/docs/sending-techniques/sending-data-webhook-slack-workflow/format-generated-files.md b/docs/sending-techniques/sending-data-webhook-slack-workflow/format-generated-files.md
new file mode 100644
index 0000000..de86a9c
--- /dev/null
+++ b/docs/sending-techniques/sending-data-webhook-slack-workflow/format-generated-files.md
@@ -0,0 +1,31 @@
+# Example workflow: format generated files
+
+This workflow converts build outputs from earlier GitHub Action steps into a Slack message.
+
+This example uses data from a payload file to [send a message](https://tools.slack.dev/deno-slack-sdk/reference/slack-functions/send_message) to a hardcoded channel.
+
+## Files
+
+### Payload file being sent 
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_1_Slack_Workflow_Builder/builds.data.json
+```
+
+### GitHub Actions workflow
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_1_Slack_Workflow_Builder/builds.gha.yml
+```
+
+### Slack app manifest
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_1_Slack_Workflow_Builder/builds.manifest.json
+```
+
+### Slack webhook trigger
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_1_Slack_Workflow_Builder/builds.trigger.json
+```
diff --git a/docs/sending-techniques/sending-data-webhook-slack-workflow/post-release-announcements.md b/docs/sending-techniques/sending-data-webhook-slack-workflow/post-release-announcements.md
new file mode 100644
index 0000000..003efbc
--- /dev/null
+++ b/docs/sending-techniques/sending-data-webhook-slack-workflow/post-release-announcements.md
@@ -0,0 +1,30 @@
+# Example workflow: post release announcements
+
+This workflow allows you to select a channel to post news about the most recent release to.
+
+This example uses [Slack functions](https://tools.slack.dev/deno-slack-sdk/guides/creating-slack-functions) and inline inputs to do the
+following:
+
+1. Open a form to select a channel.
+2. Send a message to the selected channel.
+3. React with a `:tada:` emoji.
+
+## Files
+
+### GitHub Actions workflow 
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_1_Slack_Workflow_Builder/announcements.gha.yml
+```
+
+#### Slack app manifest
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_1_Slack_Workflow_Builder/announcements.manifest.json
+```
+
+### Slack webhook trigger
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_1_Slack_Workflow_Builder/announcements.trigger.json
+```
\ No newline at end of file
diff --git a/docs/sending-techniques/sending-data-webhook-slack-workflow/sending-data-webhook-slack-workflow.md b/docs/sending-techniques/sending-data-webhook-slack-workflow/sending-data-webhook-slack-workflow.md
new file mode 100644
index 0000000..e4cbc4c
--- /dev/null
+++ b/docs/sending-techniques/sending-data-webhook-slack-workflow/sending-data-webhook-slack-workflow.md
@@ -0,0 +1,78 @@
+---
+sidebar_label: Overview
+---
+
+# Sending data via a webhook to start a Slack workflow
+
+:::info[This technique requires [a Slack paid plan](https://slack.com/pricing) to use Workflow Builder.]
+:::
+
+This technique sends data to Slack using a webhook to start a workflow created using Slack [Workflow Builder](https://slack.com/features/workflow-automation).
+
+## Setup
+
+Start in Slack to create a Slack workflow:
+
+1. [Create a Slack workflow](https://slack.com/help/articles/360041352714-Build-a-workflow--Create-a-workflow-that-starts-outside-of-Slack) that starts from a webhook.
+2. Copy the webhook URL and [add it as a repository secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) called `SLACK_WEBHOOK_URL`.
+3. [Add this Action as a step](https://docs.github.com/en/actions/learn-github-actions/workflow-syntax-for-github-actions#jobsjob_idsteps) to your GitHub workflow and provide an input payload to send to the webhook.
+4. Configure your Slack workflow to use the payload variables sent from the GitHub Action. You can then update the steps of the Slack workflow to use these values in creative and clever ways.
+
+The webhook URL will resemble something like so:
+
+```txt
+https://hooks.slack.com/triggers/T0123456789/3141592653589/c6e6c0d868b3054ca0f4611a5dbadaf
+```
+
+## Usage
+
+Update the input payloads sent from this GitHub Action to your Slack workflow using the following options:
+
+### Sending values from the default GitHub event context
+
+In the example below, the default GitHub event [context](https://github.com/actions/toolkit/blob/main/packages/github/src/context.ts#L6) and event [payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads) associated with the job that started the GitHub workflow are sent to the provided webhook URL:
+
+```yaml
+- name: Send GitHub Action data to a Slack workflow
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    payload-delimiter: "_"
+    webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
+    webhook-type: webhook-trigger
+```
+
+Accessing variables sent to [Workflow Builder](https://slack.com/features/workflow-automation) with a webhook require that the payload variables are flattened with stringified values. Nested variables in the provided payload can be both flattened and also stringified with the `payload-delimiter` option or changed with other [configurations](/slack-github-action/additional-configurations) to match this format expected from Workflow Builder.
+
+### Providing parsed payload information as strings
+
+Provided input values for payload information are sent to the webhook URL after the job is started:
+
+```yaml
+- name: Send custom event details to a Slack workflow
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
+    webhook-type: webhook-trigger
+    payload: |
+      status: "${{ job.status }}"
+      option: "false"
+```
+
+### Gathering details of the payload from a saved file
+
+Input values for the payload to be sent can also be provided in a file, either in JSON or YAML format:
+
+```yaml
+- name: Send a saved artifact to a Slack workflow
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    payload-file-path: "./artifacts.json"
+    webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
+    webhook-type: webhook-trigger
+```
+
+## Example workflows
+
+* [**Format generated files**](/slack-github-action/sending-techniques/sending-data-webhook-slack-workflow/format-generated-files): Message outputs from prior steps.
+* [**Post release announcements**](/slack-github-action/sending-techniques/sending-data-webhook-slack-workflow/post-release-announcements): Share releases to a channel.
+* [**Update a channel topic**](/slack-github-action/sending-techniques/sending-data-webhook-slack-workflow/update-a-channel-topic): Highlight the current build status.
\ No newline at end of file
diff --git a/docs/sending-techniques/sending-data-webhook-slack-workflow/update-a-channel-topic.md b/docs/sending-techniques/sending-data-webhook-slack-workflow/update-a-channel-topic.md
new file mode 100644
index 0000000..caa6829
--- /dev/null
+++ b/docs/sending-techniques/sending-data-webhook-slack-workflow/update-a-channel-topic.md
@@ -0,0 +1,25 @@
+# Example workflow: update a channel topic
+
+This workflow shows the latest commit status in the header of a channel.
+
+This example uses the default GitHub event [context](https://github.com/actions/toolkit/blob/main/packages/github/src/context.ts#L6) and [payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads) to [update a channel topic](https://tools.slack.dev/deno-slack-sdk/reference/slack-functions/update_channel_topic).
+
+## Related files
+
+### GitHub Actions workflow
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_1_Slack_Workflow_Builder/topic.gha.yml
+```
+
+### Slack app manifest
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_1_Slack_Workflow_Builder/topic.manifest.json
+```
+
+### Slack webhook trigger
+
+```js reference
+https://github.com/slackapi/slack-github-action/blob/main/example-workflows/Technique_1_Slack_Workflow_Builder/topic.trigger.json
+```
\ No newline at end of file
diff --git a/docs/sending-techniques/sending-techniques.md b/docs/sending-techniques/sending-techniques.md
new file mode 100644
index 0000000..2e6c1e9
--- /dev/null
+++ b/docs/sending-techniques/sending-techniques.md
@@ -0,0 +1,55 @@
+---
+sidebar_label: Overview
+---
+
+# Sending techniques
+
+This GitHub Action offers three different techniques to send data to Slack:
+
+* [Send data with a webhook to start a workflow in Workflow Builder](/slack-github-action/sending-techniques/sending-data-webhook-slack-workflow).
+* [Send data using a Slack API method and a secret token with required scopes](/slack-github-action/sending-techniques/sending-data-slack-api-method/).
+* [Send data as a message with a Slack incoming webhook URL](/slack-github-action/sending-techniques/sending-data-slack-incoming-webhook/). 
+
+## Expected outputs
+
+Each technique above [outputs values](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs) that can be used as inputs in following steps of a GitHub workflow.
+
+The following outputs are returned with each of the techniques:
+
+| Output | Type  | Description|
+|---|---|---|
+|`time` | `number` | The Unix [epoch time](https://en.wikipedia.org/wiki/Unix_time) that the step completed.
+| `ok` | `boolean` | If the request completed with success.
+| `response` | `string` | The [response](https://api.slack.com/web#responses) from the request as stringified JSON.
+
+While these outputs are returned with certain Slack API methods:
+
+| Output | Type  | Description|
+|---|---|---|
+|`channel_id` | `string` | The [channel ID](https://api.slack.com/types/conversation) included in the response.
+| `ts`| `string` | The [timestamp](https://api.slack.com/messaging/retrieving#individual_messages) of the Slack event or message.
+| `thread_ts` | `string` | The [timestamp](https://api.slack.com/messaging/retrieving#individual_messages) of a parent Slack message with [threaded replies](https://api.slack.com/messaging/retrieving#finding_threads).
+
+## Example responses
+
+The following snippet shows how multiple steps can be chained together to create a Slack channel before posting a message:
+
+```yaml
+- name: Create a new Slack channel for recent changes
+  id: conversation
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    method: conversations.create
+    token: ${{ secrets.SLACK_BOT_TOKEN }}
+    payload: |
+      name: pull-request-review-${{ github.sha }}
+- name: Send the pull request link into the Slack channel
+  if: ${{ steps.conversation.outputs.ok }}
+  uses: slackapi/slack-github-action@v2.0.0
+  with:
+    method: chat.postMessage
+    token: ${{ secrets.SLACK_BOT_TOKEN }}
+    payload: |
+      channel: ${{ steps.conversation.outputs.channel_id }}
+      text: "A PR was created <!date^${{ steps.conversation.outputs.time }}^{date_num} at {time_secs}|just now>: ${{ github.event.pull_request.html_url }}"
+```
diff --git a/docs/sending-variables.md b/docs/sending-variables.md
new file mode 100644
index 0000000..e69de29
diff --git a/docs/slack-github-action.md b/docs/slack-github-action.md
new file mode 100644
index 0000000..c3ee8f7
--- /dev/null
+++ b/docs/slack-github-action.md
@@ -0,0 +1,32 @@
+# Slack Send GitHub Action
+
+The GitHub Action for sending data to Slack.
+
+## Sending variables 
+
+There are different [techniques to send data](/slack-github-action/sending-techniques) into Slack and whichever one is chosen will require a certain set of customized inputs, as described later.
+
+You can provide data to send to Slack from this GitHub Action and either source:
+
+- The default event [context](https://github.com/actions/toolkit/blob/main/packages/github/src/context.ts#L6) with a [payload](https://docs.github.com/en/webhooks/webhook-events-and-payloads) matching the GitHub event.
+- A custom payload with optional [variables](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) provided in the GitHub Action step.
+
+These input options are valid for all techniques, but some techniques require specific constraints with certain requirements for valid inputs.
+
+Additional [configurations](/slack-github-action/additional-configurations) and other details are also available for more customizations to the provided payload.
+
+## Versioning
+
+We recommend using the latest version of this GitHub Action for the most recent updates and fixes.
+
+Migration guides are available in the [release notes](https://github.com/slackapi/slack-github-action/releases) with breaking changes noted between versions.
+
+Changes required when upgrading from `@v1` to `@v2` are included in this [migration guide](https://github.com/slackapi/slack-github-action/releases/tag/v2.0.0).
+
+## License
+
+This project is licensed under the [MIT license](https://github.com/slackapi/slack-github-action/blob/main/LICENSE).
+
+## Contributing
+
+All contributions are encouraged! Check out the [contributor's guide](https://github.com/slackapi/slack-github-action/blob/main/.github/contributing.md) to learn more.
\ No newline at end of file