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

Create a bot

You can create two types of bot:

Tap Show Advanced Settings to create your app with more details.

Chat Bot

A Chat Bot will only be connectable to chat platforms like these:

Voice Application

A Voice Application will only be connectable to voice platforms like the followings:

Dialog Flow

Each application has a Dialog Flow which defines its behaviour.

A Dialog Flow is composed 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/do in a certain context. The bot output is represented by a robot icon in a blue node.

When you double click, a window allowing you to set up many things appears.

Before saving click Add this! to add messages to your app answers

Welcome State

A special node called “Welcome state” was built in Smartly.ai, it 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 and do when your bot 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.

Before saving click Add this! to add a welcome message to your Welcome State

In the dialog flow, you may use this kind of message to help the user answering a specific question. The reprompt message has the same properties as a classic output message. The reprompt message will be played if:

Tasks to execute

Smartly Blue’s strategy is to provide many pre-configured modules to make it easier for developers to build their conversational apps. This list of functions is your home 🙂.

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:

Coding reference

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

Available NodeJS modules on the server are:

Add new language

Allows you to add another dialog flow using the chosen language.

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 output tab to see what is really happening when you are talking to your bot:

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).

Enjoy the community’s intents

In many cases you may find the intent you have in mind (or something close) have already been created by someone in the community. To check this, you can browse the intent search engine by clicking the Search button.

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

Smartly.ai offers multiple integrations according to your type of bot (see type of bots)

As of today available options are:

The same bot can be deployed on one or more integrations at the same time.

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.

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.

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

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
}

assistant_request: contains the send data 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 misunderstood 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. we can also filter logs by language and channels.

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

Profile

Your profile includes your informations where you can choose your photo and edit your personal informations.
You can see also your API keys like client_id and client_secret.

To add or edit informations that’s shown on your profile:

  1. Go to the Dashboard.
  2. Go to My Account.
  3. Click profile.

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 slack, 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, slack, …). 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.

Languages

At the moment 4 languages should work and should be proposed when creating an agent:

System entities

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

To enable system entity retrieving, you can create an entity with the type field being one of the types above, and add it in an intent.

API

We have language bindings in Shell and JavaScript! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

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/oauth/token

HTTPS Request
POST https://auth.smartly.ai/api/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":"{{ USER 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 from your profile page, and the client_secret from profile page also.

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 gives you the next prompt for your dialog.

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 lang used in the dialog

en-gb for English GB

en-us for English US

fr-fr for French

de-de for German
input empty true The input given to the bot
platform empty false Platform’s type
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.1.14] - 15/08/2017

New

Improved

Fixed

[2.1.13] - 11/08/2017

Changed

Fixed

[2.1.12] - 10/08/2017

Fixed

Changed

[2.1.11] - 09/08/2017

Fixed

[2.1.10] - 08/08/2017

Fixed

Changed

[2.1.9] - 07/08/2017

New

Improved

Fixed

[2.1.8] - 04/08/2017

Changed

Fixed

[2.1.7] - 02/08/2017

New

[2.1.6] - 02/08/2017

New

Fixed

[2.1.5] - 01/08/2017

Fixed

Chnaged

[2.1.4] - 01/08/2017

New

[2.1.3] - 30/07/2017

New

Fixed

[2.1.2] - 26/07/2017

Fixed

[2.1.1] - 24/07/2017

New

Improved

[2.0.0] 17/07/2017

Added

Improved