doc: how to reply to a message (#309)

* Document replying to message

* Update README.md

Co-authored-by: Fil Maj <fmaj@slack-corp.com>

* Fix variable reference in docs

* Fix typo

Co-authored-by: Fil Maj <fmaj@slack-corp.com>

* Improve documentation based on feedback

* Update example

Co-authored-by: Ethan Zimbelman <ethan.zimbelman@me.com>

---------

Co-authored-by: Fil Maj <fmaj@slack-corp.com>
Co-authored-by: Ethan Zimbelman <ethan.zimbelman@me.com>

README.md

@@ -64,6 +64,7 @@ or
   env:
     SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
 ```
+
 or
 
 > If the `payload` is provided it will take preference over `payload-file-path`
@@ -211,6 +212,37 @@ Please note that **the message update step does not accept a channel name.** Set
     SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
 ```
 
+#### Reply to a message
+
+If you want to post a message as a threaded reply, you can populate the `payload` with a `thread_ts` field. This field should equal the `ts` value of the parent message of the thread. If you want to reply to a message previously posted by this Action, you can use the `ts` output provided as the `thread_ts` of a consequent threaded reply, e.g. `"thread_ts": "${{ steps.deployment_message.outputs.ts }}"`.
+
+Please note that **reply to a message does not accept a channel name.** Set a channel ID for the actions that reply to messages in thread.
+
+```yaml
+- id: deployment_message
+  uses: slackapi/slack-github-action@v1.26.0
+  with:
+    channel-id: "CHANNEL_ID"
+    payload: |
+      {
+        "text": "Deployment started (In Progress)"
+      }
+  env:
+    SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+- uses: slackapi/slack-github-action@v1.26.0
+  with:
+    # Unlike the step posting a new message, this step does not accept a channel name.
+    # Please use a channel ID, not a name here.
+    channel-id: "CHANNEL_ID"
+    payload: |
+      {
+        "thread_ts": "${{ steps.deployment_message.outputs.ts }}",
+        "text": "Deployment finished (Completed)"
+      }
+  env:
+    SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+```
+
 ### Technique 3: Slack Incoming Webhook
 
 This approach allows your GitHub Actions job to post a message to a Slack channel or direct message by utilizing [Incoming Webhooks](https://api.slack.com/messaging/webhooks).

test/slack-send-test.js

@@ -143,6 +143,26 @@ describe('slack-send', () => {
         assert.equal(firstChatArgs.text, 'who let the dogs out?', 'Correct message provided to postMessage with first comma-separated channel');
         assert.equal(secondChatArgs.text, 'who let the dogs out?', 'Correct message provided to postMessage with second comma-separated channel');
       });
+
+      it("should send a reply-message using the postMessage API if thread_ts payload field is used'", async () => {
+        fakeCore.getInput
+          .withArgs('payload')
+          .returns('{"thread_ts":"123456","text":"who let the dogs out?"}');
+        fakeCore.getInput.withArgs('channel-id').returns('C123456');
+
+        await slackSend(fakeCore);
+
+        assert.equal(fakeCore.setOutput.firstCall.firstArg, 'ts', 'Output name set to ts');
+        assert.equal(fakeCore.setOutput.secondCall.firstArg, 'thread_ts', 'Output name set to thread_ts');
+        assert(fakeCore.setOutput.secondCall.lastArg.length > 0, 'Time output a non-zero-length string');
+        assert.equal(fakeCore.setOutput.lastCall.firstArg, 'time', 'Output name set to time');
+        assert(fakeCore.setOutput.lastCall.lastArg.length > 0, 'Time output a non-zero-length string');
+
+        const chatArgs = ChatStub.postMessage.lastCall.firstArg;
+        assert.equal(chatArgs.channel, 'C123456', 'Correct channel provided to postMessage');
+        assert.equal(chatArgs.thread_ts, '123456', 'Correct thread_ts provided to postMessage');
+        assert.equal(chatArgs.text, 'who let the dogs out?', 'Correct message provided to postMessage');
+      });
     });
     describe('sad path', () => {
       it('should set an error if payload cannot be JSON parsed', async () => {