Skip to content

Latest commit

 

History

History
422 lines (353 loc) · 15.4 KB

README.md

File metadata and controls

422 lines (353 loc) · 15.4 KB
Raw

Viber Bot API

Use this library to communicate with the Viber API to develop a bot for Viber. Please visit Getting Started guide for more information about Viber API.

License

This library is released under the terms of the Apache 2.0 license. See License for more information.

Library Prerequisites

Let's get started!

Installing

Creating a basic Viber bot is simple:

  1. Import viber-bot library to your project
  2. Create a Public Account and use the API key from https://developers.viber.com/
  3. Configure your bot as described in the documentation below
  4. Add the bot as middleware to your server with bot.middleware()
  5. Start your web server
  6. Call setWebhook(url) with your webserver url

A simple Echo Bot

Firstly, let's import and configure our bot:

'use strict';

const ViberBot  = require('viber-bot').Bot;
const BotEvents = require('viber-bot').Events;

const winston   = require('winston');
const toYAML    = require('winston-console-formatter');

function createLogger() {
	const logger = new winston.Logger({ level: "debug" }); // We recommend DEBUG for development
	logger.add(winston.transports.Console, toYAML.config()); 
	return logger;
}

const logger = createLogger();
const bot    = new ViberBot(logger, {
	authToken: YOUR_AUTH_TOKEN_HERE,
	name: "EchoBot",
	avatar: "http://viber.com/avatar.jpg" // It is recommended to be 720x720, and no more than 100kb.
});

// Perfect! Now here's the key part:
bot.on(BotEvents.MESSAGE_RECEIVED, (message, response) => {
	// Echo's back the message to the client. Your bot logic should sit here.
	response.send(message);
});

// Wasn't that easy? Let's create HTTPS server and set the webhook:
const https = require('https');
const port  = process.env.PORT || 8080;

// Viber will push messages sent to this URL. Webserver should be internet-facing.
const webhookUrl = process.env.WEBHOOK_URL; 

const httpsOptions = { key: ... , cert: ... , ca: ... }; // Trusted SSL certification (not self-signed).
https.createServer(httpsOptions, bot.middleware()).listen(port, () => bot.setWebhook(webhookUrl));

Do you supply a basic router for text messages?

Well, funny you ask. Yes we do. be careful, messages sent to your router callback will also be emitted to BotEvents.MESSAGE_RECEIVED event.

const TextMessage = require('viber-bot').Message.Text;

// A simple regular expression to answer messages in the form of 'hi' and 'hello'.
bot.onTextMessage(/^hi|hello$/i, (message, response) => 
    response.send(new TextMessage(`Hi there ${response.userProfile.name}. I am ${bot.name}`)));

Have you noticed how we created the TextMessage? There's a all bunch of message types you should get familiar with, here's a list of them. Every one of them is already modeled:

Creating them is easy! Every message object has it's own unique constructor corresponding to it's API implementation, click on them to see it! Check out the full API documentation for more advanced uses.

API

Viber Bot

require('viber-bot').Bot

An event emitter, emitting events described here.

new ViberBot()

Param Type Description
logger object Winston logger
options.authToken string Viber Auth Token
options.name string Your BOT Name
options.avatar string Avatar URL. No more than 100kb.

bot.on(handler)

require('viber-bot').Events

Param Type
handler EventHandlerCallback
message Message Object
response Response Object
err Error Object

Subscribe to events:

  • MESSAGE_RECEIVED (Callback: function (message, response) {})
  • MESSAGE_SENT (Callback: function (message, userProfile) {})
  • SUBSCRIBED (Callback: function (response) {})
  • UNSUBSCRIBED (Callback: function (response) {})
  • CONVERSATION_STARTED (Callback: function (response) {})
  • ERROR (Callback: function (err) {})

Example

bot.on(BotEvents.MESSAGE_RECEIVED, (message, response) => ... );
bot.on(BotEvents.MESSAGE_SENT, (message, userProfile) => ... );
bot.on(BotEvents.CONVERSATION_STARTED, (message, response) => ... );
bot.on(BotEvents.ERROR, err => ... );
bot.on(BotEvents.UNSUBSCRIBED, response => ... );
bot.on(BotEvents.SUBSCRIBED, response =>
    response.send(`Thanks for subscribing, ${response.userProfile.name}`));

bot.getBotProfile()

Returns a promise.JSON (With the following JSON). Example

bot.getBotProfile().then(response => console.log(`Public Account Named: ${response.name}`));

bot.getUserDetails(userProfile)

Param Type Description
userProfile UserProfile UserProfile object

Returns a promise.JSON. Example

bot.onSubscribe(response => bot.getUserDetails(response.userProfile)
        .then(userDetails => console.log(userDetails)));

bot.setWebhook(url)

Param Type Description
url string Trusted SSL Certificate

Returns a promise.JSON. Example

bot.setWebhook("https://my.bot/incoming").then(() => yourBot.doSomething()).catch(err => console.log(err));

bot.sendMessage(userProfile, messages, [optionalTrackingData])

Param Type Description
userProfile UserProfile UserProfile object
Messages object or array Can be Message object or array of Message objects
[optionalTrackingData] JSON Optional. JSON Object. Returned on every message sent by the client

Note: When passing array of messages to sendMessage, messages will be sent by explicit order (the order which they were given to the sendMessage method). The library will also cancel all custom keyboards except the last one, sending only the last message keyboard.

Returns a promise.ARRAY array of message tokens. Example

// single message
const TextMessage = require('viber-bot').Message.Text;
bot.sendMessage(userProfile, new TextMessage("Thanks for shopping with us"));

// multiple messages
const UrlMessage  = require('viber-bot').Message.Url;
bot.sendMessage(userProfile, [
    new TextMessage("Here's the product you've requested:"),
    new UrlMessage("http://my.ecommerce.site/product1"),
    new TextMessage("Shipping time: 1-3 business days")
]);

bot.middleware()

Returns a middleware to use with http/https. Example

const https = require('https');
https.createServer({ key: ... , cert: ... , ca: ... }, bot.middleware()).listen(8080);

bot.onTextMessage(regex, handler)

Param Type
regex regular expression
handler TextMessageHandlerCallback

TextMessageHandlerCallback: function (message, response) {}

Example

bot.onTextMessage(/^hi|hello$/i, (message, response) => 
    response.send(new TextMessage(`Hi there ${response.userProfile.name}. I am ${bot.name}`)));

bot.onError(handler)

Param Type
handler ErrorHandlerCallback

ErrorHandlerCallback: function (err) {}

Example

bot.onError(err => logger.error(err));

bot.onConversationStarted(userProfile, onFinish)

Param Type
userProfile UserProfile
onFinish ConversationStartedOnFinishCallback

Note: onConversationStarted event happens once when A Viber client opens the conversation with your bot for the first time. Callback accepts null and MessageObject only. Otherwise, an exception is thrown.

ConversationStartedOnFinishCallback: function (responseMessage, optionalTrackingData) {}

Example

bot.onConversationStarted((userProfile, onFinish) => 
	onFinish(new TextMessage(`Hi, ${userProfile.name}! Nice to meet you.`)));
	
bot.onConversationStarted((userProfile, onFinish) => 
    onFinish(new TextMessage(`Thanks`), { saidThanks: true }));

bot.onSubscribe(handler)

Param Type
handler SubscribeResponseHandlerCallback

SubscribeResponseHandlerCallback: function (response) {}

Example

bot.onSubscribe(response => console.log(`Subscribed: ${response.userProfile.name}`));

bot.onUnsubscribe(handler)

Param Type
handler UnsubscribeResponseHandlerCallback

UnsubscribeResponseHandlerCallback: function (userId) {}

Example

bot.onUnsubscribe(userId => console.log(`Unsubscribed: ${userId}`));

Response object

Members:

Param Type Notes
userProfile UserProfile ---

UserProfile object

Members:

Param Type Notes
id string ---
name string ---
avatar string Avatar URL
country string currently set in CONVERSATION_STARTED event only
language string currently set in CONVERSATION_STARTED event only

Message Object

const TextMessage     = require('viber-bot').Message.Text;
const UrlMessage      = require('viber-bot').Message.Url;
const ContactMessage  = require('viber-bot').Message.Contact;
const PictureMessage  = require('viber-bot').Message.Picture;
const VideoMessage    = require('viber-bot').Message.Video;
const LocationMessage = require('viber-bot').Message.Location;
const StickerMessage  = require('viber-bot').Message.Sticker;

Common Members for Message interface:

Param Type Description
timestamp long Epoch time
token long Sequential message token
trackingData JSON JSON Tracking Data from Viber Client

Common Constructor Arguments Message interface:

Param Type Description
optionalKeyboard JSON Writing Custom Keyboards
optionalTrackingData JSON Data to be saved on Viber Client device, and sent back each time message is recived

TextMessage object

Member Type
text string 
const message = new TextMessage(text, [optionalKeyboard], [optionalTrackingData]);
console.log(message.text);

UrlMessage object

Member Type
url string 
const message = new UrlMessage(url, [optionalKeyboard], [optionalTrackingData]);
console.log(message.url);

ContactMessage object

Member Type
contactName string
contactPhoneNumber string 
const message = new ContactMessage(contactName, contactPhoneNumber, [optionalKeyboard], [optionalTrackingData]);
console.log(`${message.contactName}, ${message.contactPhoneNumber}`);

PictureMessage object

Member Type
url string
text string
thumbnail string 
const message = new ContactMessage(url, [optionalText], [optionalThumbnail], [optionalKeyboard], [optionalTrackingData]);
console.log(`${message.url}, ${message.text}, ${message.thumbnail}`);

VideoMessage object

Member Type
url string
size int
thumbnail string
duration int 
const message = new VideoMessage(url, size, [optionalThumbnail], [optionalDuration], [optionalKeyboard], [optionalTrackingData]);
console.log(`${message.url}, ${message.size}, ${message.thumbnail}, ${message.duration}`);

LocationMessage object

Member Type
latitude float
longitude float 
const message = new LocationMessage(latitude, longitude, [optionalKeyboard], [optionalTrackingData]);
console.log(`${message.latitude}, ${message.longitude}`);

StickerMessage object

Member Type
stickerId int 
const message = new StickerMessage(stickerId, [optionalKeyboard], [optionalTrackingData]);
console.log(message.stickerId);

Useful links: