Scripting - rikai-network/docs GitHub Wiki

Rikai Labs bot writing language is called Ribot. Ribot translates a person’s stories into a language that our Chatbot understands.

To learn how to speak RiBot, you will need to learn a series of vocabulary, syntax and punctuation to tell the chatbot what to do. But unlike people, bots are easily confused by bad punctuation, syntax, spelling errors and unclear commands.

To write your first story or lesson, you will first need to write a new chatbot. Think of a chatbot as a teacher, or a person. The core components of a chatbot are

1. Topics - Provide context
2. Triggers - Tell the bot what to look for
3. Responses - Tells the chatbot how to respond

At the most basic level, Ribot works by looking for a unique trigger within a topic and then giving a specific response to that trigger.

Punctuation
The chatbot understands what is a topic, trigger or response by looking for specific punctuation in the script. Some common punctuation that you will see include: (More on these later)

+ 	(triggers)
- 	(responses)
^ 	(extenders)
> 	(opens a topic or variable)
< 	(closes a topic or variable)
// 	(comments for bot authors)

Topics
Topics are containers which hold many triggers and responses. Topics provide context to the chatbot about what is happening in a conversation.

For example, a normal response to the word yes has very different meanings depending on the context. The chatbot doesn't innately understand like humans do. So to create context, we have to create topics.

The chatbot knows that you are opening a new topic by looking for > topic xxxyyy at the beginning of a block and a < topic at the end of that block. In practice, it looks like:

> topic new-topic inherits shared

< topic

NOTE

1. Include a space AFTER the the > and after the word topic
2. Topic names must be lowercase and cannot contain spaces.
3. When naming topics please follow the following naming convention
   > topic lessonname-action
   > topic salesnegotiation-ask
4. Topics MUST be unique.
5. You MUST remember to close your topic with < topic

Triggers
Triggers are always preceded by a + sign
Triggers are what the bot listens for the user to say. When a trigger is found the bot then knows what to respond with.

+ i am a trigger

It is important to remember a couple of things about triggers:

1. Each topic can contain many triggers.
2. Each trigger MUST be unique within its own topic.
3. Triggers can contain spaces.
4. Triggers must ALWAYS be lower case.
5. Triggers can NEVER contain ANY punctuation.
6. If you include punctuation or capitalization, you will break and confuse your bot.

GOOD Trigger:

+ i am a trigger

BAD Trigger:

+ It's nice to meet you!

BAD Trigger:

+ It is nice to meet you

Responses
Responses are the specific response that your bot will give you when it hears a trigger.
Responses are always preceded by a – sign and look like:

  + i am the trigger
  - I am the Response!

NOTE

1. Every trigger must have at least one response.
2. Responses can have punctuation, capitalization, images, audio files and emojis.

Putting Things Together
The ^ is another piece of punctuation that allows you to read the Ribot code easier.
The ^ is not essential like the +, - , > or < BUT it allows you to write code that is more readable and easy for the author to understand. It will insert a newline into the bot’s output.

> topic intro inherits shared

  + trigger
    - This is a response:
    ^ The response can be extended 
    ^ on a few lines with ^ marks

< topic

When writing these scripts, every new line that contains text MUST have a piece of punctuation in front of it. If your line is not a topic, trigger or response, then it MUST have a ^ in front of it. If you don’t have a piece of punctuation in front of the chatbot it will become confused.

Linking Triggers Together
You can link triggers together by using the ^ /goto triggername format. This is important because it allows you to create narratives and structure to your lessons.

If you don't have a ^ /goto triggername that extends a response, the chatbot will wait for an nput from the users to tell it what to do next.

> topic intro inherits shared

  + start
    - This is the first trigger
    ^ /goto prompt

  + prompt
    - This is the second trigger

< topic

NOTES

• By default, the bot is waiting for either the student or the author to say something to it. If you do not include a ^ /goto triggername, the bot will be waiting for the user to say something.
• ^ /goto triggername tells the chatbot which trigger to look for next.
• Be careful linking too many triggers together. Remember that the user has to say something to you.

---

Below is a sample of a script and it shows how to use the different functions above. When kol1’s QR code is scanned, an audio will be played followed by a 13 seconds delay before and article appears.

When kol2’s QR code is scanned, an image will appear followed by the text “Check out my favorite place!” (The chat icon of the image will be kol2), then a card and an article will be sent.

> topic qrcodes

  + (runqr|qrcode) [*] kol1
  - /voice chengcheng-welcome
  ^ /goto timeout

  + timeout
  - /timeout 13 
  ^ /goto article

  + (runqr|qrcode) [*] kol2
  - /image image-filename
  ^ /goto gretting kol2

  + greeting kol2
  - Check out my favorite place!
  ^ /who tangbohu
  ^ /goto card

  + card
  - /card this-is-card-name 
  ^ /goto article
  
  + article
  - /news story01

< topic 

Up next: Tracking on Amplitude