Use this library to develop a bot for the Viber platform. The library is available on GitHub as well as a package on npm.
Important notes for bot developers: Please note that since 5.02.24, Viber bots can only be created on commercial terms. Before you start developing your bot in Viber please check how to apply for a bot creation here.
This library is released under the terms of the Apache 2.0 license. See License for more information.
This library is released on npm.
Install with npm install viber-bot --save
If you are already using express or equivalent, you can do the following:
Please revisit app.use() documentation. For more information see ViberBot.middleware().
Creating a basic Viber bot is simple:
viber-bot
library to your projectbot.middleware()
setWebhook(url)
with your web server urlFirstly, let’s import and configure our bot:
We provide an option to use Winston logger with our library. The only requirement is that you use Winston >= 2.0.0.
Well funny you ask. Yes we do. But a word of warning - messages sent to your router callback will also be emitted to the BotEvents.MESSAGE_RECEIVED
event.
Have you noticed how we created the TextMessage
instance? There’s a all bunch of message types you should get familiar with.
Creating them is easy! Every message object has its own unique constructor corresponding to its API implementation. Click on each type in the list to find out more. Check out the full API documentation for more advanced uses.
require('viber-bot').Bot
An event emitter, emitting events described here.
promise.JSON
promise.JSON
promise.JSON
promise.JSON
promise.ARRAY
handler
= TextMessageHandlerCallback
handler
= ErrorHandlerCallback
onFinish
= ConversationStartedOnFinishCallback
handler
= SubscribeResponseHandlerCallback
handler
= UnsubscribeResponseHandlerCallback
Param | Type | Description |
---|---|---|
options.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. |
options.registerToEvents | array |
example: [“message”, “delivered”] |
require('viber-bot').Events
Param | Type |
---|---|
handler | EventHandlerCallback |
message | Message Object |
response | Response Object |
err | Error Object |
Subscribe to events:
function (message, response) {}
)function (message, userProfile) {}
)function (response) {}
)function (response) {}
)function (userProfile, isSubscribed, context, onFinish) {}
)function (err) {}
)Example
Returns a promise.JSON
with the following JSON.
Param | Type | Description |
---|---|---|
userProfile | UserProfile |
UserProfile object |
The getUserDetails
function will fetch the details of a specific Viber user based on his unique user ID. The user ID can be obtained from the callbacks sent to the account regarding user’s actions. This request can be sent twice during a 12 hours period for each user ID.
Returns a promise.JSON
.
Param | Type | Description |
---|---|---|
viberUserIds | array of strings |
Collection of Viber user ids |
Returns a promise.JSON
.
Param | Type | Description |
---|---|---|
url | string |
Trusted SSL Certificate |
Returns a promise.JSON
.
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.
Returns a middleware implementation to use with http/https
.
Param | Type |
---|---|
regex | regular expression |
handler | TextMessageHandlerCallback |
function (message, response) {}
Param | Type |
---|---|
handler | ErrorHandlerCallback |
function (err) {}
Param | Type | Description |
---|---|---|
userProfile | UserProfile |
UserProfile object |
isSubscribed | boolean | Indicates whether a user is already subscribed |
context | String | Any additional parameters added to the deep link used to access the conversation passed as a string |
onFinish | ConversationStartedOnFinishCallback |
When called, a Message will be sent to the client |
Conversation started event fires when a user opens a conversation with the bot using the “message” button (found on the account’s info screen) or using a deep link.
This event is not considered a subscribe event and doesn’t allow the account to send messages to the user; however, it will allow sending one “welcome message” to the user. See sending a welcome message below for more information.
function (responseMessage, optionalTrackingData) {}
The ConversationStartedOnFinishCallback
accepts null
and MessageObject
only. Otherwise, an exception is thrown.
The ConversationStartedOnFinishCallback
isn’t compatible with certain keyboard features, and therefore sendMessage
is preferable when sending messages with keyboards.
Param | Type |
---|---|
handler | SubscribeResponseHandlerCallback |
function (response) {}
Param | Type |
---|---|
handler | UnsubscribeResponseHandlerCallback |
function (userId) {}
Members:
Param | Type | Notes |
---|---|---|
userProfile | UserProfile |
— |
promise.JSON
Members:
Param | Type | Notes |
---|---|---|
id | string |
— |
name | string |
— |
avatar | string |
Optional Avatar URL |
country | string |
currently set in CONVERSATION_STARTED event only |
language | string |
currently set in CONVERSATION_STARTED event only |
Common Members for Message
interface:
Param | Type | Description |
---|---|---|
timestamp | string |
Epoch time |
token | string |
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 received |
Member | Type |
---|---|
text | string |
Note: to enable features that have an api level requirement in your keyboard, it’s necessary to add the following arguments to the KeyboardMessage constructor:
TextMessage(text, [optionalKeyboard], [optionalTrackingData], null, null, [minApiVersion])
[minApiVersion]
should be an integer value of the desired minimum api version/level for the message.
Member | Type |
---|---|
url | string |
Member | Type |
---|---|
contactName | string |
contactPhoneNumber | string |
Member | Type |
---|---|
url | string |
text | string |
thumbnail | string |
Member | Type |
---|---|
url | string |
size | int |
thumbnail | string |
duration | int |
Member | Type |
---|---|
latitude | float |
longitude | float |
Member | Type |
---|---|
stickerId | int |
Member | Type |
---|---|
url | string |
sizeInBytes | int |
filename | string |
Member | Type |
---|---|
richMedia | Object |
Member | Type |
---|---|
keyboard | JSON |
Note: to enable features that have an api level requirement in your keyboard, it’s necessary to add the following arguments to the KeyboardMessage constructor:
KeyboardMessage(SAMPLE_KEYBOARD, [optionalTrackingData], null, null, [minApiVersion])
[minApiVersion]
should be an integer value of the desired minimum api version/level for the message.
We’ve created the Is It Up sample project to help you get started.
Join the conversation on Gitter.