Add docs for posting remote files to Slack (#13860)

source/_integrations/slack.markdown

@@ -69,29 +69,68 @@ icon:
   type: string
 {% endconfiguration %}
 
-### Slack service data
+### Slack Service Data
 
-The following attributes can be placed inside `data` for extended functionality.
+The following attributes can be placed inside the `data` key of the service call for extended functionality:
 
-| Service data attribute | Optional | Description |
+| Attribute              | Optional | Description |
 | ---------------------- | -------- | ----------- |
-| `file`                   |      yes | Local path of file, photo, etc. to post to Slack.
+| `file`                   |      yes | A file to include with the message; see below.
 | `attachments`            |      yes | Array of [Slack attachments](https://api.slack.com/messaging/composing/layouts#attachments) (legacy). *NOTE*: if using `attachments`, they are shown **in addition** to `message`.
 | `blocks`                 |      yes | Array of [Slack blocks](https://api.slack.com/messaging/composing/layouts). *NOTE*: if using `blocks`, they are shown **in place of** the `message` (note that the `message` is required nonetheless).
 | `blocks_template`        |      yes | The same as `blocks`, but able to support [templates](https://www.home-assistant.io/docs/configuration/templating).
 
-Example for posting a file from local path:
+Note that using `file` will ignore all usage of `attachments`, `blocks`, and `blocks_template` (as Slack does not support those frameworks in messages that accompany uploaded files).
+
+To include a local file with the Slack message, use these attributes underneath the `file` key:
+
+| Attribute              | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `path`                   |      no  | A local filepath that has been [whitelisted](/docs/configuration/basic/#whitelist_external_dirs).
+
+To include a remote file with the Slack message, use these attributes underneath the `file` key:
+
+| Attribute              | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `url`                    |      no  | A URL that has been [whitelisted](/docs/configuration/basic/#allowlist_external_urls).
+| `username`               |      yes | An optional username if the URL is protected by HTTP Basic Auth.
+| `password`               |      yes | An optional password if the URL is protected by HTTP Basic Auth.
+
+### Examples
+
+To send a file from local path:
 
 ```yaml
 message: Message that will be added as a comment to the file.
 title: Title of the file.
 data:
-  file: "/path/to/file.ext"
+  file:
+    path: /path/to/file.ext
 ```
 
-Please note that `file` is validated against the `whitelist_external_dirs` in the `configuration.yaml`.
+To send a file from remote path:
 
-Example for using the block framework:
+```yaml
+message: Message that will be added as a comment to the file.
+title: Title of the file.
+data:
+  file:
+    url: "http://site.com/image.jpg"
+```
+
+To send a file from remote path that is protected by HTTP Basic Auth:
+
+```yaml
+message: Message that will be added as a comment to the file.
+title: Title of the file.
+data:
+  file:
+    url: "http://site.com/image.jpg"
+    username: user
+    password: pass
+```
+
+To use the block framework:
 
 ```yaml
 message: Fallback message in case the blocks don't display anything.
@@ -122,7 +161,7 @@ data:
           1.0
 ```
 
-Example for using the legacy attachments framework:
+To use the legacy attachments framework:
 
 ```yaml
 message: Message that will be added as a comment to the file.