jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-19 15:26:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add block documentation for Slack (#12518)

Browse Source 
* Add block documentation for Slack

* Code review

* Updates from code review
This commit is contained in:
Aaron Bach 2020-03-31 12:30:31 -06:00 committed by GitHub
parent 74b0cdcddc
commit 7bbb3c06ef
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 47 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
source/_integrations/slack.markdown
View File

@ -75,77 +75,65 @@ The following attributes can be placed inside `data` for extended functionality.
| Service data attribute | Optional | Description | | Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- | | ---------------------- | -------- | ----------- |
| `file` | yes | Groups the attributes for file upload. If present, either `url` or `path` have to be provided. | `file` | yes | Local path of file, photo, etc. to post to Slack.
| `path ` | yes | Local path of file, photo etc to post to Slack. Is placed inside `file`. | `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`.
| `url` | yes | URL of file, photo etc to post to Slack. Is placed inside `file`. | `blocks` | yes | Array of [Slack blocks](https://api.slack.com/messaging/composing/layouts). *NOTE*: if using `blocks`, they are shown **in addition** to `message`.
| `username` | yes | Username if the URL requires authentication. Is placed inside `file`.
| `password` | yes | Password if the URL requires authentication. Is placed inside `file`.
| `auth` | yes | If set to `digest` HTTP-Digest-Authentication is used. If missing HTTP-BASIC-Authentication is used. Is placed inside `file`.
| `attachments` | yes | Array of [Slack attachments](https://api.slack.com/docs/message-attachments). See [the attachment documentation](https://api.slack.com/docs/message-attachments) for how to format. *NOTE*: if using `attachments`, they are shown **in addition** to `message`
Example for posting file from URL: Example for posting a file from local path:
```json ```yaml
{ message: Message that will be added as a comment to the file.
"message":"Message that will be added as a comment to the file.", title: Title of the file.
"title":"Title of the file.", data:
"target": ["#channelname"], file: "/path/to/file.ext"
"data":{
"file":{
"url":"http://[url to file, photo, security camera etc]",
"username":"optional user, if necessary",
"password":"optional password, if necessary",
"auth":"digest"
}
}
}
``` ```
Example for posting file from local path: Please note that `file` is validated against the `whitelist_external_dirs` in the `configuration.yaml`.
```json Example for using the block framework:
{
"message":"Message that will be added as a comment to the file.", ```yaml
"title":"Title of the file.", message: Message that will be added as a comment to the file.
"data":{ title: Title of the file.
"file":{ data:
"path":"/path/to/file.ext" attachments:
} - type: section
} text:
} type: mrkdwn
text: 'Danny Torrence left the following review for your property:'
- type: section
block_id: section567
text:
type: mrkdwn
text: "<https://example.com|Overlook Hotel> \n :star: \n Doors had too many
axe holes, guest in room 237 was far too rowdy, whole place felt stuck in
the 1920s."
accessory:
type: image
image_url: https://is5-ssl.mzstatic.com/image/thumb/Purple3/v4/d3/72/5c/d3725c8f-c642-5d69-1904-aa36e4297885/source/256x256bb.jpg
alt_text: Haunted hotel image
- type: section
block_id: section789
fields:
- type: mrkdwn
text: |-
*Average Rating*
1.0
``` ```
Please note that `path` is validated against the `whitelist_external_dirs` in the `configuration.yaml`. Example for using the legacy attachments framework:
Example for posting formatted attachment: ```yaml
message: Message that will be added as a comment to the file.
```json title: Title of the file.
{ data:
"message": "", attachments:
"data": { - title: WHAT A HORRIBLE NIGHT TO HAVE A CURSE.
"attachments": [ image_url: https://i.imgur.com/JEExnsI.gif
{
"title": "WHAT A HORRIBLE NIGHT TO HAVE A CURSE.",
"image_url": "https://i.imgur.com/JEExnsI.gif"
}
]
}
}
``` ```
You can also use YAML to send messages from your automations You can also use YAML to send messages from your automations
```yaml
- service: notify.slack
data:
message: "Latest notification"
title: "Latest image"
target: ["#home-assistant"]
data:
file:
path: "/myfile.jpg"
```
Please note that both `message` is a required key, but is always shown, so use an empty (`""`) string for `message` if you don't want the extra text. Please note that both `message` is a required key, but is always shown, so use an empty (`""`) string for `message` if you don't want the extra text.
To use notifications, please see the [getting started with automation page](/getting-started/automation/). To use notifications, please see the [getting started with automation page](/getting-started/automation/).