Create your first Chatbot

You can use any of the supported programming languages to create your first chatbot. This documentation currently support Python, JavaScript and Golang.

note

As mentioned Before almost all of language based SDK with exception of Python are community maintained and not officially supported by Sarufi. If you find any issues with the SDK, please create an issue on the respective GitHub repository. Also If you see missing documentation or typos or bugs for any of the SDK, You're welcome to contribute

Draft Architecture

Before we start coding, let's first draft the architecture of our chatbot. Here an oversimplified version of the architecture for our chatbot. Sarufi will handle intents training, intent inference, and dialog management. We will be handling the application logic and the user interface.

Installations

Select your language of preference to get instructions on installing SDK

Python

Its good to use virtual environment. You can read more on Virtual Environment. So, lets create a virtual environment ➡️ activate it ➡️ install sarufi.

python -m venv chatbot
source chatbot/bin/activate
pip install --upgrade sarufi

JavaScript

npm install sarufi

Golang

go mod init chatbot
go get github.com/sarufi-io/sarufi-golang-sdk

Sign up to Sarufi.io

To use the Sarufi.io SDK, you'll need to create an account on the Sarufi.io website. Here's how:

1. Go to the Sarufi.io website and click on the "Sign Up" button in the top right corner of the screen.

   

2. Choose your preferred sign-up method (email, GitHub, or Google).

3. Follow the prompts to complete the sign-up process.

4. Once you've signed up, log in to your Sarufi.io account.

Obtaining Your API KEY

After logging in to your Sarufi.io account, you can obtain your client ID and client secret by following these steps:

1. Go to your Sarufi.io profile settings page.

2. Scroll down to the Authorization section.

3. Here, you'll find your API KEY.

   

4. Copy these values and use them in your Sarufi.io SDK client configuration.

That's it! With your API KEY, you can now use the Sarufi.io SDK to interact with the platform.

Python

from sarufi import Sarufi
sarufi = Sarufi(api_key='your API KEY')

JavaScript

import sarufi from 'sarufi'
sarufi.login({ api_key: YOUR_API_KEY })

Golang

var app sarufi.Application

app.GetToken("your_api_key")

Create a Chatbot

Now that we have successfully authenticated with Sarufi, we can create an empty chatbot, with 0 intents and 0 utterances.

The below image shows overview of the steps it takes to create your first chatbot with Sarufi

Creating an empty chatbot

This is the first step in creating your first chatbot. You can use the following code to create an empty chatbot.

Python

>>> from sarufi import Sarufi
>>> sarufi = Sarufi(api_key='your API KEY')
>>> chatbot = sarufi.create_bot(name='My First Chatbot')
2022-09-12 15:42:02,821 - root - INFO - Creating bot
>>> chatbot
Bot(id=13, name=My First Chatbot)

JavaScript

We supply chatbot details

Request payload

{
  "name": "YOUR AWESOME BOT NAME",
  "description": "PUT DESCRIPTION HERE",
  "industry": "YOUR BOT INDUSTRY",
  "intents": {},
  "flows": {},
}

Then we call

// call this first if you haven't logged in.
sarufi.login({ api_key: YOUR_API_KEY }) 

sarufi.createBot({bot: REQUEST PAYLOAD})

Response for successful bot creation

{
  "success": true,
  "bot": {  "name": "YOUR AWESOME BOT NAME",
            "description": "PUT DESCRIPTION HERE",
            "user_id": "YOUR ID",
            "industry": "YOUR BOT INDUSTRY",
            "intents": {},
            "flows": {},
            "updated_at": "DATE THE BOT WAS LAST UPDATED",
            "id": "BOT ID",
            "model_name": "BOT MODEL NAME",
            "created_at": "DATE THE BOT WAS CREATED"
  },
  "chat": "({message: string, chat_id?: uknown}) => RETURNS CHAT RESPONSE"
}

Golang

visible_on_community := true // Set it to false if you don't want it visible on the playground

example_bot, err := app.CreateBot("Name of your bot", "Description", "Industry", visible_on_community)
if err != nil {
    log.Fatal(err)
}

fmt.Println(example_bot.Name)

Dashboard

jasdhajsdhaj djahdaj

note

To Create a bot, each sdk has it method. Take note of the naming

SDK	Method used	Return Value
Python	create_bot()	Bot object
JavaScript	createBot()	JSON object
Golang	CreateBot()	Sarufi Bot Type

Start a conversation with your Chatbot

Now that we have successfully created an empty chatbot, we can start a conversation with our chatbot and see how it responds. You can use the following code to start a conversation with our chatbot.

Here is an example of how to start a conversation with our chatbot.

Python

✅ To start conversation with a bot you can use one of the methods below

Class name	Method	Arguments
Sarufi	chat()	bot_id , chat_id and message
Bot	respond()	chat_id and message

By default, chat_id is set to a random UUID. You can pass your own chat_id if you want to continue the conversation with the same user.

Here are examples on each method

Chat method

  >>> from sarufi import Sarufi
  >>> sarufi = Sarufi(api_key='your API KEY')
  >>> sarufi.chat(bot_id=5, message='Hello')

Respond method

  >>> chatbot = sarufi.get_bot(13)
  >>> chatbot.respond('Hey')
  2022-09-12 15:44:02,811 - root - INFO - Sending message to bot and returning response
  2022-09-12 15:44:07,078 - root - INFO - Status code: 200
  2022-09-12 15:44:07,078 - root - INFO - Message sent successfully
  #here is the response
  {'message': 'Intent for this message is missing in [FLOW]'}

JavaScript

You can either use sarufi.chat() method or chatbot.chat() method on the bot response.

Class name	Method	Arguments	Return Type
Sarufi	chat()	bot_id , message and chat_id(optional)	JSON object
Bot	chat()	message,chat_id	JSON object

You will need to pass the chat_id and message to the chat() method. By default, chat_id is set to a random UUID.

You can pass your own chat_id if you want to continue the conversation with the same user.

//chatbot.chat()
> const chatbot = await sarufi.getBot({id: 45})
> await chatbot.chat({message: "Hey"})
{
  message: 'Intent for this message is missing in [FLOW]'
}

//sarufi.chat
> await sarufi.chat({ message: 'Hey', bot_id: 1 })

Golang

To get a list of available bots use bot.GetBots(), this will return a json response of all your bots and their details. To get a specific bot use bot.GetBot(bot_id). This will return a bot object.

To start a conversation, use bot.Respond("message", "message_type"). For now only text message types are supported:

if err = example_bot.Respond("Hey", "general"); err != nil {
    log.Fatal(err)
}

fmt.Println(example_bot.Conversation.Message)

note

As you can see, our chatbot is not able to understand the message we sent but replied us with a predefined response. This is because we haven't trained our chatbot yet. We will be training our chatbot in the next section.

Another cool way to test your chatbot is to use the Sarufi Playground. By Default when you create a chatbot, it is set to public. All you need to instantly test your chatbot is to go Sarufi Community playground and search for your chatbot.

Adding Intents and flow

We are going to create a bot that will help us with ordering a 🍕 pizza

Add Intent

Let's now create an intent that will help us order a pizza and also add some utterances to that intent. You can use the following code to create an intent and add some utterances to that intent.

To make more interactive, let's general intents like greets, order_pizza, goodbye and add some utterances to those intents.

Python

>>> from sarufi import Sarufi
>>> sarufi = Sarufi(api_key='your API KEY')
>>> chatbot = sarufi.get_bot(13)
#We assign intents attribute a dict with intent name and and intents
# dict {<intent name>:[list of all related keywords to trigger the intent]}
>>> chatbot.intents = {
...     'greets': ['hey', 'hello', 'hi', 'howdy', 'hola', 'greetings', 'good morning', 'good afternoon', 'good evening'],
...     'goodbye': ['bye', 'goodbye', 'see you later', 'see you soon', 'see you', 'talk to you later', 'talk to you soon', 'talk to you'],
...     'order_pizza': ['I need a pizza', 'I want a pizza', 'order a pizza', 'I want to order a pizza']}
2022-09-12 15:55:06,696 - root - INFO - Updating bot
2022-09-12 15:55:07,972 - root - INFO - Bot(id=13, name=My First Chatbot)
#We get bot's intents
>>> chatbot.intents
{'greets': ['hey', 'hello', 'hi', 'howdy', 'hola', 'greetings', 'good morning', 'good afternoon', 'good evening'], 'goodbye': ['bye', 'goodbye', 'see you later', 'see you soon', 'see you', 'talk to you later', 'talk to you soon', 'talk to you'], 'order_pizza': ['I need a pizza', 'I want a pizza', 'order a pizza', 'I want to order a pizza']}

JavaScript

We are going to use Sarufi UpdateBot method we pass it a dict with intents and bot_id.

> const chatbot = await sarufi.getBot({ id: 45 });
> const bot = {
  intents: {
    greets: [
      'hey',
      'hello',
      'hi',
      'howdy',
      'hola',
      'greetings',
      'good morning',
      'good afternoon',
      'good evening',
    ],
    goodbye: [
      'bye',
      'goodbye',
      'see you later',
      'see you soon',
      'see you',
      'talk to you later',
      'talk to you soon',
      'talk to you',
    ],
    order_pizza: [
      'I need a pizza',
      'I want a pizza',
      'order a pizza',
      'I want to order a pizza',
    ],
  },
};
 await sarufi.updateBot({ bot, id: chatbot.id });

Golang

// Create a string in JSON format
intents := `
{
    "goodbye": ["bye", "goodbye", "see ya"],
    "greets": ["hey", "hello", "hi"],
    "order_pizza": ["I need pizza", "I want pizza"]
}`

if err := example_bot.CreateIntents(intents); err != nil {
    log.Fatal(err)
}

// For changes to take effect
if err = app.UpdateBot(example_bot); err != nil {
    log.Fatal(err)
}

Try a conversation after adding intents

Now that we have successfully added some intents and utterances to our chatbot, let's start a conversation with our chatbot and see how it responds. You can use the following code to start a conversation with our chatbot.

Python

>>> chatbot.respond("Hey")
2022-09-12 15:56:16,078 - root - INFO - Sending message to bot and returning response
2022-09-12 15:56:17,279 - root - INFO - Status code: 200
2022-09-12 15:56:17,279 - root - INFO - Message sent successfully
{'message': 'Intent for this message is missing in [FLOW]'}

JavaScript

> await chatbot.chat({message: 'Hey'})

Golang

if err = example_bot.Respond("Hey", "general"); err != nil {
    log.Fatal(err)
}

fmt.Println(example_bot.Conversation.Message)

note

You might wondering like but we trained it, yes ofcourse we trained it but we haven't given a flow on how to respond to the user. We will be adding a flow in the next section.

Lets add a flow

Flow is a directed graph that defines the conversation flow between the user and the chatbot. Flow is defined using the JSON format. where each node is an intent and each edge is a response to the user message & the next intent to be triggered.

note

You can have nodes that are not intents. In that case, the node will be treated as a response to the user message. If you want to end the conversation, you can add a node with the name end.

Let's now add a flow to our chatbot. You can use the following code to add a flow to our chatbot.

Python

>>> chatbot.flow = {
...     'greets': {
...         'message': ['Hi, How can I help you?'],
...         'next_state': 'end'
...     },
...     'order_pizza': {
...         'message': ['Sure, How many pizzas would you like to order?'],
...         'next_state': 'number_of_pizzas'
...     },
...     'number_of_pizzas': {
...         'message': ['Sure, What would you like to have on your pizza?'],
...         'next_state': 'pizza_toppings'
...     },
...     'pizza_toppings': {
...         'message': ['Cool, Whats your address ?'],
...         'next_state': 'address'
...     },
...     'address': {
...         'message': ['Sure, What is your phone number ?'],
...         'next_state': 'phone_number'
...     },
...     'phone_number': {
...         'message': ['Your order has been placed.', 'Thank you for ordering with us.'],
...         'next_state': 'end'
...     },
...     'goodbye': {
...         'message': ['Bye', 'See you soon'],
...         'next_state': 'end'
...     }
... }

JavaScript

> const chatbot = await sarufi.getBot({ id: 45 });
> const bot = {
  flows: {
  "greets": {
    "message": [
      "Hi, How can I help you?"
    ],
    "next_state": "end"
  },
  "order_pizza": {
    "message": [
      "Sure, How many pizzas would you like to order?"
    ],
    "next_state": "number_of_pizzas"
  },
  "number_of_pizzas": {
    "message": [
      "Sure, What would you like to have on your pizza?"
    ],
    "next_state": "pizza_toppings"
  },
  "pizza_toppings": {
    "message": [
      "Cool, Whats your address ?"
    ],
    "next_state": "address"
  },
  "address": {
    "message": [
      "Sure, What is your phone number ?"
    ],
    "next_state": "phone_number"
  },
  "phone_number": {
    "message": [
      "Your order has been placed.",
      "Thank you for ordering with us."
    ],
    "next_state": "end"
  },
  "goodbye": {
    "message": [
      "Bye",
      "See you soon"
    ],
    "next_state": "end"
  }
}
};
 await sarufi.updateBot({ bot, id: chatbot.id });

Golang

// create a string in JSON format
newFlow := `
{
     "greets": {"message": ["Hi, How can I help you?"], "next_state": "end"},
     "order_pizza": {
     "message": ["Sure, How many pizzas would you like to order?"],
     "next_state": "number_of_pizzas"
 },
     "number_of_pizzas": {
     "message": [
         "Sure, What would you like to have on your pizza?",
         "1. Cheese",
         "2. Pepperoni",
         "3. Both"
     ],
     "next_state": "choice_pizza_toppings"
 },
     "choice_pizza_toppings": {
     "1": "pizza_toppings",
     "2": "pizza_toppings",
     "3": "pizza_toppings",
     "fallback_message": ["Sorry, the topping you chose is not available."]
 },
     "pizza_toppings": {
     "message": ["Cool, Whats your address ?"],
     "next_state": "address"
 },
     "address": {
     "message": ["Sure, What is your phone number ?"],
     "next_state": "phone_number"
 },
     "phone_number": {
     "message": ["Your order has been placed.", "Thank you for ordering with us."],
     "next_state": "end"
 },
     "goodbye": {"message": ["Bye", "See you soon"], "next_state": "end"}
}`

if err = example_bot.CreateFlows(newFlow); err != nil {
        fmt.Println(err)
    }

app.UpdateBot(example_bot) // for changes to take effect

Conversation with our chatbot after adding flow

Now that we have successfully added a flow to our chatbot, let's start a conversation with our chatbot and see how it responds. You can use the following code to start a conversation with our chatbot.

>>> chatbot.respond('Hey')
{'message': ['Hi, How can I help you?']}
>>> chatbot.respond('Bye')
{'message': ['Bye', 'See you soon']}
>>> chatbot.respond('I want to order pizza')
{'message': ['Sure, How many pizzas would you like to order?']}
>>> chatbot.respond('3')
{'message': ['Sure, What would you like to have on your pizza?']}
>>> chatbot.respond('tomato')
{'message': ['Cool, Whats your address ?']}
>>> chatbot.respond('123, Main Street, New York')
{'message': ['Sure, What is your phone number ?']}
>>> chatbot.respond('+255783483934')
{'message': ['Your order has been placed.', 'Thank you for ordering with us.']}

note

You can see that our chatbot is able to understand the user message and respond to the user message. This is because we have trained our chatbot with intents and utterances and also added a flow to our chatbot.

Conclusion

In this tutorial, we have learned how to create a chatbot using Sarufi. We have also learned how to train our chatbot with intents and utterances and also how to add a flow to our chatbot. We have also learned how to start a conversation with our chatbot and how to respond to the user message.