Iconic Narada, developer friendly boilerplate to help you connect Social Media/Messaging platforms via Webhooks.
Supported Platforms:
- Facebook Messenger
- 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
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.
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.
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);
To start the app without babel, run node app.js.
To start the app with babel, run node start.js
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:
import FacebookConnector from '../../../platforms/facebook/connector';
import * as FacebookElements from '../../../platforms/facebook/elements';
Create a plain text message.
const message = new FacebookElements.Text(`Hello there!`);
For more detailed samples of Facebook Elements, check out this doc.
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));
}
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),
];
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));
import TwitterConnector from '../../../platforms/twitter/connector';
import * as TwitterElements from '../../../platforms/twitter/elements';
Create a plain text message.
const message = new TwitterElements.Text(`Hi there!`);
For more detailed samples of Twitter Elements, check out this doc.
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));
}
import YoutubeConnector from '../../../platforms/youtube/connector';
Follow the instruction here.
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
});
You can add a new comment for a video using the commentInsert method.
youtubeConnector.commentInsert(videoId, comment).catch(err => logger.error(err));
You can add a reply to an existing comment using the commentReply method.
youtubeConnector.commentReply(commentId, comment).catch(err => logger.error(err));
You can remove a comment using the commentDelete method.
youtubeConnector.commentDelete(commentId).catch(err => logger.error(err));
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.
The source code of Iconic Narada boilerplate is licensed under MIT.