At Google, we believe the future is artificial intelligence first. Artificial intelligence means making computers "smart" so they can think on their own.

We have been investing heavily in the areas of:

These things come together in the Google Assistant. It allows you to have a conversation with Google, that helps you get things done.

Let's see together how it's all working with a new way for us to get useful information on bitcoin. Ready? Let's roll.

So what does this mean?

Google Home is a voice activated speaker that users keep in their home.

The Google Assistant is the conversation between the users and Google. They can get things done by talking with the Assistant. There are many things users can do by just using the Assistant directly.

To learn more about the Assistant check out this short video.

Actions on Google allows developers to extend the Assistant. A developer can implement an "Assistant app".

That is what we are going to focus on today in our bitcoin information example.
This codelab will walk you through creating your own Assistant app with API.AI. We are going to use API.AI, which is a conversational user experience platform. In other words, it helps us ‘talk' to machines in a way they will understand us better.

This codelab will include the design considerations, as well as implementation details, to ensure that your action meets the key principles.

What you will build

In this codelab, you're going to build an "Bitcoin Info" action.
Your action will:

  • Utilize and demonstrate the principles of Voice UI.
  • Tell you bitcoin information such as: current value, total amount of bitcoins etc.
  • Provide you with knowledge to create more actions in the future.
  • Btw, it will involve a bit of code!
    It is going to be fun.
  • You can test it right now at https://bot.api.ai/bitcoin-info

What you'll learn

What you'll need

How does it works?

So how does a conversation action work?

The user needs to invoke your action. You say a phrase like "Ok Google, talk to bitcoin info". This tells Google the name of the action to talk to.

From this point onwards, the user is now talking to your conversation action. Your action generates dialog output, which then spoken to the user. The user then makes requests, your action processes it, and replies back again. The user has a two way dialog until the conversation is finished.

See below, if you like diagrams to ‘see' what we explained above.

Also, if you are confused between API.AI and your webhook, see below.

Login to API.AI

So what is API.AI?

APIAI lets the machine understand what the user is trying to say, and can provide a response. You type in example sentences of things that a user might speak.

You can specify what values you need to get from the user. It then uses machine learning to understand the sentences and manage the conversation.

Click the following link to login to API.AI - https://console.api.ai/

Once you clicked on the ‘Google' button you will get an option to create your first agent.

After the login you can create your first agent.
See below:

You will need to:

  1. Click on ‘Create Agent' and give your agent a name.
    In our case, it will be "BitcoinInfo". Please note that the agent name can not contain any spaces between the words.
  2. Give a short description so other users will know what this action is going to do.
  3. Click on ‘Save'.
    It's the button in the top-right corner of the screen.

Create our first Entity

What are entities?

Entities are the values we are trying to capture from the user phrases. Kind of like filling out a form, requesting details from the user. API.AI looks to extract these out, and will do follow up prompts until done.

This is how an entity looks in API.AI

We will create a currency entity.

(!) Actually, API.AI already has this type of entity built out for you. But for the purpose of this codelab we will create it, cool?

Create a Bitcoin entity

First step is to click on the ‘Create Entity' button.

Important aspects to note:

  1. You should ‘help' our machine learning algorithm to train itself by providing synonyms. the synonyms list is kind of like a lookup table of words to other words. For example, we typed few currencies like: Euro, Dollars, Bitcoins etc'. Moreover, we allowed API.AI to use its machine learning to expand this entity by clicking on the checkbox ‘Allow automated expansion'.
  2. In the real world, try to give many examples so it will cover more cases.
  3. Click on ‘Save' when you are done.

Build The Webhook

We got for you two options here:

  1. If you don't have a server running right now, You can use our demo live webhook: https://us-central1-bitcoin-info-io17.cloudfunctions.net/bitcoinInfo
    by just plug it to your Fulfilment.
  2. If you wish to test the webhook from your own server. You can take the code below and use your own server with NodeJS.
    This is the index.js that contain all the logic for our webhook.

index.js

// Copyright 2017, Google, Inc.
// Licensed under the Apache License, Version 2.0 (the 'License');
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an 'AS IS' BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

'use strict';

process.env.DEBUG = 'actions-on-google:*';

// We need the Assistant client for all the magic here
const Assistant = require('actions-on-google').ApiAiAssistant;
// To make our http request (a bit nicer)
const request = require('request');

// Some variables we will use in this example
const ACTION_PRICE = 'price';
const ACTION_TOTAL = 'total';
const EXT_BITCOIN_API_URL = "https://blockchain.info";
const EXT_PRICE = "/q/24hrprice";
const EXT_TOTAL = "/q/totalbc";

// [START bitcoinInfo]
exports.bitcoinInfo = (req, res) => {
  const assistant = new Assistant({request: req, response: res});
  console.log('bitcoinInfoAction Request headers: ' + JSON.stringify(req.headers));
  console.log('bitcoinInfoAction Request body: ' + JSON.stringify(req.body));

  // Fulfill price action business logic
  function priceHandler (assistant) {
    request(EXT_BITCOIN_API_URL + EXT_PRICE, function(error, response, body) {
      // The fulfillment logic for returning the bitcoin current price
    console.log("priceHandler response: " + JSON.stringify(response) + " Body: " + body + " | Error: " + error);
    const msg = "Right now the price of a bitcoin is " + body + " USD";
    assistant.tell(msg);
    });
  }

  // Fulfill total bitcoin action 
  function totalHandler (assistant) {
    request(EXT_BITCOIN_API_URL + EXT_TOTAL, function(error, response, body) {
    console.log("totalHandler response: " + JSON.stringify(response) + " Body: " + body + " | Error: " + error);
    // The fulfillment logic for returning the amount of bitcoins in the world
    const billionsBitcoins = body / 1000000000;
    const msg = "Right now there are " + billionsBitcoins + " billion bitcoins around the world.";
    assistant.tell(msg);
    });
  }

  // The Entry point to all our actions
  const actionMap = new Map();
  actionMap.set(ACTION_PRICE, priceHandler);
  actionMap.set(ACTION_TOTAL, totalHandler);

  assistant.handleRequest(actionMap);
};
// [END bitcoinInfo]

Create our intents

What is an intent?

An Intent is triggered by a series of "user says" phrases. This could be something like "Please tell me what is the bitcoin value in USD" or "What is the block chain size today?".

In most cases, you need to specify 10-12 sentences to train API.AI's machine learning algorithm. Then even if the user doesn't say exactly the words you typed here, API.AI can still understand them!

You should create separate intents for different types of actions though.

Don't try to combine all of them together.

In our example, we will create only three intents:

Build the "price" intent

After we have our new @currency entity. If you notice the @ before the word - It's not a mistake. This is the way we will refer to our new entity from now. Think of it as a special sign to show us that we are referring to our entity and not just another bitcoin.

It's time to create the intent that will fetch us bitcoin information.

First, click on the ‘Create Intent' button.

Second, start typing few sentences that you will want to use to get information on bitcoin. For example, "please tell me what is the value of bitcoin today in USD".

Type a few sentences so API.AI could start training its algorithms.

You can see that while you type, API.AI automatically recognizes that the phrase includes one of the entities, so it highlights it.

Next, we are skipping the ‘events' part, and in the ‘Action' section we need:

  1. Type ‘price' as the action name that we will pass our webhook. You can think on it as our ‘key' for the webhook. This information will let us run the right functionality in the webhook.
  2. Make sure that our @currency entity is not required. As in this codelab, we aren't going to use it, due to time limitations. However, if you wish to extend it later, you could require it and have several options to get the value of the bitcoin in different currencies.

Finally, in the ‘Fulfillment' section you need to check the ‘webhook' checkbox.

But, before you can do that, you need to click on the ‘Fulfilment' menu item and enable the ‘Webhook'.

See below:

After you enabled it you will get the option to enter your webhook parameters.

In this phase, you can just fill the URL with: https://us-central1-bitcoin-info-io17.cloudfunctions.net/bitcoinInfo

Now, click ‘Save' and return to the ‘Intents' and click on ‘Price' intnet. Scroll all the way down and you will see this new option ‘Fulfilment':

Please make sure to check the two checkboxes so API.AI will know to send its information to our webhook.

Build the "Total" intent

Let's have another option to give the user the total number of bitcoins in the world.
Click on the + sign near the Intents menu.

And you will get an empty intent form.

Fill it like the example below.

You can give it a bit more examples for the ‘User says'.

(!) Don't forget to give the action name: total as it's important for our webhook in order to recognize what data to return.

Last but not least, check the ‘fulfilment' section to ‘Use webhook'. Than, please don't forget to click ‘Save'.

Build the "Quit" intent

A good design principle is to allow our user to end the conversation.

You should click again on ‘Create Intent' button. Than, start typing few sentences that will end the conversation. For example, "bye bye" or "bye bitcoin info".

Below is how this intent should look like.

You need to check the ‘end conversation' checkbox so that it will know to really end the conversation at this point.

Test ‘price' intent

It's very important to check our work while we are developing it. Luckily for us, it's very easy to do it with API.AI. All you need to do after you created the new intent is to look at the right side of the screen. Type what you wish to test and you will get the response.

In the example below, we type "please tell me what is the price of bitcoin in USD" and as you can see it's working nicely, since we got a price in the response.

A quick way to test how our new action works on Google home will be to use the web simulator.

We need to click on ‘Integrations' in the left side menu and then click:

  1. On the publish checkbox in the top-right side.
  2. On "Actions on Google" as this will be our integration.

Click on the ‘TEST' button. If this is the first time you are enabling this integration, you need to click on the switch at the top-right corner to enable this integration.

The next step is to click on ‘VIEW' in order to open the Actions simulator.
You can see it in the image below.

You will get a screen that lets you talk with the simulator.

On the left side, you can type (or talk) your commands and on the rigth side, you can see the responses (in JSON format). Here we gave a full conversation that test our 2 intents (price and total).

We can also test our action with the automated page that API.AI created for our new bot.

First, you need to click on ‘Deploy' so this new action will be available to the world. Then, you can customize the url so it will be easier to remember it. In our case, we typed: "bitcoin-info".

Now, you can try it.

You will see this screen:

It's very powerful, as you can now share your creation with the world and it will work on any device that is connected to the internet and got a browser.

Good job!

Conversation Design

Please remember that in order to make a really good Action, you need to think carefully about the design.

Designing a spoken dialog between a human and a computer - in advance - accounting for all the possibilities, both in function and user behavior, and still have it feel natural - is harder than it looks.

The key to building a good voice interface is to not fall into the trap of simply converting a graphical user interface into a Voice User Interface. This defeats the purpose of using a conversation. People are not going to change how they talk anytime soon, so take what we know about human-to-human conversation to teach our computers to talk to humans. Not the other way around.

Top 3 Design Tips

  1. Create a persona.
    It's the consistent character, captured by the voice and interactive experience. It's the face of the experience for the user, who they will be talking to. Persona It is conveyed through:
  1. Tone
  2. Word and phrase choices
  3. Style
  4. Technique
  5. Voice

The persona should be based on: Your user population and their needs and the imagery & qualities associated with your agent's brand.

2. Think outside the box, literally.

You should write your core experiences like you would a screenplay. This can be as scrappy as acting it out with a colleague and documenting it on paper, or creating an interactive wizard-of-oz prototype you tweak and play with until you're ready to start coding.

And then, when you draw out your initial vision, keep it at a high level, where the boxes represent entire dialogs or user intents, but leave out the individual wording you'll use in the interaction.

3. In conversations, there are no "errors"

When a problem happens, imagine what the user hears when your action says "I don't understand YOU".

This is one of the greatest cause of user frustration and aversions to voice interfaces. People get angry and raise their voice and repeat the same answer again!

We need to give people credit for knowing how to speak. Just because they don't understand a prompt or choices, doesn't mean they don't speak the language. So help them be successful.

And remember what happens along the way, maintain context.

The best way to course-correct in advance while still maintaining a natural, comfortable conversation, is to plan for these occurrences as if they were any other turn in a conversation - i.e. to treat them as input that didn't cause the "error" in and of themselves.

We have a great set of design materials on our developer site to help you think about how to design better conversations.

Action naming and policies

Read more on about "Actions on Google Developers"

(!) Please feel free to join our "Actions on Google Developer Community" and follow us @Actions on Google

Download the Action example

Click the following link to download all the code for this codelab:

Download source code

Unpack the downloaded zip file. This will unpack a root folder (bitcoin-info), which contains a zip file with all the definitions this codelab, along with all of the resources you will need. This is the zip file (Bitcoin-info.zip) that you will need to import.

How to import the action to API.AI

After you download the source code, you need to open the with all of the resources you will need. You can import this action with 3 easy steps:

  1. Create a new agent.
  2. Click on ‘Export and Import'.
  3. Click on the ‘Import from zip' and point to the zip file (Bitcoin-info.zip) you just downloaded.

Please note, that at any time during the development process, you can restore this action from the same zip and get all the data we showed in this code lab.

Give it a try

TRY IT