docs: showcase updated use cases in example workflows (#376)

Co-authored-by: Luke Russell <[email protected]>

README.md

@@ -164,7 +164,7 @@ 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 to a Slack channel
+- name: Post text to a Slack channel
   uses: slackapi/[email protected]
   with:
     method: chat.postMessage
@@ -180,7 +180,7 @@ More complex message layouts, such as messages made with [Block Kit][block-kit]
 blocks, can also be sent with one of the Slack API methods:
 
 ```yaml
-- name: Post to a Slack channel
+- name: Post blocks to a Slack channel
   uses: slackapi/[email protected]
   with:
     method: chat.postMessage
@@ -203,7 +203,7 @@ outputs from past steps as inputs to current ones:
 
 ```yaml
 - name: Initiate the deployment launch sequence
-  id: slack
+  id: launch_sequence
   uses: slackapi/[email protected]
   with:
     method: chat.postMessage
@@ -226,7 +226,7 @@ outputs from past steps as inputs to current ones:
     token: ${{ secrets.SLACK_BOT_TOKEN }}
     payload: |
       channel: ${{ secrets.SLACK_CHANNEL_ID }}
-      ts: "${{ steps.slack.outputs.ts }}"
+      ts: "${{ steps.launch_sequence.outputs.ts }}"
       text: "Deployment finished! :rocket:"
       attachments:
         - color: "28a745"
@@ -278,7 +278,7 @@ convenience of the [`files.uploadV2`][files.uploadV2] method:
     payload: |
       channel_id: ${{ secrets.SLACK_CHANNEL_ID }}
       initial_comment: "the results are in!"
-      file: "results.out"
+      file: "./path/to/results.out"
       filename: "results-${{ github.sha }}.out"
 ```
 
@@ -307,6 +307,12 @@ Gather a Slack incoming webhook URL:
 6. [Add this Action as a step][job-step] 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
@@ -342,7 +348,7 @@ 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: Send GitHub Action data to a Slack workflow
+- name: Attempt to call an unknown method
   uses: slackapi/[email protected]
   with:
     errors: true
@@ -366,7 +372,7 @@ The `payload-delimiter` option will flatten the input payload using the provided
 delimiter and will also make values stringified:
 
 ```yaml
-- name: Send GitHub Action data to a Slack workflow
+- name: Flatten the default GitHub payload
   uses: slackapi/[email protected]
   with:
     payload-delimiter: "_"
@@ -385,7 +391,6 @@ input payload with the `payload-templated` option:
 
 ```yaml
 - name: Send custom JSON data to Slack workflow
-  id: slack
   uses: slackapi/[email protected]
   with:
     payload-file-path: "./payload-slack-content.json"

example-workflows/Technique_1_Slack_Workflow_Builder/README.md

@@ -0,0 +1,81 @@
+# Technique 1: Slack Workflow Builder
+
+> :memo: This technique uses Workflow Builder, which requires
+> [a Slack paid plan][plans].
+
+This technique sends data to Slack using a webhook to start a workflow created
+using Slack [Workflow Builder][wfb].
+
+## Setup
+
+The Slack app manifest included with each example showcases steps of a workflow
+in [Workflow Builder][wfb] along with the [webhook trigger][triggers] inputs.
+
+For details on how to setup this technique in GitHub Actions, read the
+[`README.md`][setup].
+
+## Example workflows
+
+1. [**Format generated files**](#format-generated-files): Message outputs from
+   prior steps.
+2. [**Post release announcements**](#post-release-announcements): Share releases
+   to a channel.
+3. [**Update a channel topic**](#update-a-channel-topic): Highlight the current
+   build status.
+
+### Format generated files
+
+Convert build outputs from earlier GitHub Action steps into a Slack message.
+
+This example uses data from a payload file to [send a message][send_message] to
+a hardcoded channel.
+
+**Related files**:
+
+- [`builds.data.json`](./builds.data.json): Payload file being sent.
+- [`builds.gha.yml`](./builds.gha.yml): GitHub Actions workflow.
+- [`builds.manifest.json`](./builds.manifest.json): Slack app manifest.
+- [`builds.trigger.json`](./builds.trigger.json): Slack webhook trigger.
+
+### Post release announcements
+
+Select a channel to post news about the most recent release to.
+
+This example uses [Slack functions][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.
+
+**Related files**:
+
+- [`announcements.gha.yml`](./announcements.gha.yml): GitHub Actions workflow.
+- [`announcements.manifest.json`](./announcements.manifest.json): Slack app
+  manifest.
+- [`announcements.trigger.json`](./announcements.trigger.json): Slack webhook
+  trigger.
+
+### Update a channel topic
+
+Show the latest commit status in the header of a channel.
+
+This example uses the default GitHub event [context][event-context] and
+[payload][event-payload] to [update a channel topic][update_channel_topic].
+
+**Related files**:
+
+- [`topic.gha.yml`](./topic.gha.yml): GitHub Actions workflow.
+- [`topic.manifest.json`](./topic.manifest.json): Slack app manifest.
+- [`topic.trigger.json`](./topic.trigger.json): Slack webhook trigger.
+
+[event-context]: https://github.com/actions/toolkit/blob/main/packages/github/src/context.ts#L6
+[event-payload]: https://docs.github.com/en/webhooks/webhook-events-and-payloads
+[functions]: https://api.slack.com/automation/functions
+[giphy]: https://giphy.com
+[send_message]: https://api.slack.com/reference/functions/send_message
+[plans]: https://slack.com/pricing
+[setup]: https://github.com/slackapi/slack-github-action/blob/main/README.md#technique-1-slack-workflow-builder
+[triggers]: https://api.slack.com/automation/triggers/webhook
+[update_channel_topic]: https://api.slack.com/reference/functions/update_channel_topic
+[wfb]: https://slack.com/features/workflow-automation

example-workflows/Technique_1_Slack_Workflow_Builder/announcements.gha.yml

@@ -0,0 +1,22 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+
+name: Post release announcements
+on:
+  release:
+    types:
+      - published
+jobs:
+  run:
+    name: Share recent changes with a channel
+    runs-on: ubuntu-latest
+    steps:
+      - name: Draft with these release notes details
+        uses: slackapi/[email protected]
+        with:
+          webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
+          webhook-type: webhook-trigger
+          payload: |
+            "draft_channel": "${{ secrets.SLACK_CHANNEL_ID }}",
+            "release_notes": ${{ toJSON(github.event.release.body) }},
+            "release_repository": "${{ github.repository }}",
+            "release_version": "${{ github.event.release.tag_name }}",

example-workflows/Technique_1_Slack_Workflow_Builder/announcements.manifest.json

@@ -0,0 +1,113 @@
+{
+  "_metadata": {
+    "major_version": 2
+  },
+  "display_information": {
+    "name": "Slack GitHub Actions Releaser",
+    "description": "Sharing the latest news in channel"
+  },
+  "features": {
+    "app_home": {
+      "messages_tab_enabled": false
+    },
+    "bot_user": {
+      "display_name": "Slack GitHub Actions Releaser"
+    }
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": ["chat:write", "chat:write.public", "reactions:write"]
+    }
+  },
+  "settings": {
+    "org_deploy_enabled": true
+  },
+  "workflows": {
+    "release_announcement": {
+      "title": "Release announcement",
+      "description": "Share excitement around the latest changes",
+      "input_parameters": {
+        "properties": {
+          "draft_channel": {
+            "type": "slack#/types/channel_id"
+          },
+          "release_notes": {
+            "type": "string"
+          },
+          "release_repository": {
+            "type": "string"
+          },
+          "release_version": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "draft_channel",
+          "release_notes",
+          "release_repository",
+          "release_version"
+        ]
+      },
+      "steps": [
+        {
+          "id": "0",
+          "function_id": "slack#/functions/send_message",
+          "inputs": {
+            "channel_id": "{{inputs.draft_channel}}",
+            "message": "A new release of <https://github.com/{{inputs.release_repository}}/releases/tag/{{inputs.release_version}}|{{inputs.release_repository}}@{{inputs.release_version}}> was tagged! :rocket:",
+            "interactive_blocks": [
+              {
+                "type": "actions",
+                "elements": [
+                  {
+                    "type": "button",
+                    "text": {
+                      "type": "plain_text",
+                      "text": "Share"
+                    },
+                    "action_id": "share"
+                  }
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "id": "1",
+          "function_id": "slack#/functions/open_form",
+          "inputs": {
+            "title": "Share the release notes",
+            "interactivity": "{{steps.0.interactivity}}",
+            "submit_label": "Share",
+            "fields": {
+              "elements": [
+                {
+                  "name": "announcement_channel",
+                  "title": "Select an announcements channel",
+                  "type": "slack#/types/channel_id"
+                }
+              ],
+              "required": ["announcement_channel"]
+            }
+          }
+        },
+        {
+          "id": "2",
+          "function_id": "slack#/functions/send_message",
+          "inputs": {
+            "channel_id": "{{steps.1.fields.announcement_channel}}",
+            "message": "A new release of <https://github.com/{{inputs.release_repository}}/releases/tag/{{inputs.release_version}}|{{inputs.release_repository}}@{{inputs.release_version}}> was tagged! :rocket:\n```{{inputs.release_notes}}```"
+          }
+        },
+        {
+          "id": "3",
+          "function_id": "slack#/functions/add_reaction",
+          "inputs": {
+            "message_context": "{{steps.2.message_context}}",
+            "emoji": "tada"
+          }
+        }
+      ]
+    }
+  }
+}

example-workflows/Technique_1_Slack_Workflow_Builder/announcements.trigger.json

@@ -0,0 +1,20 @@
+{
+  "type": "webhook",
+  "name": "Release webhook",
+  "description": "Share the most recent changes",
+  "workflow": "#/workflows/release_announcement",
+  "inputs": {
+    "draft_channel": {
+      "value": "{{data.draft_channel}}"
+    },
+    "release_notes": {
+      "value": "{{data.release_notes}}"
+    },
+    "release_repository": {
+      "value": "{{data.release_repository}}"
+    },
+    "release_version": {
+      "value": "{{data.release_version}}"
+    }
+  }
+}

example-workflows/Technique_1_Slack_Workflow_Builder/builds.data.json

@@ -0,0 +1,6 @@
+{
+  "status": "done",
+  "task": "Downstream staging rollout",
+  "errors": "",
+  "runner": "github-actions"
+}

example-workflows/Technique_1_Slack_Workflow_Builder/builds.gha.yml

@@ -0,0 +1,23 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+
+name: Format generated files
+on:
+  push:
+    branches:
+      - main
+jobs:
+  run:
+    name: Write structured data as a message
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repo
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Start the Slack workflow
+        uses: slackapi/[email protected]
+        with:
+          payload-file-path: "./example-workflows/Technique_1_Slack_Workflow_Builder/builds.data.json"
+          webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
+          webhook-type: webhook-trigger