Scripting

PiscoBot Scripting 101

Writing new scripts for PiscoBot is relatively easy. Only three things are required in your new PiscoBot script:

1. They have valid metadata
2. They use good code standards
3. They're cool

BotKit

When making a script, you'll probably want to use some native functionality of HowdyAI's BotKit. The best part is that all of your functions have access to BotKit's functionality by default. All you need to do is call bot. in your function and you'll have access to their library.

---

A script for PiscoBot uses the following template:

Template

'use strict';

function makeSandwich(bot, controller, message) {
  // Make sandwich here
}
module.exports = {
  name: 'sandwich',
  author: 'Your Name (yourgithubusername)',
  patterns: ['make me a sandwich'],
  types: ['direct_message', 'direct_mention', 'mention', 'ambient'],
  description: 'Bot makes you a sandwich',
  command: makeSandwich,
};

You don't have to worry about asynchronization, PiscoBot will automatically make your function asynchronous, using the async library. Cool, right?

Here's a rundown on how a that template works.

Explanation

Strict code

'use strict';

In our scripts we use strict code. This is a requirement, since it helps us write more secure JavaScript and make less errors.

Functions

function yourFunction(bot, controller, message) {
  // Your code here, EG:
  // bot.reply(message, 'Your reply here!");
}

Each function MUST HAVE bot, controller and message passed to them. These are the only inputs that your function will recieve. The rest of the input from users must be determined through some sort of matcher, either manually or using BotKit's internal message matchers. You can see an example of matching a string using RegExp here and matching a string using BotKit's match functionality

Metadata

Each script should have valid metadata or our Travis builds won't work correctly. This format MUST BE MET or your code WILL NOT BE ACCEPTED.

Name

name: 'sandwich',

This is the name of your script.

Author

author: 'Your Name (yourgithubusername)',

This is you! Make sure to credit yourself. 😁

Patterns

patterns: ['make me a sandwich'],

This is an array of RegExp patterns that will let the bot find your command. If you use escaped characters, make sure to double escape them (eg: \\s) until we fix this issue.

Types

types: ['direct_message', 'direct_mention', 'mention', 'ambient'],

These are the default BotKit types. Read more on them here.

Type	Description
direct_message	Bot is sent a PM
direct_mention	Bot is mentioned directly: @bot make me a sandwich
mention	Bot is mentioned in a message: hey @bot make me a sandwich
ambient	Message that doesn't mention bot in any way: make me a sandwich