viberbot

The Viber bot python library provides just what you need to develop intelligent bots that interact naturally with your Viber users.

Showing:

Popularity

Downloads/wk

0

GitHub Stars

137

Maintenance

Last Commit

8mos ago

Contributors

11

Package

Dependencies

2

License

Categories

Readme

Viber Python Bot API

Use this library to develop a bot for Viber platform. The library is available on GitHub as well as a package on PyPI.

This package can be imported using pip by adding the following to your requirements.txt:

viberbot==1.0.11

License

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

Library Prerequisites

  1. python >= 2.7.0
  2. An Active Viber account on a platform which supports Public Accounts/ bots (iOS/Android). This account will automatically be set as the account administrator during the account creation process.
  3. Active Public Account/ bot - Create an account here.
  4. Account authentication token - unique account identifier used to validate your account in all API requests. Once your account is created your authentication token will appear in the account’s “edit info” screen (for admins only). Each request posted to Viber by the account will need to contain the token.
  5. Webhook - Please use a server endpoint URL that supports HTTPS. If you deploy on your own custom server, you'll need a trusted (ca.pem) certificate, not self-signed. Read our blog post on how to test your bot locally.

Contributing

If you think that there's a bug or there's anything else needed to be changed and you want to change it yourself, you can always create a new Pull request.
Please make sure that your change doesn't break anything and all the unit tests passes.
Also, please make sure that the current tests cover your change, if not please add tests.

We are using pytest, so if you want to run the tests from the commandline just follow the relevant steps after cloning the repo and creating your branch:

# installing the dependencies:  
python setup.py develop

# run the unit tests
python -m pytest

Let's get started!

Installing

Creating a basic Viber bot is simple:

  1. Install the library with pip pip install viberbot
  2. Import viberbot.api library to your project
  3. Create a Public Account or bot and use the API key from https://developers.viber.com
  4. Configure your bot as described in the documentation below
  5. Start your web server
  6. Call set_webhook(url) with your web server url

A simple Echo Bot

Firstly, let's import and configure our bot

from viberbot import Api
from viberbot.api.bot_configuration import BotConfiguration

bot_configuration = BotConfiguration(
    name='PythonSampleBot',
    avatar='http://viber.com/avatar.jpg',
    auth_token='YOUR_AUTH_TOKEN_HERE'
)
viber = Api(bot_configuration)

Create an HTTPS server

Next thing you should do is starting a https server. and yes, as we said in the prerequisites it has to be https server. Create a server however you like, for example with Flask:

from flask import Flask, request, Response

app = Flask(__name__)

@app.route('/incoming', methods=['POST'])
def incoming():
    logger.debug("received request. post data: {0}".format(request.get_data()))
    # handle the request here
    return Response(status=200)

context = ('server.crt', 'server.key')
app.run(host='0.0.0.0', port=443, debug=True, ssl_context=context)

Setting a webhook

After the server is up and running you can set a webhook. Viber will push messages sent to this URL. web server should be internet-facing.

viber.set_webhook('https://mybotwebserver.com:443/')

Logging

This library uses the standard python logger. If you want to see its logs you can configure the logger:

logger = logging.getLogger()
logger.setLevel(logging.DEBUG)
handler = logging.StreamHandler()
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)

Do you supply a basic types of messages?

Well, funny you ask. Yes we do. All the Message types are located in viberbot.api.messages package. Here's some examples:

from viberbot.api.messages import (
    TextMessage,
    ContactMessage,
    PictureMessage,
    VideoMessage
)
from viberbot.api.messages.data_types.contact import Contact

# creation of text message
text_message = TextMessage(text="sample text message!")

# creation of contact message
contact = Contact(name="Viber user", phone_number="0123456789")
contact_message = ContactMessage(contact=contact)

# creation of picture message
picture_message = PictureMessage(text="Check this", media="http://site.com/img.jpg")

# creation of video message
video_message = VideoMessage(media="http://mediaserver.com/video.mp4", size=4324)

Have you noticed how we created the TextMessage? There's a all bunch of message types you should get familiar with.

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.

Let's add it all up and reply with a message!

from flask import Flask, request, Response
from viberbot import Api
from viberbot.api.bot_configuration import BotConfiguration
from viberbot.api.messages import VideoMessage
from viberbot.api.messages.text_message import TextMessage
import logging

from viberbot.api.viber_requests import ViberConversationStartedRequest
from viberbot.api.viber_requests import ViberFailedRequest
from viberbot.api.viber_requests import ViberMessageRequest
from viberbot.api.viber_requests import ViberSubscribedRequest
from viberbot.api.viber_requests import ViberUnsubscribedRequest

app = Flask(__name__)
viber = Api(BotConfiguration(
    name='PythonSampleBot',
    avatar='http://site.com/avatar.jpg',
    auth_token='445da6az1s345z78-dazcczb2542zv51a-e0vc5fva17480im9'
))


@app.route('/', methods=['POST'])
def incoming():
    logger.debug("received request. post data: {0}".format(request.get_data()))
    # every viber message is signed, you can verify the signature using this method
    if not viber.verify_signature(request.get_data(), request.headers.get('X-Viber-Content-Signature')):
        return Response(status=403)

    # this library supplies a simple way to receive a request object
    viber_request = viber.parse_request(request.get_data())

    if isinstance(viber_request, ViberMessageRequest):
        message = viber_request.message
        # lets echo back
        viber.send_messages(viber_request.sender.id, [
            message
        ])
    elif isinstance(viber_request, ViberSubscribedRequest):
        viber.send_messages(viber_request.get_user.id, [
            TextMessage(text="thanks for subscribing!")
        ])
    elif isinstance(viber_request, ViberFailedRequest):
        logger.warn("client failed receiving message. failure: {0}".format(viber_request))

    return Response(status=200)

if __name__ == "__main__":
    context = ('server.crt', 'server.key')
    app.run(host='0.0.0.0', port=443, debug=True, ssl_context=context)

As you can see there's a bunch of Request types here's a list of them.

Viber API

Api class

from viberbot import Api

New Api()

ParamTypeDescription
bot_configurationobjectBotConfiguration

Api.set_webhook(url)

ParamTypeDescription
urlstringYour web server url
webhook_eventslistoptional list of subscribed events

Returns List of registered event_types.

event_types = viber.set_webhook('https://example.com/incoming')

Api.unset_webhook()

Returns None.

viber.unset_webhook()

Api.get_account_info()

Returns an object with the following JSON.

account_info = viber.get_account_info()

Api.verify_signature(request_data, signature)

ParamTypeDescription
request_datastringthe post data from request
signaturestringsent as header X-Viber-Content-Signature

Returns a boolean suggesting if the signature is valid.

if not viber.verify_signature(request.get_data(), request.headers.get('X-Viber-Content-Signature')):
    return Response(status=403)

Api.parse_request(request_data)

ParamTypeDescription
request_datastringthe post data from request

Returns a ViberRequest object.

There's a list of ViberRequest objects

viber_request = viber.parse_request(request.get_data())

Api.send_messages(to, messages)

ParamTypeDescription
tostringViber user id
messageslistlist of Message objects

Returns list of message tokens of the messages sent.

tokens = viber.send_messages(to=viber_request.get_sender().get_id(),
                 messages=[TextMessage(text="sample message")])

Api.post_messages_to_public_account(to, messages)

ParamTypeDescription
senderstringViber user id
messageslistlist of Message objects

Returns list of message tokens of the messages sent.

tokens = viber.post_messages_to_public_account(sender=viber_request.get_sender().get_id(),
                 messages=[TextMessage(text="sample message")])

Api.get_online(viber_user_ids)

ParamTypeDescription
viber_user_idsarray of stringsArray of Viber user ids

Returns a dictionary of users.

users = Api.get_online(["user1id", "user2id"])

Api.get_user_details(viber_user_id)

ParamTypeDescription
viber_user_idsstringViber user id

The get_user_details 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.

user_data = Api.get_user_details("userId")

Request object

ParamTypeNotes
event_typestringaccording to EventTypes enum
timestamplongEpoch of request time
  • ViberRequest
    • .event_type ⇒ string
    • .timestamp ⇒ long

ViberConversationStartedRequest object

Inherits from ViberRequest

Conversation started event fires when a user opens a conversation with the Public Account/ 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.

ParamTypeNotes
event_typestringalways equals to the value of EventType.CONVERSATION_STARTED
message_tokenstringUnique ID of the message
typestringThe specific type of conversation_started event.
contextstringAny additional parameters added to the deep link used to access the conversation passed as a string
userUserProfilethe user started the conversation UserProfile
subscribedbooleanIndicates whether a user is already subscribed
  • ViberConversationStartedRequest
    • message_token ⇒ string
    • type ⇒ string
    • context ⇒ string
    • user ⇒ UserProfile

ViberDeliveredRequest object

Inherits from ViberRequest

ParamTypeNotes
event_typestringalways equals to the value of EventType.DELIVERED
message_tokenstringUnique ID of the message
user_idstringUnique Viber user id
  • ViberDeliveredRequest
    • message_token ⇒ string
    • user_id ⇒ string

ViberFailedRequest object

Inherits from ViberRequest

ParamTypeNotes
event_typestringalways equals to the value of EventType.FAILED
message_tokenstringUnique ID of the message
user_idstringUnique Viber user id
descstringFailure description
  • ViberFailedRequest
    • message_token ⇒ string
    • user_id ⇒ string
    • desc ⇒ string

ViberMessageRequest object

Inherits from ViberRequest

ParamTypeNotes
event_typestringalways equals to the value of EventType.MESSAGE
message_tokenstringUnique ID of the message
messageMessageMessage object
senderUserProfilethe user started the conversation UserProfile
  • ViberMessageRequest
    • message_token ⇒ string
    • message ⇒ Message
    • sender ⇒ UserProfile

ViberSeenRequest object

Inherits from ViberRequest

ParamTypeNotes
event_typestringalways equals to the value of EventType.SEEN
message_tokenstringUnique ID of the message
user_idstringUnique Viber user id
  • ViberSeenRequest
    • message_token ⇒ string
    • user_id ⇒ string

ViberSubscribedRequest object

Inherits from ViberRequest

ParamTypeNotes
event_typestringalways equals to the value of EventType.SUBSCRIBED
userUserProfilethe user started the conversation UserProfile
  • ViberSubscribedRequest
    • user ⇒ UserProfile

ViberUnsubscribedRequest object

Inherits from ViberRequest

ParamTypeNotes
event_typestringalways equals to the value of EventType.UNSUBSCRIBED
user_idstringUnique Viber user id
  • ViberUnsubscribedRequest
    • get_user_id() ⇒ string

UserProfile object

ParamTypeNotes
idstring---
namestring---
avatarstringAvatar URL
countrystringcurrently set in CONVERSATION_STARTED event only
languagestringcurrently set in CONVERSATION_STARTED event only

Message Object

Common Members for Message interface:

ParamTypeDescription
timestamplongEpoch time
keyboardJSONkeyboard JSON
trackingDataJSONJSON Tracking Data from Viber Client

Common Constructor Arguments Message interface:

ParamTypeDescription
optionalKeyboardJSONWriting Custom Keyboards
optionalTrackingDataJSONData to be saved on Viber Client device, and sent back each time message is received

TextMessage object

MemberType
textstring
message = TextMessage(text="my text message")

URLMessage object

MemberTypeDescription
mediastringURL string
message = URLMessage(media="http://my.siteurl.com")

ContactMessage object

MemberType
contactContact
from viberbot.api.messages.data_types.contact import Contact

contact = Contact(name="Viber user", phone_number="+0015648979", avatar="http://link.to.avatar")
contact_message = ContactMessage(contact=contact)

PictureMessage object

MemberTypeDescription
mediastringurl of the message (jpeg only)
textstring
thumbnailstring
message = PictureMessage(media="http://www.thehindubusinessline.com/multimedia/dynamic/01458/viber_logo_JPG_1458024f.jpg", text="Viber logo")

VideoMessage object

MemberTypeDescription
mediastringurl of the video
sizeint
thumbnailstring
durationint
message = VideoMessage(media="http://site.com/video.mp4", size=21499)

LocationMessage object

MemberType
locationLocation
from viberbot.api.messages.data_types.location import Location

location = Location(lat=0.0, lon=0.0)
location_message = LocationMessage(location=location)

StickerMessage object

MemberType
sticker_idint
message = StickerMessage(sticker_id=40100)

FileMessage object

MemberType
mediastring
sizelong
file_namestring
message = FileMessage(media=url, size=sizeInBytes, file_name=file_name)

RichMediaMessage object

MemberType
rich_mediastring (JSON)
SAMPLE_RICH_MEDIA = """{
  "BgColor": "#69C48A",
  "Buttons": [
    {
      "Columns": 6,
      "Rows": 1,
      "BgColor": "#454545",
      "BgMediaType": "gif",
      "BgMedia": "http://www.url.by/test.gif",
      "BgLoop": true,
      "ActionType": "open-url",
      "Silent": true,
      "ActionBody": "www.tut.by",
      "Image": "www.tut.by/img.jpg",
      "TextVAlign": "middle",
      "TextHAlign": "left",
      "Text": "<b>example</b> button",
      "TextOpacity": 10,
      "TextSize": "regular"
    }
  ]
}"""

SAMPLE_ALT_TEXT = "upgrade now!"

message = RichMediaMessage(rich_media=SAMPLE_RICH_MEDIA, alt_text=SAMPLE_ALT_TEXT)

KeyboardMessage object

MemberType
keyboardJSON
tracking_dataJSON
message = KeyboardMessage(tracking_data=tracking_data, keyboard=keyboard)

Sending a welcome message

The Viber API allows sending messages to users only after they subscribe to the account. However, Viber will allow the account to send one “welcome message” to a user as the user opens the conversation, before the user subscribes.

The welcome message will be sent as a response to a conversation_started callback, which will be received from Viber once the user opens the conversation with the account. To learn more about this event and when is it triggered see Conversation started in the callbacks section.

Welcome message flow

Sending a welcome message will be done according to the following flow:

  1. User opens 1-on-1 conversation with account.
  2. Viber server send conversation_started even to PA’s webhook.
  3. The account receives the conversation_started and responds with an HTTP response which includes the welcome message as the response body.

The welcome message will be a JSON constructed according to the send_message requests structure, but without the receiver parameter. An example welcome message would look like this:

@app.route('/', methods=['POST'])
def incoming():
    viber_request = viber.parse_request(request.get_data())

    if isinstance(viber_request, ViberConversationStartedRequest) :
        viber.send_messages(viber_request.get_user().get_id(), [
            TextMessage(text="Welcome!")
        ])

    return Response(status=200)

Community

Join the conversation on Gitter.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100