Viber API: how it works, key limits and what to set up (2026)

What is the Viber API and how do you get started?

The Viber API is a set of HTTPS endpoints that let a business server send messages to Viber users, receive their messages and events at a webhook URL it controls, and run a bot. Viber's developer site says bots can only be created on commercial terms since 5 Feb 2024, so you apply to Viber or a verified partner first.

According to the Viber Developers Hub, you can build bots with the REST bot API or the open-source NodeJS and Python libraries. SleekFlow's Help Center says Viber must approve a new bot and that approval isn't guaranteed, so plan lead time.

Viber Business Messages, the separate product for alerts and offers, is set up through Viber or a messaging partner. Viber's template announcement, published 20 May 2026, says its transactional messages must use approved templates from 1 July 2026.

How does the authentication token work?

Your authentication token is the secret that identifies your bot to Viber. Viber generates it when the bot is created, administrators can view it in the bot's "edit info" screen or the Viber Admin Panel, and every request must send it in the X-Viber-Auth-Token header.

Viber's authentication page doesn't say whether a token expires or how to replace one. Keep the token in environment variables or a secret manager, never in Git or client-side code, and ask Viber support how to replace it the moment you suspect a leak.

Your server also holds whatever users send it. Data protection rules differ by country, so ask local counsel what applies before you store conversations.

How do you configure webhooks for real-time callbacks?

You register your webhook by calling set_webhook with your URL and token. Viber then sends a test callback to that URL, and the check succeeds when your server answers with HTTP 200. Viber only accepts a valid SSL certificate from a trusted certificate authority, so self-signed certificates won't work.

The webhook setup guide also describes the optional send_name flag. The name only arrives when the user allows content personalization, so don't build a greeting that breaks when it's blank.

To remove your webhook, call set_webhook with an empty URL. That also disables the 1-on-1 conversation feature for your bot, so check which environment your script points at before you run it.

Which events can you choose with event_types?

The event_types parameter sets which events Viber sends to your webhook. The message, subscribed and unsubscribed events are mandatory. The delivered, seen, failed and conversation_started events are optional, and leaving the parameter out sends you everything. An empty list sends only the mandatory ones.

Pro Tip: If you set event_types, include conversation_started, or your bot won't receive the event it needs to send a welcome message.

What events and delivery receipts will you receive?

Viber sends every event to your webhook, from subscribed and unsubscribed to message, delivered, seen and failed. Delivered events fire for each device while seen fires once, so receipts need careful handling before they reach your reports or your delivery rate.

Viber's delivered event fires for each device, so one message to a user with a phone and a tablet can produce two callbacks. The seen event fires once, when the user reads their unread messages. Viber stops trying to deliver after 14 days, with no delivered event.

How do welcome messages and conversation_started work?

conversation_started fires when someone opens a chat with your bot, before they've subscribed. Viber permits one welcome message at that point. You return it in the HTTP response to the callback, using the send_message JSON without the receiver. Viber doesn't bill welcome messages.

How do you make your handler safe against duplicate events?

Delivered events can arrive more than once. Record each message_token you've processed, skip repeats before you create orders or replies, and return HTTP 200 fast. Do heavy work afterward in a queue, or your delivery rate can read above 100%.

Viber's webhook page gives no retry schedule for callbacks, so don't assume a failed callback is sent again.

How do you verify callbacks from Viber?

Callbacks reach a public URL, so anyone who finds it can post fake events. Viber's official Python library checks the X-Viber-Content-Signature header against an HMAC SHA-256 hash of the raw request body, keyed with your auth token. Reject calls that fail the check, and confirm the method in Viber's current developer documentation.

How do you send messages with the core messaging API?

send_message sends one message to one subscriber of your bot. The only exception is the single welcome message. Viber's send message page sets a 30 KB message limit, 100 messages to one user within an hour without a reply, and a sender name of 28 characters or fewer.

The optional tracking_data field holds 4,000 characters or fewer and comes back with the user's reply. A successful response returns status 0 and a message_token you can match to later delivered, seen and failed callbacks.

A plain text message:

{

  "receiver": "USER_ID", // subscriber ID from a callback

  "type": "text",

  "sender": { "name": "Acme Support" }, // 28 characters or fewer

  "text": "Your order #4821 has shipped!"

}

Which message types and rich media can you send?

Viber's official Python library sends text, URL, contact, picture, video, location, sticker, file, rich media and keyboard messages. SleekFlow's connection supports fewer, so check both lists before you plan a campaign.

SleekFlow's Help Center lists rich media and carousel content, contact cards, location messages and stickers as unsupported. It sets limits of 7,000 characters for text, 1 MB for images, 26 MB for MP4 video and 50 MB for files.

How does the broadcast API work for campaigns?

broadcast_message sends one message to many subscribers in a single request. Viber's broadcast page sets a limit of 300 subscribers per request, 500 requests per 10 seconds and 30 KB per message. A large audience needs batching and a queue.

Viber's developer pages show "last updated" dates of Feb and Mar 2023, so recheck these limits first. Under Viber's chatbot commercial model, Viber bills messages sent outside an active 24-hour session by the recipient's country code.

Each broadcast response carries a billing_status from 0 to 5, which tells you whether Viber charged for the message.

What error codes and rate limits should you plan for?

Viber returns a numeric status and a status_message with every response, and 0 means success. The errors you'll meet most are 1 (Invalid URL), 2 (Invalid Auth Token), 3 (Bad Data), 5 and 6 (receiver problems) and 12 (Too Many Requests).

The errors page also lists code 4 (Missing Data), code 10 (Webhook Not Set), and codes 23 (Free Messages Exceeded) and 24 (No Balance) for bots that have used their monthly free out-of-session messages.

How does SleekFlow work with the Viber API?

The raw API gives you full control, and it also gives you the webhook, the token, the rate limits and the monitoring to run. With SleekFlow's Viber integration, you connect one or more Viber Chatbots, which are Viber's business account type for conversations. Your agents then work in one shared inbox.

SleekFlow's Help Center lists these Viber features:

• Multiple chatbots. Connect more than one Viber Chatbot to one SleekFlow account.
• Send and receive. Handle messages through a Viber bot.
• Broadcasts. Create and manage broadcasts.
• QR codes and links. Share a Viber QR code or account link so customers can message you.

The connection guide adds that you can automate replies with Flow Builder.

To connect, you need an approved Viber bot token and admin access to your SleekFlow workspace. Open Channels, then Viber, then Connect, enter an account name, a channel name and your bot token, then share the QR code or link SleekFlow generates so customers can find your bot.

Should you build on the Viber API or connect it through SleekFlow?

Build on the API if you need custom logic and have developers to run a secure webhook. Connect through SleekFlow if your team mainly needs to reply and broadcast. Either way, apply to Viber for commercial terms first. See how it works on the Viber integration page.