Viber Bot

Viber Bot

This connector sends messages as a Viber bot through the Viber REST Bot API (https://chatapi.viber.com/pa). It covers sending to one subscriber or broadcasting to many, reading the bot account, a subscriber's details and online status, and setting or removing the bot's webhook. It does not receive messages: Viber delivers incoming messages and events only to the bot's webhook, a public HTTPS endpoint of your own.

Setup (5 minutes once you have a bot)

1. You need an existing Viber bot. Since 5 February 2024 Viber creates new bots only on commercial terms: apply through Rakuten Viber or one of its official partners (see https://developers.viber.com/docs/api/rest-bot-api/). Older free bots keep working.
2. Copy the bot's authentication token (app key): in the Viber app as the bot's admin, More > Settings > Bots > Edit Info > Your app key, or in the Viber Admin Panel.
3. Paste it into VIBER_AUTH_TOKEN and run viber_get_account_info to check it.
4. Viber only lets a bot write to users after a webhook is set. If your bot has none yet, set one with viber_set_webhook (the URL must answer Viber's check with HTTP 200 and have a certificate from a trusted CA).

Who can receive messages: only users subscribed to the bot. A user subscribes by sending the bot a message or tapping subscribe; they can unsubscribe at any time. There is no API to list subscribers: their user ids (sender.id of incoming messages, user.id of the subscribed event) arrive at the webhook, so the id you send to must come from there. Sending to anyone else fails with receiverNotSubscribed (6) or receiverNotRegistered (5). Messaging people by phone number is a different, paid product (Viber Business Messages) and is not part of this connector.

Workflow

• Check the bot: viber_get_account_info returns the name, URI, the webhook, its event types and subscribers_count.
• One user: viber_send_text (optionally with a keyboard of reply buttons), viber_send_picture, viber_send_video, viber_send_file, viber_send_url, viber_send_contact, viber_send_location, viber_send_sticker, and viber_send_rich_media for a carousel of cards with images and buttons. Every send tool takes receiver (the user id) and sender_name, the name shown above the message (at most 28 characters).
• Many users: viber_broadcast_message sends the same message to up to 300 subscribers per call; replace_me_with_user_name and replace_me_with_receiver_id in the text are replaced for each receiver. Check failed_list in the answer for receivers that did not get it.
• About a user: viber_get_user_details (name, country, language, device, Viber version; at most twice per user in 12 hours) and viber_get_online (up to 100 ids; online_status 0 online, 1 offline with last_online, 2 hidden, 3 try later, 4 not a Viber user or not subscribed).
• Webhook: viber_set_webhook points the bot at your endpoint and picks the optional events (delivered, seen, failed, conversation_started; message, subscribed and unsubscribed always arrive). viber_remove_webhook removes it, which also closes the bot's 1-on-1 chat for users.

Keyboards and rich media: keyboard is an object {"Type": "keyboard", "Buttons": [{"ActionType": "reply", "ActionBody": "yes", "Text": "Yes"}]}; the user's tap comes back to the webhook as a message. Rich media takes {"Type": "rich_media", "ButtonsGroupColumns": 6, "ButtonsGroupRows": 7, "Buttons": [...]} with Columns, Rows, ActionType (reply, open-url), ActionBody, Text and Image per button; send it with min_api_version 7 and an alt_text for old clients. Buttons are documented at https://developers.viber.com/docs/tools/keyboards/.

Reading the answers: every answer has status (0 = ok) and status_message; the connector turns any other status into an error. A sent message returns message_token. billing_status says how Viber bills the message: 0 to 4 are not charged (in a session the user opened, or free), 5 is a charged message outside a session. Times (last_online, callback timestamp) are Unix milliseconds.

Limits: the whole request must stay under 30 KB; text up to 7,000 characters; pictures JPEG, PNG or static GIF up to 1 MB on iOS (3 MB on Android) with the extension in the URL; videos MP4 up to 26 MB and 180 seconds; files up to 50 MB (executables are refused). Broadcasts allow 500 requests in 10 seconds. Commercial bots pay per message outside a session: freeMessagesExceeded (23) or noBalance (24) means the monthly free messages or the balance are used up.

Errors (status): 2 invalid token, 3 bad data, 4 missing data, 5 receiver not on Viber, 6 receiver not subscribed, 7 bot blocked, 8 not a bot token, 9 bot suspended, 10 no webhook set, 11 receiver's Viber too old, 12 too many requests, 13 or 14 min_api_version too high for the receiver, 21 country not supported.