docs: showcase updated use cases in example workflows

README.md

@@ -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"
 ```
 
@@ -385,7 +385,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,78 @@
+# Technique 1: Slack Workflow Builder
+
+> :memo: This technique requires [a Slack paid plan][plans] to use Workflow
+> Builder.
+
+This technique sends data to Slack using a webhook to start a workflow created
+using Slack [Workflow Builder][wfb].
+
+## Setup
+
+For details on how to setup this technique in GitHub Actions, read the
+[`README.md`][setup].
+
+## Example workflows
+
+1. [**Format generated files**](#format-structured-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 channel.
+
+**Related files**:
+
+- [`format.data.json`](./format.data.json): Payload file being sent.
+- [`format.gha.yml`](./format.gha.yml): GitHub Actions workflow.
+- [`format.manifest.json`](./format.manifest.json): Slack app manifest.
+
+### Post release announcements
+
+Select a channel to post news about the most recent release to.
+
+This example uses [Slack functions][functions] and a
+[connector function][connector] to do the following:
+
+1. Open a form to select a channel.
+2. Gather a random gif from [giphy][giphy].
+3. Send a message to the selected channel.
+4. React with an excited emoji.
+
+The default GitHub event [context][event-context] and [payload][event-payload]
+are used as inputs.
+
+**Related files**:
+
+- [`announcements.gha.yml`](./announcements.gha.yml): GitHub Actions workflow.
+- [`announcements.manifest.json`](./announcements.manifest.json): Slack app
+  manifest.
+
+### Update a channel topic
+
+Show the current build status in the header of a channel.
+
+This example uses inputs provided inline 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.
+
+[connector]: https://api.slack.com/automation/connectors
+[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
+[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,19 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+
+name: Post release announcements
+on:
+  release:
+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: |
+            key: value
+            foo: bar
+            todo: update this....

example-workflows/Technique_1_Slack_Workflow_Builder/announcements.manifest.json

@@ -0,0 +1 @@
+{}

example-workflows/Technique_1_Slack_Workflow_Builder/format.data.json

@@ -0,0 +1,5 @@
+{
+  "todo": "12345",
+  "something": "${{ github.???????????? }}",
+  "details": "${{ env.???????????? }}"
+}

example-workflows/Technique_1_Slack_Workflow_Builder/format.gha.yml

@@ -0,0 +1,22 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+
+name: Format generated files
+on:
+  push:
+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/format.data.json"
+          payload-templated: true
+          webhook: ${{ secrets.SLACK_WEBHOOK_URL }}
+          webhook-type: webhook-trigger

example-workflows/Technique_1_Slack_Workflow_Builder/format.manifest.json

@@ -0,0 +1 @@
+{}

example-workflows/Technique_1_Slack_Workflow_Builder/default_GitHub_Trigger_payload.yml → example-workflows/Technique_1_Slack_Workflow_Builder/topic.gha.yml

@@ -1,12 +1,17 @@
-on: [push]
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
 
+name: Update a channel topic
+on:
+  push:
+    branches:
+      - main
+      - example
 jobs:
-  new_push_job:
-    runs-on: ubuntu-latest
+  run:
     name: New push to repo
+    runs-on: ubuntu-latest
     steps:
-      - name: Send GitHub trigger payload to Slack Workflow Builder
-        id: slack
+      - name: Update the channel topic
         uses: slackapi/[email protected]
         with:
           payload-delimiter: "_"

example-workflows/Technique_1_Slack_Workflow_Builder/topic.manifest.json

@@ -0,0 +1 @@
+{}

example-workflows/Technique_2_Slack_API_Method/README.md

@@ -0,0 +1,40 @@
+# Technique 2: Slack API method
+
+A bot token or user token or [token of some other kind][tokens] must be used to
+call one of [the Slack API methods][methods] with this technique.
+
+## Setup
+
+For details on how to setup this technique in GitHub Actions, read the
+[`README.md`][setup].
+
+## Example workflows
+
+1. [**Direct message the author**](#direct-message-the-author): Write to the
+   Slack user with a matching email.
+2. [**Invite a usergroup to channel**](#invite-a-usergroup-to-channel): Create a
+   channel and invite members.
+
+### Direct message the author
+
+Send 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.
+
+**Related files**:
+
+- [`author.yml`](./author.yml): GitHub Actions workflow.
+
+### Invite a usergroup to channel
+
+Create 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.
+
+**Related files**:
+
+- [`invite.yml`](./invite.yml): GitHub Actions workflow.
+
+[methods]: https://api.slack.com/methods
+[setup]: https://github.com/slackapi/slack-github-action?tab=readme-ov-file#technique-2-slack-api-method
+[tokens]: https://api.slack.com/concepts/token-types

example-workflows/Technique_2_Slack_API_Method/author.yml

@@ -0,0 +1,56 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+
+name: Direct message the author
+on:
+  push:
+jobs:
+  run:
+    name: Send a notification of recent changes
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout the repo
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Find correspondences
+        id: email
+        uses: slackapi/[email protected]
+        with:
+          method: users.lookupByEmail # https://api.slack.com/methods/users.lookupByEmail
+          token: ${{ secrets.SLACK_BOT_TOKEN }}
+          payload: |
+            email: ${{ github.event.pusher.email }}
+
+      - name: Search email detail
+        if: ${{ steps.email.outputs.ok }}
+        run: |
+          SLACK_USER_ID=$(echo '${{ steps.email.outputs.response }}' | jq -r '.user.id')
+          echo "SLACK_USER_ID=$SLACK_USER_ID" >> $GITHUB_ENV
+
+      - name: Send a direct message
+        if: ${{ steps.email.outputs.ok }}
+        uses: slackapi/[email protected]
+        with:
+          errors: true
+          method: chat.postMessage # https://api.slack.com/methods/chat.postMessage
+          token: ${{ secrets.SLACK_BOT_TOKEN }}
+          payload: |
+            "channel": "${{ env.SLACK_USER_ID }}",
+            "text": "${{ github.repository }} had a change!",
+            "blocks": [
+              {
+                "type": "section",
+                "text": {
+                  "type": "mrkdwn",
+                  "text": ":large_green_square: <https://github.com/${{ github.repository }}|*${{ github.repository }}*>: `${{ github.sha }}`"
+                }
+              },
+              {
+                "type": "section",
+                "text": {
+                  "type": "mrkdwn",
+                  "text": ${{ toJSON(github.event.head_commit.message) }}
+                }
+              }
+            ]

example-workflows/Technique_2_Slack_API_Method/invite.yml

@@ -0,0 +1,56 @@
+# yaml-language-server: $schema=https://json.schemastore.org/github-workflow.json
+
+name: Invite a usergroup to channel
+on:
+  issues:
+    types:
+      - labeled
+jobs:
+  run:
+    name: Respond to reports of a new problem
+    runs-on: ubuntu-latest
+    if: ${{ github.event.label.name == 'bug' }}
+    steps:
+      - name: Create a new Slack channel for communications
+        id: conversation
+        uses: slackapi/[email protected]
+        with:
+          errors: true
+          method: conversations.create # https://api.slack.com/methods/conversations.create
+          token: ${{ secrets.SLACK_BOT_TOKEN }}
+          payload: |
+            name: issue-${{ github.event.issue.number }}
+
+      - name: Send the issue link into the Slack channel
+        uses: slackapi/[email protected]
+        with:
+          method: chat.postMessage # https://api.slack.com/methods/chat.postMessage
+          token: ${{ secrets.SLACK_BOT_TOKEN }}
+          payload: |
+            channel: ${{ steps.conversation.outputs.channel_id }}
+            text: "An issue was opened <!date^${{ steps.conversation.outputs.time }}^{date_num} at {time_secs}|just now>: ${{ github.event.issue.html_url }}"
+
+      - name: Gather information of those to add
+        id: members
+        uses: slackapi/[email protected]
+        with:
+          errors: true
+          method: usergroups.users.list # https://api.slack.com/methods/usergroups.users.list
+          token: ${{ secrets.SLACK_BOT_TOKEN }}
+          payload: |
+            usergroup: ${{ secrets.SLACK_USERGROUP_ID }}
+
+      - name: Combine the list of usergroup users
+        run: |
+          SLACK_USERGROUP_USER_IDS=$(echo '${{ steps.members.outputs.response }}' | jq -r '.users | join(",")' )
+          echo "SLACK_USERGROUP_USER_IDS=$SLACK_USERGROUP_USER_IDS" >> $GITHUB_ENV
+
+      - name: Add the usergroup to the channel
+        uses: slackapi/[email protected]
+        with:
+          errors: true
+          method: conversations.invite # https://api.slack.com/methods/conversations.invite
+          token: ${{ secrets.SLACK_BOT_TOKEN }}
+          payload: |
+            channel: ${{ steps.conversation.outputs.channel_id }}
+            users: ${{ env.SLACK_USERGROUP_USER_IDS }}