Building custom skills with Katella

Katella was built for the Enterprise on the openness of modern API platforms. You can request time off, order office supplies, book a conference room, file expense report …, the potential is limitless with the proliferation of APIs. With today’s release, your team can now extend the Katella assistant and build private skills, tapping into your existing APIs.

Introducing the Katella platform

Our platform unifies Natural Language Understanding with Application APIs, enabling teams to build impactful skills with real-time API connectivity, all without hosting any servers or writing code. In fact, all the skills at katella.ai were built using this same platform.

There are a few pieces to the Katella platform, and together they provide the complete toolset to build self-hosted, intelligent tasks:

Natural Language Understanding

We designed our NLU engine to scale to hundreds of different intents. It was trained with business domains and highly accurate at distinguishing the smallest differences between similar intents.

API connectivity

Katella acts as the API store, managing all users’ credentials to different APIs. She understands OAuth1, OAuth2 and API token lifecycle and automatically handle authorization and renewal, abstracting the security layer away from the skill builder.

Katella supports API chaining, allowing you to make multiple API calls to gather your data.

Serverless processing

We wanted the skill building experience together in one unified platform, so Katella has her own Expression Language to inline process API data and construct user outputs (and because it’s 2018 and serverless is cool). The language is in its early stage but we are confident it’ll do 95% of a full-fledge programming language job 500% easier.

Building a custom Skill

Let’s try adding a simple skill to the existing BambooHR app. Supposed I want to take a vacation in August, and wanted to make sure my time off balance can cover it. BambooHR actually has an API to do just that. You’d make an API call to (bold texts are the expected variables):

https://api.bamboohr.com/api/gateway.php/your_company/v1/employees/employee_id/time_off/calculator?end=balance_date

In return, you’d get a JSON output showing that employee’s available time off types, as well as their balances:

Let’s see how we can build a Katella skill leveraging this API. Once completed, all your team members will have access to this skill.

Login to app.katella.ai as a team admin. Go to Team Settings and select Add a Custom Skill. Let’s walk through each steps.

Triggering the skill

Give the skill a name and enter a few sentences your users may ask to get their balances. Katella uses machine learning-based training so sentences don’t have to be exact. Start with 4-5 sentences and add more later.

Collecting user inputs

A skill may require some user inputs or data from external APIs before it can be executed. In our case, we needs to know the current user’s BambooHR employee Id (to check that user’s balance), as well as a date to check the balance by (balance accrued over time) .

Use the drop down to add

1. a remote input called BAMBOO MY ID, which calls Bamboo API and returns the current user’s employee id
2. a system input DATE, which expects a date from the user

An input can be Required or Optional. Optional inputs will be extracted once from the original sentence, and ignored if not entered. Required inputs will repetitively prompt user, and will not proceed without fulfillment.

For our Date input, we should also set a default value of today, which will auto-populate today’s date if a date is not mentioned by the user.

All inputs collected here are accessible in subsequent steps with our Expression Language. Each input type comes with its own expressions. For example the DATE type reference {input2} will return an ISO standard format yyyy-mm-dd, while {input2.pretty} will return a user friendly text (tomorrow, Friday 6/4,…). Referencing {input1} will just return the Bamboo employee id as a text.

In addition to these inputs, you’ll also have expressions available to get the current user and team (e.g {user.name}, {user.email}, {user.tz}, …).

Making API call

Now that we have all the necessary inputs, time to call BambooHR API to retrieve the time off balance for the current user.

Select Bamboo HR from the list of Apps dropdown. This will provide two things for your skill:

1. The API’s baseURL are pre-filled with your team’s information. In fact, when your Katella admin enables BambooHR app, he/she would have entered specific team information. This will carry over to each API call automatically.
2. Authorization are also handled automatically. Authorization tokens (if any) will be passed automatically when the skill is invoked.

The only thing left is to complete the URL path to append to the App’s baseURL. Here you may reference the inputs above by expressions (in brackets). {input1} would be the Bamboo user id, and {input2} would be the date in ISO format.

Responding to User

Katella connects to different Messaging clients (Slack, Google Hangouts, Microsoft Teams, ..) as well as Google Home/Assistant, so user outputs are abstracted into 3 output widgets: Text, Card, and list of Cards.

To help constructing the widgets, you’ll have full suite of expressions to {input1}, {input2}, {user}, and hundreds of utility methods. The result of your API call will also be available as {output}.

Behind the scene, Katella builds out an Object Graph that normalizes data from different data sources. Navigating the graph is fast, predictable and fun.

Since we may have multiple time off types, we’ll use Cards output. Here’s a Cards response template:

This looks like a lot but it’s actually pretty simple. The first field is the message to be shown before the cards (e.g Here’s your result…). Next you’ll need to enter an expression resolving to a list (which we’ll loop through to generate each Card). The rest of the fields can be a mixture of text and expressions representing each card’s elements.

Since our Bamboo API call returns a JSON list, our loop expression will just be {output}. For each item under the loop, we need to use the {item.*} prefix to access each child elements. Using the BambooHR JSON above, we can construct our Cards widget like this:

Once you hit Save, head over to one of your connected messaging clients and test it out. This is the output of my Google Hangouts Chat:

Pretty it up

Note how “Bereavement” time off type has balance of 0. A look at the JSON shows that its policy type is discretionary (i.e unlimited), which we don’t care about. We can filtered the result by policy type of accruing only using our Expression Language.

Also it would be nice to show a more personal message, as well as the date that the balance is calculated off. You may update your skills as followed:

Here’s what the output will look like (this time in Slack):

Now Katella will only include the time off types that are accruing, as well as telling you the date the balance is calculated off. The Date input is flexible and can understand a variety of utterances like “pto balance in 20 days”, or “what was my sick balance last Nov”

But wait, there’s more

For voice-only devices (Google Home, Alexa), Katella will gracefully handle the different output widgets. In this case, you’ll hear the message line, following by the 1st item of the list. You can control the exact speech by populating the voice-friendly text field for each widget. The field is SSML compatible, so breaks, audio, rate, pitch, volume, .. are supported.

In Summary

Katella can extract intents and entities from English, call your APIs, process the response and construct user replies … all without writing code or hosting servers.

The platform is released in beta, so expect a lot of changes to come. We are only opening up a fraction of the features. In the coming weeks, we’ll turn on custom Apps and Entities training, as well as the revolutionary (disclosure: my opinion) Publish-Subscribe framework to automate and link your business Apps together.

We can’t wait to see what teams will be building with Katella. Let us know at hello@katella.ai.