iconicbot / iconic-narada

Open Source Webhook Boilerplate for Social Media/Messaging Platforms(Facebook, Facebook Messenger, Twitter, Twitter Direct, Youtube)

Iconic Narada | Social Media/Messaging Webhooks Boilerplate

Iconic Narada, developer friendly boilerplate to help you connect Social Media/Messaging platforms via Webhooks.

Supported Platforms:

• Facebook
• Facebook Messenger
• Twitter
• Twitter Direct
• Youtube

Why Iconic-Narada?:

• Developer friendly
• Raw social media request/response objects
• Code from the future (ECMAScript 6 compatible)
• Database of your choice
• Server of your choice (Not specific to AWS lambda)
• Not only for messaging platforms, supports social media too
• Multiple platforms/channels in 1 boilerplate
• Better error handling
• Very low learning curve

Installation

Choose one of the following options:

• Install with npm: npm install iconic-narada
• To install Iconic Narada from source, first clone the repository and then run: npm install.

Edit config

In app root directory, rename .sample-env to .env. You can set app wide environment constants here and access them in your code with dotenv module and process.env.

In each example bot directory, you will find config.json. You can set bot specific constants here and access them by importing this file into your bot code. You may also instead retrieve this information from database for additional security.

Enable/Disable a Platform

Each platform has it's own router, controller, parser, elements and connector. The main router in routes.js hands over new received event to the router of specific platform.

To enable a new platform, import the platform from platforms folder and create a new route for that platform in the main router(routes.js). E.g.: The below code will create a route like - https://your.domain/webhook/facebook

import facebookRouter from './platforms/facebook/router';

app.use('/facebook', facebookRouter);

Run

To start the app without babel, run node app.js.

To start the app with babel, run node start.js

Basic Usage

The business logic of bot is handled in bots. Each platform can have it's own configuration which may also be retrieved from database or environment file.

Once a platform is enabled by adding it to routes, the platform specific Controller in platforms/<platform>/controller.js parses every new event and hands over the parsed event to bots/<platform>/index.js. You can either process the parsed event here or create multiple bots for that platform and redirect the parsed event to respective bot.

Bots can use Elements from platforms/<platform>/elements.js to create JSON objects to form a reply or action and, use Connector from platforms/<platform>/connector.js to send the reply or action to platform APIs.

Here are some examples of typical usage:

Facebook Elements and Connector

Importing elements and connector

import FacebookConnector from '../../../platforms/facebook/connector';
import * as FacebookElements from '../../../platforms/facebook/elements';

Creating a message

Create a plain text message.

const message = new FacebookElements.Text(`Hello there!`);

For more detailed samples of Facebook Elements, check out this doc.

Sending a message

Set the Recipient ID.

Event object contains basic information like senderId, recipientId, etc based on the type of event received.

const recipientId = event.senderId;

Set a message.

const message = new FacebookElements.Text(`Hello there!`);

Set the array of replies to be sent.

Reply element method requires a recipient ID and a message. It also accepts a string in place of message object.

const replies = [
    new FacebookElements.Reply(recipientId, message),
    new FacebookElements.Reply(recipientId, 'What\'s up?'),
];

Send each reply in sequence.

const facebookConnector = new FacebookConnectorACCESS_TOKEN);

for (const reply of replies) {
    await facebookConnector.sendMessage(botConfig.PAGE_ID, reply)
        .catch(err => logger.error(err));
}

Sending an action.

You can also send an action with/without/before/after a Reply element.

const replies = [
    new FacebookElements.MarkSeen(recipientId),
    new FacebookElements.TypingOn(recipientId),
    new FacebookElements.TypingOff(recipientId),
];

Getting user profile.

You can get user profile with getUserProfile method.

const facebookConnector = new FacebookConnector(ACCESS_TOKEN);

const userProfile = await facebookConnector.getUserProfile(recipientId)
    .catch(err => logger.debug(err));

Twitter Elements and Connector

Importing elements and connector

import TwitterConnector from '../../../platforms/twitter/connector';
import * as TwitterElements from '../../../platforms/twitter/elements';

Creating a message

Create a plain text message.

const message = new TwitterElements.Text(`Hi there!`);

For more detailed samples of Twitter Elements, check out this doc.

Sending a message.

Set the Recipient ID.

Event object contains basic information like senderId, recipientId, etc based on the type of event received.

const recipientId = event.senderId;

Set a message.

const message = new TwitterElements.Text(`Hello there!`);

Create an array of replies to be sent.

Reply element method requires a recipient ID and a message. It also accepts a string in place of message object.

const replies = [
    new TwitterElements.Reply(recipientId, message),
    new TwitterElements.Reply(recipientId, 'What\'s up?'),
];

Send each reply in sequence.

const twitterConnector = new TwitterConnectorOAUTH);

for (const reply of replies) {
    await twitterConnector.sendMessage(reply)
      .catch(err => logger.error(err));
}

Youtube Connector

Importing connector

import YoutubeConnector from '../../../platforms/youtube/connector';

Generating Access token

Follow the instruction here.

Fetch list of comments

You can fetch the list of comments for a specific video using the commentsList method.

const youtubeConnector = new YoutubeConnector(ACCESS_TOKEN);

youtubeConnector.commentsList(videoId).then((data) => {
  //Process the data
});

Add a new comment

You can add a new comment for a video using the commentInsert method.

youtubeConnector.commentInsert(videoId, comment).catch(err => logger.error(err));

Add a reply to a comment

You can add a reply to an existing comment using the commentReply method.

youtubeConnector.commentReply(commentId, comment).catch(err => logger.error(err));

Delete a comment

You can remove a comment using the commentDelete method.

 youtubeConnector.commentDelete(commentId).catch(err => logger.error(err));

Contributing

Contributions are generally appreciated. But we are exclusively looking for contributers to help us extend our support to Slack, Telegram, Instagram, WhatsApp, Skype, Youtube, Viber, Amazon Alexa, Line, Kik & make it a all-in-one open source webhooks boilerplate.

See the Contributors' guide for more information.

Authors

• Iconic.wtf

License

The source code of Iconic Narada boilerplate is licensed under MIT.