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

This commit is contained in:
Aaron Bach 2020-07-13 08:14:35 -06:00 committed by GitHub
parent 2dfbbd6a1d
commit af88558ef9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -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.