NAV Navbar
Logo
shell ruby python javascript

Introduction

Welcome to Smartly.ai !

Smartly.ai is a set of tools and algorithms that helps you create, test, deploy and monitor conversational apps.

App Builder

Designing

Have a great conversational app idea?

Let’s go through a few steps to give it life! First let’s create an app by clicking on the Add New App button

Create a bot

You can create two types of bot:

Then give a name and pick a language for your app, the confidence rate is the minimum confidence you are accepting from the natural language understanding engine. Too low you will get false positive, too high you will miss a lot of true positive. We recommand something between 40 and 80%

Designing your Dialog Flow

Each application has a Dialog Flow which defines its behaviour.

In Smartly.AI, the principle of the dialog flow is pretty simple. There is what the user can asks (purple nodes), what the app will answer (blue nodes) and in between some code (black nodes) you may want to execute.

Once your app is designed, everything is automatically built behind the scene to make your app works. That includes Natural Language Processing, Conversational Engine and an API endpoint so you can use your app in whatever app or object you may think of.

If you want a branch of the flow to be accessible at any time, you have to unplug it from the graph like that:

User Says

The User Input object represents what the user can say in a certain context. It’s represented by a user icon in a purple node.

A User Input is composed of an intent

App Answers

The app answers object is a modelization of what the bot should say in a certain context. The bot output is represented by a robot icon in a blue node.

You can give a name to each node, define several answers and reprompts messages. Reprompts message are contextual “error messages”. Their goal is to be more specific and helpful than the sadly common “Sorry I didn’t get that”.

Welcome State

A special node called “Welcome state” is used to begin dialog flows. It’s represented by a robot icon in a blue node. In this state you can modelize what the bot should say when your app is launched.

When you double click, a window allowing you to set up many things appears. Let’s see what’s inside a bot answer.

Add new language

Once you are happy with your app, you can add translation by clicking the Add New Language button.

Functions

In order to provide you with a fully serverless solution, the solution comes with a set of prebuilt functions. The first one available today is the NodeJS function.

The NodeJs node can only be called after an output answer.

When you double click on </>NodeJs node , This custom code editor will be displayed.

You can change the editor’s theme to dark and also make the editor full screen.

With the custom code editor you can:

Available NodeJS modules on the server are:

Coding reference

Here is the main values that you can manipulate programatically in your bot:

Testing

With Smartly.ai, you can try your bot as you are bluiding it ! Simply talk to your bot by text or by voice in our built-in simulator:

If you want more insight, you can go on the API output to see what is really happening when you are talking to your bot, You can also check the api reference here:

Using console.log('This is a test'), you can log in your NodeJS code and get them in the console tab.

Components

Intents

To create an intent you should double click on your User Says node (purple node).

Create Intent

For this click on the Create button. Then give a name to your intent and give it a first sample.
Before saving you have to click Add this! in order to add your intent to your user sentences.

For a better performance, we recommand you to create at least 5 sentences in each intent.

In order to create light intents (avoid repetition) you can use entities.

Integrations

Here is available the channels for a text app:

Voice Application

Here is available the channels for a voice application

Amazon Alexa

Click on Alexa Integration.
There you will find a set of informations to paste on your Alexa Developer Account.
Here is a brief overview of the data you will have to copy on your Amazon
Developer account.

Copy the endpoint over in Alexa skill configuration.

You can also use the alexa card from smartly to do that, simply add the object alexa_card to the output:


output.alexa_card = {
      "type": "Simple",
      "title": "Example of Card Title",
      "content": "Example of card content. This card has just plain text content.\nThe content is formatted with line breaks to improve readability."
    }

Once you have designed your skill

That’s it, all done!

You can now test / update and even publish your application in the Alexa Store 🙂

For more information about the alexa card, see the official documentation (see javascript tab in code part).
For more description about the format of alexa input see here.

Google Assistant

Assistant integration allow you to integrate your bot to your google assistant application, to do that you have to follow these steps:

1- Click on Assistant, this window will appear.

If you intend to use account linking and Google Home integration, you should check “Google Assistant Account Linking” box so the bot would ask the user to signin before continuing the conversation.

2- Go to Action on Google

3- Click on Add/Import Project, this window will appear, you have to fill the project name

4- Once the project is created you will be redirected to this page Assistant app name

5- Click on Action SDK in order to find Google Project ID and copy it.

6- Paste the Project ID in your Assistant Integration like this:

7- Click on App information in Assistant app name, this window will appear

Click on Add, and fill Name, Details, Images, Testing Instructions, Contact Details and Privacy and Content

Here you have to put the same project name which you will put it in your Assistant Integration like this:

8- The last step if for you to fill the Google Home Token, to do that go to Google Home Access and cick on AUTORISER

Once done you will be redirected to this page:

9- Copy this code and paste it here

10- Finally click on preview to finish integration

here you can test your integration but before testing you have to check your surface

click on surface and choose Google Home

Here are the commands that manage data ( google save in your account ) and change your activity Activity controls

assistant_answer


    assistant_answer.initialPrompts = [{
      ssml: '<speak>This is a hello from NodeJS</speak>'
    }];

    assistant_answer.noInputPrompts = [];

    assistant_answer = {
      initialPrompts: [{ 
        ssml: '<speak>This is a hello from NodeJS</speak>'
      }],
      noInputPrompts = []
    }

We can manage data send it to Google Assistant using two variables assistant_answer and request_answer

The Assistant answer: allow us to send anything to the Google Action.

assistant_request


{
  "user":{
    "user_id":"<user_id>",
    "permissions":[

    ],
    "locale":"en-US"
  },
  "conversation":{
    "conversation_id":"<conversation_id>",
    "type":2,
    "conversation_token":"<conversation_token>"
  },
  "inputs":[
    {
      "intent":"assistant.intent.action.TEXT",
      "raw_inputs":[
        {
          "input_type":3,
          "query":"<input>",
          "annotation_sets":[

          ]
        }
      ],
      "arguments":[
        {
          "name":"text",
          "raw_text": "<input>",
          "text_value": "<input>"
        }
      ]
    }
  ],
  "surface":{
    "capabilities":[
      {
        "name":"actions.capability.AUDIO_OUTPUT"
      },
      {
        "name":"actions.capability.SCREEN_OUTPUT"
      }
    ]
  },
  "device":{

  },
  "is_in_sandbox":true
}

The Assistant request as received from Google.

SMS

For all the SMS transactions we recommend Twilio.

If you want your user to be able to chat with your app via sms you have to follow these steps:

1- Go on your sms account

-> programmable sms

-> messaging services

2- Copy the request url

3- Click save on the bottom

WebChat

The WebChat integration allows you to adress your users via any website !

You can choose a color for your chatbox.
Once done a short code snippet in javascript is provided so you can implement it in any website 🙂.

Here you find the demo

And here is what it will look like in your website:

Here you go! You can now serve your customers with a bot or with your customer support team 🙂, and in WebChat conversation we can distinguish actions performed by a human being (answers), and similar actions being performed by the bot (as shown in the picture of the one who answers).

For mobile users, the WebChat is mobile friendly and it is more bearable for you, the chat box will be on full screen with your devices in order to make conversation easier with your customers.
And here is what it will look like in your mobile phone:

Messenger

Messenger integration allow you to add your bot to Facebook Messenger. To do that you have to follow these steps:

1- Click on messenger, this window will appear:

In this step you have to fill the Token verify

2- Create your facebook page

3- Go to Developers Facebook

4- Add a new App

5- After creating the new app you will be redirected to Product Setup, in this state you have to get Messenger started

6- Once the messenger has started you have to generate Page Access Token and copy it

7- Paste the Page Access Token in your messenger integration like that

8- Hit Deploy my App

9- Now in developers facebook go to set up webhook

10- To activate the bot you have to subscribe your webhook to the page events

Finally you can start talking to the Bot on Messenger

messenger_user

{
    "first_name":"Smartly",
    "last_name":"AI",
    "profile_pic":"https://scontent.ftun3-1.fna.fbcdn.net/v/t1.0-9/18057955_1697168273645572_7528083323191086401_n.png?oh=ca6b53926e08b23c590bea756405b1fe&oe=598B4F5C",
    "locale":"fr_FR",
    "timezone":1,
    "gender":"male",
    "sender":"1310677675254316"
}

messenger_request


    {
      "recipient":{"id":"1696999743662425"},
      "timestamp":1493138028508,
      "sender":{"id":"1285562291541696"},
      "postback":{"payload":"GET_STARTED_PAYLOAD"}
    }

messenger_answer

  {
   "attachment":{
     "type":"template",
     "payload":{
       "template_type":"generic",
       "elements":[
          {
           "title":"Welcome to Smartly",
           "image_url":"https://bots.smartly.ai",
           "subtitle":"We've got the bot for everyone.",
           "default_action": {
             "type": "web_url",
             "url": "https://bots.smartly.ai",
             "messenger_extensions": true,
             "webview_height_ratio": "tall",
             "fallback_url": "https://bots.smartly.ai"
           },
           "buttons":[
             {
               "type":"web_url",
               "url":"https://bots.smartly.ai",
               "title":"View Website"
             },{
               "type":"postback",
               "title":"Start Chatting",
               "payload":"DEVELOPER_DEFINED_PAYLOAD"
             }              
           ]      
         }
       ]
     }
   }
 }

To Customize our Messages according to the attributes of messenger users (first name, last name etc…), for example if we want to say
hello username how are you ? You have to go to the builder and add a NodeJs node then add these line of code:

output.answer = "hello "+messenger_user.first_name + " " +messenger_user.last_name + " How are you ?";

The same for messenger requests, if we want to get for example the facebook page of the sender we can add this line of code:

output.answer = "sender is : www.facebook.com/"+messenger_request.recipient.id;

messenger_answer
If we want to add many elements like images, buttons, carousels etc… to the bot’s messages, we have to prepare our json containing all elements we need it, and push it in the messenger_answer table messenger_answer.push()

Datasets

Manage Intent

To manage your intents:

1. Go to your Dashboard.
2. Click Datasets.

The below window appears, allowing you to create, search, edit and delete intents:

Entities

Imagine, you want the user to be able to say:

Entities are here to solve this issue. Using entities we will be able to have something like:

I want a pizza with {toppings}

One more time, the smartly community has already created some of the basic entities. However, you can create your own entities with many elements.

Manage Entities

To manage your entities:

  1. Go to the Dashboard.
  2. Go to Datasets.
  3. Click entities in the header.

The below window appears allowing you to create, search, edit and delete your entities.

Inbox

The inbox contains all the messages received by selected bot, we can search the understood and not understood messages. It allows us to know and control the performance of the bot and to be able to understand the bot’s behaviour and improve it( add the understood logs to our intent, add an existing intent to our selected log).

we can also delete and filter logs by language, channels and status.

You can find a targeted message by using the search bar.

Conversations

The Smartly.ai Conversations is the perfect tool to combine the best of human and machine intelligence. Once one of your bot is integrated to a service like messenger or google home, you will automatically see, in real time, all your user conversations with your bot. Thanks to the Conversations, you don’t just create conversational bots, but also an amazing experience for all of your customers and a new kind of service.

Through an interface designed like a direct message platform, you will be able in a couple of minutes to use the power of the Conversations. Beyond the bot management aspect, the Smartly.ai Conversations is the way to increase your customer satisfaction and act quickly if your bot seems to be struggled in a rich conversation.

The left menu list all the customers which are currently, or were in the past, chatting with your bot, in this menu we analyze the conversation of each customer by classifying it into 3 lists.

You can find a targeted customer by using the search bar.

Once you enter a conversation, you can see the full conversation of a user with your bot. But even more, YOU can chat directly with your customer, regardless of the platform (messenger, sms, skype, google home, …). All the messages that weren’t understood by your bot are indicated by percentages, and you will be able to understand your bot’s behaviour and improve it.

Each customer has its own profile. Customizable, it allows you a²nd your bot, to know your customer better.

System entities

The following entities can be retrieved by an intent (examples under the name):

API

Authentication

Authenticate to get the token

# With this curl you can get a token
curl -H "Content-Type: application/json" -X POST -d '{"username":"your username","password":"your password","grant_type":"password","client_id":"test","client_secret":"test"}' -k https://apis.smartly.ai/api/auth/oauth/token

HTTPS Request
POST https://apis.smartly.ai/api/auth/oauth/token

Query Parameters

Parameter Required Default Description
grant_type true password the grant type
password true The password of the user
username true The email of the user
client_id true Authentication client_id
client_secret true Authentification client_secret

JSON successful authentication response

{
    "access_token":"YOUR TOKEN",
    "refresh_token":"REFRESH TOKEN",
    "expires_in":3600,
    "token_type":"Bearer"
}

There are two more parameters (client_id, client_secret) needed to get the authentication token
You can find the client_id and the client_secret from your profile page.

Use the token to consume our API

Make sure to replace TOKEN with your API key.

## With shell, you can just add the correct header with each request
-H "Authorization: Bearer  YOUR TOKEN"

Smartly expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer YOUR TOKEN

Dialog

Feed the dialog

# NEW_DIALOG_SESSION
curl -H "Authorization: Bearer YOUR TOKEN " -H "Content-Type: application/json" -X POST -d '{ "platform": "simulator", "event_name": "NEW_DIALOG_SESSION", "user_id": "132465abb031efa21d66", "skill_id": "58e6211c97fbc1254741c607", "lang": "en-us", "user_data": { "sender": "132465abb031efa21d66" }, "input": "" }' -k https://apis.smartly.ai/api/dialog/
# NEW_INPUT
curl -H "Authorization: Bearer YOUR TOKEN " -H "Content-Type: application/json" -X POST -d '{ "platform": "simulator", "event_name": "NEW_INPUT", "user_id": "132465abb031efa21d66", "skill_id": "58e6211c97fbc1254741c607", "lang": "en-us", "user_data": { "sender": "132465abb031efa21d66" }, "input": "test" }' -k https://apis.smartly.ai/api/dialog/

The above command returns JSON structured like this:

{
 "input":"What time is it ?",
 "intent":"Get Time",
 "entities":{},
 "understood":true,
 "state_id":"kthm4r7gr5",
 "state_name":"Welcome State",
 "answer":"It is 4pm",
 "reprompt":null,
 "display":"",
 "audio_file":"",
 "processing_time":0.001,
 "short_term_memory":{
   "last_answer":"Welcome on your Chatbot",
   "last_reprompt":null
 },
 "long_term_memory":{}
 "end_session":false,
}

this endpoint allows you to send requests to your conversational app.

HTTPS Request
POST https://apis.smartly.ai/api/dialog/

Query Parameters

Parameter Default Required Description
user_id true A unique user id
skill_id true The id of the bot
event_name true The event name could be either (NEW_DIALOG_SESSION, NEW_INPUT)

NEW_DIALOG_SESSION
This event will reset the conversation and return you to the Welcome Message

NEW_INPUT
Use this anytime the user speaks, it will make the conversation flow while keeping the context
lang en-gb false The language you want to use in this conversatoin

en-us for English (United States)

en-gb for English (United Kingdom)

en-au for English (Australia)

en-ca for English (Canada)

en-in for English (India)

fr-fr for French (France)

fr-ca for French (Canada)

de-de for German (Germany)

input empty true The input said by the user
platform empty false
user_data {} false User’s data

Errors

The Smartly API uses the following error codes:

Error

Code Meaning
400 Bad Request – Your request was wrong
401 Unauthorized – Your API key is wrong
403 Forbidden – You don’t have the scope to do this action
404 Not Found – The ressource could not be found
429 Too Many Requests – You’re requesting too many ressources
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintanance. Please try again later.

Glossary

Dialog Flow
A visual representation of how we expect the interactions between the user and the conversational app to happen.

Welcome State
This is where your app starts, the system will start the conversation with the message provided in this object.

Intents
An intent is a set of expressions that express the same meaning. As we are using machine learning algorithms, you should try to maximize the number of expressions to enhance the system accuracy.

Entities
An entity is a variable part of a user expression, it can be a name, a destination, a date or an element coming from a list.

Change Log

[2.3.0] - 20/10/2017

New

Improved

[2.2.3] - 21/09/2017

New

Improved

Fixed

[2.2.2] - 18/09/2017

Improved

Fixed

[2.2.1] - 11/09/2017

Improved

[2.2.0] - 11/09/2017

Improved

Fixed

[2.1.19] - 25/08/2017

New

Improved

Fixed

[2.1.18] - 25/08/2017

Improved

Fixed

[2.1.17] - 23/08/2017

New

Improved

Fixed

[2.1.16] - 21/08/2017

Improved

[2.1.15] - 18/08/2017

Improved

Fixed

[2.1.14] - 15/08/2017

New

Improved

Fixed

[2.1.13] - 11/08/2017

Improved

[2.1.12] - 10/08/2017

Improved

* Several UI tweaks.

[2.1.11] - 09/08/2017

Fixed

* An issue where an sentence with special characters couldn’t be deleted in an intent * An issue where two sentences at a time where added while editing an intent.

[2.1.10] - 08/08/2017

Fixed

[2.1.9] - 07/08/2017

New

Fixed

[2.1.8] - 04/08/2017

Improved

Fixed

[2.1.7] - 02/08/2017

New

[2.1.6] - 02/08/2017

Fixed

[2.1.5] - 01/08/2017

Fixed

Changed

[2.1.4] - 01/08/2017

Improved

[2.1.3] - 30/07/2017

Improved

[2.1.2] - 26/07/2017

Fixed

[2.1.1] - 24/07/2017

New

Improved

[2.0.0] 17/07/2017

Added

Improved