Add Alexa Flash Briefing docs (#1299)

source/_components/alexa.markdown

@@ -12,9 +12,13 @@ ha_category: Voice
 featured: true
 ---
 
-There are two ways that you can use Amazon Echo and Home Assistant together.
+There are a few ways that you can use Amazon Echo and Home Assistant together.
 
-No matter which method(s) you decide to use, please remember that Amazon Echo requires an active Internet connection to function. If your Internet is down or experiencing issues (or Amazon's infrastructure is having issues), neither of these methods will work.
+- [Turning devices on and off](#i-just-want-to-turn-devices-on-and-off-using-echo)
+- [Build custom commands to use](#i-want-to-build-custom-commands-to-use-with-echo)
+- [Create a new Flash Briefing source](#flash-briefing-skills)
+
+No matter which method(s) you decide to use, please remember that Amazon Echo requires an active Internet connection to function. If your Internet is down or experiencing issues (or Amazon's infrastructure is having issues), none of these methods will work.
 
 Amazon has released [Echosim], a website that simulates the Alexa service in your browser. That way it is easy to test your skills without having access to a physical Amazon Echo.
 
@@ -56,15 +60,16 @@ The built-in Alexa component allows you to integrate Home Assistant into Alexa/A
 
 ### {% linkable_title Requirements %}
 
-Amazon requires the endpoint of a skill to be hosted via SSL. Self-signed certificates are ok because our skills will only run in development mode. Read more on [our blog][blog-lets-encrypt] about how to set up encryption for Home Assistant. If you are unable to get HTTPS up and running, consider using [this AWS Lambda proxy for Alexa skills](https://forums.developer.amazon.com/forums/thread.jspa?messageID=18604).
+Amazon requires the endpoint of a skill to be hosted via SSL. Self-signed certificates are ok because our skills will only run in development mode. Read more on [our blog][blog-lets-encrypt] about how to set up encryption for Home Assistant. If you are unable to get HTTPS up and running, consider using [this AWS Lambda proxy for Alexa skills](https://community.home-assistant.io/t/aws-lambda-proxy-custom-alexa-skill-when-you-dont-have-https/5230).
 
 [blog-lets-encrypt]: https://home-assistant.io/blog/2015/12/13/setup-encryption-using-lets-encrypt/
 
 To get started with Alexa skills:
 
- - Log in to [Amazon developer console](https://developer.amazon.com)
- - Go to Apps & Services => Alexa => Alexa Skill Kit - Get Started
- - Add a new skill
+ - Log in to [Amazon developer console][amazon-dev-console]
+ - Click the Alexa button at the top of the console
+ - Click the yellow "Add a new skill" button in the top right
+   - Skill Type: Custom Interaction Model (default)
    - Name: Home Assistant
    - Invocation name: home assistant (or be creative, up to you)
    - Version: 1.0
@@ -72,6 +77,8 @@ To get started with Alexa skills:
      - https
      - https://YOUR_HOST/api/alexa?api_password=YOUR_API_PASSWORD
 
+You can use this [specially sized Home Assistant logo][large-icon] as the large icon and [this one][small-icon] as the small one.
+
 ### {% linkable_title Configuring your Amazon Alexa skill %}
 
 Alexa works based on intents. Each intent has a name and variable slots. For example, a `LocateIntent` with a slot that contains a `User`. Example intent schema:
@@ -119,7 +126,6 @@ You can use [templates] for the values of `speech/text`, `card/title` and `card/
 
 Actions are using the [Home Assistant Script Syntax] and also have access to the variables from the intent.
 
-[templates]: /topics/templating/
 [Home Assistant Script Syntax]: /getting-started/scripts/
 
 Configuring the Alexa component for the above intents would look like this:
@@ -256,7 +262,7 @@ Then add the intent to your Alexa Section in your HA config file:
 
 Now say `Alexa ask homeassistant to run <some script>` and Alexa will run that script for you.
 
-## {% linkable_title Giving Alexa Some Personality%}
+## {% linkable_title Giving Alexa Some Personality %}
 
 In the examples above, we told Alexa to say `OK` when she successfully completed the task. This is effective but a little dull! We can again use [templates] to spice things up a little.
 
@@ -298,3 +304,57 @@ text: !include alexa_confirm.yaml
 Alexa will now respond with a random phrase each time. You can use the include for as many different intents as you like so you only need to create the list once.
 
 
+## {% linkable_title Flash Briefing Skills %}
+
+As of version [0.31][zero-three-one] Home Assistant supports the new [Alexa Flash Briefing Skills API][flash-briefing-api]. A Flash Briefing Skill adds a new Flash Briefing source that is generated by Home Assistant.
+
+### {% linkable_title Configuring a Flash Briefing skill in Home Assistant %}
+
+You can use [templates] for the `title`, `audio`, `text` and `display_url` configuration parameters.
+
+Here's an example configuration of a Flash briefing skill that will tell you who is at home:
+
+```yaml
+{% raw %}# Example configuration.yaml entry
+alexa:
+  flash_briefings:
+    whoishome:
+      - title: Who's at home?
+        text: >
+          {%- if is_state('device_tracker.paulus', 'home') and
+                 is_state('device_tracker.anne_therese', 'home') -%}
+            You are both home, you silly
+          {%- else -%}
+            Anne Therese is at {{ states("device_tracker.anne_therese") }}
+            and Paulus is at {{ states("device_tracker.paulus") }}
+          {% endif %}
+```
+
+You can add multiple items for a feed if you want. The Amazon required uid and timestamp will be randomly generated at startup and change at every restart of Home Assistant.
+
+Please refer to the [Amazon documentation][flash-briefing-api-docs] for more information about allowed configuration parameters and formats.
+
+### {% linkable_title Configuring your Flash Briefing skill %}
+
+- Log in to [Amazon developer console][amazon-dev-console]
+- Click the Alexa button at the top of the console
+- Click the yellow "Add a new skill" button in the top right
+  - Skill Information
+    - For Skill Type select Flash Briefing Skill API
+    - You can enter whatever name you want
+    - Hit next
+  - Interaction Model
+    - Nothing to do here
+  - Configuration
+    - Add new feed
+      - For URL, enter `https://YOUR_HOST/api/alexa/flash_briefings/BRIEFING_ID?api_password=YOUR_API_PASSWORD` where `BRIEFING_ID` is the key you entered in your configuration (such as `whoishome` in the above example)
+      - You can use this [specially sized Home Assistant logo][large-icon] as the Feed Icon
+      - All other settings are up to you
+
+[amazon-dev-console]: https://developer.amazon.com
+[flash-briefing-api]: https://developer.amazon.com/alexa-skills-kit/flash-briefing
+[flash-briefing-api-docs]: https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/flash-briefing-skill-api-feed-reference
+[large-icon]: /images/components/alexa/alexa-512x512.png
+[small-icon]: /images/components/alexa/alexa-108x108.png
+[templates]: /topics/templating/
+[zero-three-one]: /blog/2016/10/22/flash-briefing-updater-hacktoberfest/