Profile Bot

Overview

This tutorial provides a hands-on introduction to API.AI's features and tools that are especially useful for bot development. API.AI provides methods for both creating conversational components (agents) and integrating these components into the most popular messaging platforms. The result of integrating an agent with a messaging platform is known as a bot.

Even if you’re not building a bot, you might find this tutorial interesting, as it walks you through the essentials of API.AI.

Before you start, import the agent into your account, if you haven’t already.

Get started

It’s important to design conversation scenarios before you start working on your agent. This will help you understand what intents and entities you need to start with. Here is the story for our agent.

Our bot is developed for an imaginary person named Bob. Bob is a florist and is currently looking for a job. He wants a bot for his Facebook profile page and on the Kik, Slack, and Telegram messaging platforms.

Here are the initial questions that Bob thinks may come up in an interview with him and his bot:

  • Tell me about yourself.
  • What are some of your hobbies?
  • Can I see your CV?
  • Do you have a portfolio?
  • What are some of your strengths?
  • What’s your biggest weakness?

We’ll use them to start building our agent.

Create intents

An intent defines how the bot should react to what the user says. We created the following intents for each of the questions we expect:

  • about
  • cv
  • hobby
  • portfolio
  • strength
  • weakness

User inputs

In the 'User says' section of intents, we list variations of requests Bob’s bot may receive. For example, in the ‘about’ intent we wrote expressions like “tell me about yourself”, “let’s talk about you”, etc.

The API.AI platform uses machine learning to train agents to understand more variations of these examples. Even with a small number of examples, the agent can understand a lot of variations. You can try it with this agent. The more examples you add, the better the agent learns.

Action

The 'Action' section of the intent view is used to determine the actionable data that can be passed to your business logic to handle complex scenarios. We have a pretty simple Q&A bot here, however we’ll define the action names, so it’s there if we want to connect our agent to more sophisticated logic in the future.

Response

Once we’ve added several examples of how people may talk to our bot, we need to teach our bot to respond. The ‘about’ intent is designed to capture requests to talk about Bob. We think the bot should respond with his name, age, and interests. We’ll use the 'Response' section of the intent view to define the answers.

The bot is expected to respond with text. You can click the 'ADD MESSAGE CONTENT' button to add several ‘Text response’ elements. In the supported messaging platforms, they will appear as sequential messages sent from the bot.

To avoid repetition and make your bot sound more natural, you can add variations within a ‘Text response’ element. A different response will be picked when the the intent is matched. Text responses can also include emojis.

Images

If Bob wanted to share a picture of himself in the ‘about’ intent, he could include one in the ‘Response’ section by choosing the Image option from the 'ADD MESSAGE CONTENT' menu and providing a public image URL. The supported image format for all currently supported integrations is PNG.

If the provided URL is a valid image link, the picture will appear in the ‘Image’ element box.

Cards

In the ‘portfolio’ intent we’ll need to show more than one image. If you use Facebook integration you can display the pictures as a horizontal scrollable carousel, by adding them as Cards. Just choose the Card option from the 'ADD MESSAGE CONTENT' menu for each of your images, and enter the URL and the title of your pictures. You can change the order of your cards by simply dragging and placing any of the cards to the order you like.

Custom payload

For the ‘hobbies’ answers we’d like to mention that Bob loves music and wants to share one of his favorite pieces. In the 'ADD MESSAGE CONTENT' menu, we chose the Custom payload option.

Facebook integration

Facebook Messenger supports sharing .mp3 files, so in order to upload an audio file we should fill out the “facebook” section:

"facebook": {
    "attachment": {
      "type": "audio",
      "payload": {
        "url": "https://examples.api.ai/BobTheFlorist/clair-de-lune-debussy.mp3"
      }
    }
}

Slack integration

In Slack, we’d like to post clickable text which redirects the user to a YouTube page. To do that we fill out the “slack” section:

"slack": {
    "attachments": [
      {
        "title": "Debussy - Claire de Lune",
        "title_link": "https://www.youtube.com/watch?v=4fvo_iOuSck"
      }
    ]
}

Telegram integration

In the Telegram integration, the video will be reproduced on YouTube when the user taps on its title; or in the messenger, when the user taps on the image:

"telegram": {
    "text": "[Debussy - Claire de Lune](https://www.youtube.com/watch?v=4fvo_iOuSck).",
    "parse_mode": "Markdown"
}

Kik integration

In the Kik integration, the video will be reproduced on YouTube when tapped on in the messenger:

"kik": {
    "type": "link",
    "url": "https://www.youtube.com/watch?v=4fvo_iOuSck"
}

Quick replies

For all the requests about Bob’s CV, we’ll show the CV in .jpeg format in the same way that we showed the PNG file before. To make our bot more proactive, we’ll make him ask the user if they would like to take a look at Bob’s portfolio. In the 'ADD MESSAGE CONTENT' menu, we choose the Quick replies option and type in the question ‘Would you like to take a look at my portfolio?’ in the 'Title' field with two answer options below (‘Yes’ and ‘No’, each in the separate field below).

These answer options will appear in the app as clickable buttons. When clicked, the button query will be sent to the bot as user input.

Contexts

For the agent to understand that these inputs are actually the answer to the question in the ‘cv’ intent, we create a context in the Contexts section at the top of the intent page.

In this case we create an output context (namely, “see-portfolio”) because this is where we set the question that we’d like to get a response for. Then we’ll need to create the intents for each of the Quick replies options (‘cv - question:portfolio - confirmation:yes’ and ’cv - question:portfolio - confirmation:no’).

For each intent, we enter the same ‘see-portfolio’ context (the name of the context should be the same as the name of the output context in the parent intent). In this case, we place it in the input context field, since this intent represents the response for the question above.

Here we enter some examples of the user’s inputs (“Yes”/”Sure” for the ‘cv - question:portfolio - confirmation:yes’ and “No”/”Later” for the ‘cv - question:portfolio - confirmation:no’ intent).

Then we fill in the Responses section with the bot’s replies and the images of Bob’s portfolio. See how to display a good looking portfolio in the ‘portfolio’ intent description.

One-click integrations

With one-click integrations, you can easily start using your bot without extra coding. Just go to the Integrations section, choose the platform that you need and follow the instructions. For this particular bot we enabled Facebook, Slack, Telegram, and Kik.

Testing

Now our agent is ready for testing. You can test it out in the Test Console (‘Try it now...’ section) on the right side of the page.

To test rich content in messages, use one-click integrations to connect your agent to Facebook Messenger, Slack, Kik, and Telegram. The easiest would be Slack integration, as it has a “Test in Slack” button, which automatically creates a bot in your Slack account. You’ll be ready to test your bot in a few seconds.