calamars

see all badges…

An alpha quality, under heavy development, proto-frramework for building chat applications.

Install

npm install --save calamars

Documentation

See the Library Reference for full documentation.

Overview

Calamars is a toolset of different libs that helps on common tasks of a conversational application development, such as:

• bot daemon setup
• question/answer routing
• interaction with cloud-based natural language message parsers (LUIS, wit.ai).

Below are some usage examples of the different pieces of the calamars framework. For more use cases check the documentation or the test folder.

Facebook Messenger Bot Wrapper

basic echo bot

const FacebookMessengerBot = require('calamars').FacebookMessengerBot;
 
const myPageToken = 'EAASxZBKlWU...SwZDZD';
const myVerifyToken = 'RMHFOBtOd...X91LBu';
const myCallbackPath = '/webhook';
const myPort = 9091;
 
const myMessageListener = function(updateEvent){
    console.log('received message:', updateEvent.update.message.text);
    // reply with the same received message
    updateEvent.bot.sendMessage({
        userId: updateEvent.update.sender.id,
        text: updateEvent.update.message.text
    })
};
 
const mybot = new FacebookMessengerBot({
    port: myPort,
    callbackPath: myCallbackPath,
    verifyToken: myVerifyToken,
    pageTokens: [myPageToken],
    listeners: {
        onMessage: myMessageListener
    }
});
 
mybot.start().then(function(){
    console.log(`server is running on port ${myPort}`);
})

Check the Tutorial for a detailed guide of how to set up a Facebook App, a Facebook Page and how to install and run the example above.

For details on the available methods and implementation please refer to the FacebookMessengerBot class.

Chat replies Routing

string → string

import { createRouter } from 'calamars';
const routes = [
    ['yes', 'no'],
    ['stop', 'go go go'],
    ['goodbye', 'hello'],
    ['high', 'low'],
    ['why', 'I don’t know']
];
const router = createRouter(routes);
 
console.log(router('goodbye')); // hello

string → callback → string

import { createRouter } from 'calamars';
const callbacks = {
    yes() { return 'no'; },
    halt() { return 'go go go'; },
    goodbye() { return 'hello'; },
    high() { return 'low'; },
    why() { return 'I don’t know'; }
};
const routes = [
    ['yes', callbacks.yes],
    ['stop', callbacks.halt],
    ['goodbye', callbacks.goodbye],
    ['high', callbacks.high],
    ['why', callbacks.why]
];
const router = createRouter(routes);
 
console.log(router('goodbye')); // hello

echo any string input

import { createRouter } from 'calamars';
 
const routes = [
    [/.*/, matches => matches[0]]
];
const router = createRouter(routes);
 
console.log(router('goodbye')); // goodbye

string → LUIS → intentName → callback → string

import { LuisDriver, createRouter } from 'calamars';
 
const luis = new LuisDriver(options);
const callback = () => 'go go go';
const routes = [
    ['goodbye', callback]
];
const router = createRouter(routes);
 
luis.query('Good Bye!')
    .then(({ topScoringIntent }) => {
        const intentName = topScoringIntent.intent;
 
        console.log(router(intentName)); // 'go go go'
    });

More usage examples

• string → regex → string - Using createRegexRouter
• string → regex → callback → string - With matches and default answer using createRegexFunctionRouter
• object → comparisonFunction → callback → string - Using createPayloadFunctionRouter
• more

Patches are welcome

If you want to help us improve this library with a fix, a feature, better documentation or any other thing, please refer to the contributing guide.

Showcase

Who is using calamars in the real world:

• Calamarcopollo: an open-source Telegram/Facebook Messenger bot that searches for brazilian intercity bus schedules and tickets using natural language (powered by wit.ai and clickbus api).

If you are using it or know of someone else using it please let us know, open a pull request expanding this list, or file an issue :)

License

• AGPL-3.0