diff --git a/source/_components/notify.cisco_webex_teams.markdown b/source/_components/notify.cisco_webex_teams.markdown new file mode 100644 index 00000000000..3dd7b40764d --- /dev/null +++ b/source/_components/notify.cisco_webex_teams.markdown @@ -0,0 +1,149 @@ +--- +layout: page +title: "Cisco Webex Teams" +description: "Instructions on how to add Cisco Webex Teams notifications to Home Assistant." +date: 2017-02-20 15:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: cisco_webex_teams.png +ha_category: Notifications +ha_release: "0.40" +--- + +The `cisco_webex_teams` notification platform allows you to deliver rich notifications from Home Assistant to [Cisco Webex Teams](https://www.webex.com/team-collaboration.html) (formerly known as Cisco Spark). + +To use this notification platform you will need an app (bot) token. To obtain a token visit [Cisco Webex for Developers](https://developer.webex.com/). +* Detailed instructions can be found in the section titled **Creating a Webex Teams Bot** on the [Webex Teams bot documentation](https://developer.webex.com/docs/bots). + +You also need to specify the `room_id` that you wish to post messages into. The `room_id` can be found in one of two ways: + +1. Logging in at [Cisco Webex for Developers](https://developer.webex.com/) and navigate to `Documentation`>`API Reference`>`Messages` and select List Messages, or +2. Log into the web client at [teams.webex.com](https://teams.webex.com/), + * select the room (or create a new room), + * then copying the room ID from the URL. + +**Note:** you must add the bot email (in the format `mybot@webex.bot`) as a participant to the room specified above. + +To enable this platform in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +notify: + - name: NOTIFIER_NAME + platform: cisco_webex_teams + token: YOUR_BOT_TOKEN + room_id: CISCO_WEBEX_TEAMS_ROOMID +``` + +## {% linkable_title Rich Text Formatting %} + +Webex Teams clients can render rich text via a whitelisted set of html tags. + +For example, you could configure automations to display details in an easy to read fashion like so: + +

+ +Rich text as displayed in the macOS client. +

+ +Here are the automations for the above screenshot: + +```yaml + +# Rich Text Example 1. +# Show a one line message with a red banner +- alias: "Notify On Build Failing" + trigger: + - platform: webhook + webhook_id: build_failed + action: + service: notify.cisco_webex_teams_notify + data: + message: "
Build 0.89.5 compile failed." + + +# Rich Text Example 2. +# Show a title and multi-line message with a yellow banner, +# with lists, a person mention and a link +- alias: "Notify On Build Unstable" + trigger: + - platform: webhook + webhook_id: build_unstable + action: + service: notify.cisco_webex_teams_notify + data: + title: "Build 0.89.6 is unstable." + message: "
Version 0.89.6 failed verifications. + + +

<@personEmail:sparkbotjeeves@sparkbot.io>

+

View Test Report

+ " + +# Rich Text Example 3. +# Show a title and multi-line message with a blue banner, +# with lists, a person mention and a link +- alias: "Notify On Build Passing" + trigger: + - platform: webhook + webhook_id: build_passed + action: + service: notify.cisco_webex_teams_notify + data: + title: "✅ Version 0.89.7 passed all tests and deployed to production!" + message: "
Version 0.89.7 passed all verifications. + +
    +
  • test_cov +
  • test_osx +
  • test_win +
  • test_linux +
  • ... and 45 more. +
+ " +``` + +The following is a list of the allowed html tags and attributes: + +Tag | More Info +--- | --- +`<@personEmail:email@examplecompany.com>` | Used to tag another Webex Team user by email address. +`` | Defines a hyperlink. Allows attribute `href`. +`
` | Defines a section that is quoted from another source. Allows attribute `class` with allowed values `danger`, `warning`, `info`, `primary`, `secondary`. +`` | Defines bold text. +`` | Defines important text. +`` | Defines italic text. +`` | Defines emphasized text. +`
` | Defines preformatted text.
+`` | Defines a piece of computer code.
+`
` | Defines a single line break. +`

` | Defines a paragraph. +`

    ` | Defines an unordered list. +`
      ` | Defines an ordered list. +`
    1. ` | Defines a list item. +`

      ` to `

      ` | Defines HTML headings. + +{% configuration %} +name: + description: Setting the optional parameter `name` allows multiple notifiers to be created. The notifier will bind to the service `notify.NOTIFIER_NAME`. + required: false + default: notify + type: string +token: + description: Your app (bot) token. + required: true + type: string +room_id: + description: The Room ID. + required: true + type: string +{% endconfiguration %} + +To use notifications, please see the [getting started with automation page](/getting-started/automation/). diff --git a/source/_components/notify.ciscospark.markdown b/source/_components/notify.ciscospark.markdown deleted file mode 100644 index d9bcbc5e42a..00000000000 --- a/source/_components/notify.ciscospark.markdown +++ /dev/null @@ -1,51 +0,0 @@ ---- -layout: page -title: "Cisco Spark" -description: "Instructions on how to add CiscoSpark notifications to Home Assistant." -date: 2017-02-20 15:00 -sidebar: true -comments: false -sharing: true -footer: true -logo: ciscospark.png -ha_category: Notifications -ha_release: "0.40" ---- - -The `ciscospark` notification platform allows you to deliver notifications from Home Assistant to [Cisco Spark](https://ciscospark.com/). - -To use this notification platform you need to get a developer token. To obtain a token visit [Spark for Developers](https://developer.ciscospark.com/index.html) - -At this time you also need to specify the `Cisco Spark` `roomid`. The `roomid` can also be found at [Spark for Developers](https://developer.ciscospark.com/index.html). Just look in the Documentation under Rooms. - -In order to get notified for all new messages in the room you will need to create a bot. This will post the messages from the bot and mark them as new for you which will alert you. If you use your own personal token the messages are added to the room but no notification is triggered. -Once you have created the bot through the new App menu you will need to add the bot to the room that you are a member of as well. Now use the bot access token in your configuration below. - -To enable the Cisco Spark notification in your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -notify: - - name: NOTIFIER_NAME - platform: ciscospark - token: YOUR_DEVELOPER_TOKEN - roomid: CISCO_SPARK_ROOMID -``` - -{% configuration %} -name: - description: Setting the optional parameter `name` allows multiple notifiers to be created. The notifier will bind to the service `notify.NOTIFIER_NAME`. - required: false - default: notify - type: string -token: - description: Your development token. - required: true - type: string -roomid: - description: The Room ID. - required: true - type: string -{% endconfiguration %} - -To use notifications, please see the [getting started with automation page](/getting-started/automation/). diff --git a/source/images/components/cisco_webex_teams/rich_formatting.png b/source/images/components/cisco_webex_teams/rich_formatting.png new file mode 100644 index 00000000000..f0283718396 Binary files /dev/null and b/source/images/components/cisco_webex_teams/rich_formatting.png differ diff --git a/source/images/supported_brands/cisco_webex_teams.png b/source/images/supported_brands/cisco_webex_teams.png new file mode 100644 index 00000000000..d6056126e5e Binary files /dev/null and b/source/images/supported_brands/cisco_webex_teams.png differ diff --git a/source/images/supported_brands/ciscospark.png b/source/images/supported_brands/ciscospark.png deleted file mode 100644 index c6bac10f353..00000000000 Binary files a/source/images/supported_brands/ciscospark.png and /dev/null differ