Download the PHP package sashalenz/viber-bot-api without Composer

Viber Bot API

Viber Bot REST API SDK for Laravel — a typed HTTP client, webhook signature verification, and a nutgram-style inbound handler engine.

It is the reusable Viber engine (think nutgram/nutgram + its Laravel bridge): the package owns the protocol, while app-specific glue (persistence, CRM binding, notification channels) lives in your application.

Features

• Outbound client — Account, Messages, Users over a typed transport with timeout/retry and per-call token override (multi-account).
• Message builders — text, picture, video, file, contact, location, url, sticker, and rich-media (carousel), each self-validating its Viber constraints and carrying the common tracking_data / min_api_version parameters.
• Keyboards — fluent Button / Keyboard builders (full Viber field set: background media, text styling, open-url behaviour, Frame / MediaPlayer / Map / InternalBrowser) and a SharePhoneButton onboarding primitive.
• Webhook security — X-Viber-Content-Signature HMAC-SHA256 verification as route middleware.
• Typed inbound events — every callback hydrated into a spatie/laravel-data DTO (MessageEvent, SubscribedEvent, ConversationStartedEvent, …).
• Handler engine — register onMessage / onText / onContact / … handlers with a short-circuitable middleware pipeline; dispatched automatically from the webhook controller.
• Artisan commands — manage the webhook lifecycle from the CLI.

Requirements

• PHP 8.2 – 8.5
• Laravel 11, 12, or 13

Installation

The package is distributed via a private Composer registry. Add the repository, then require it:

Publish the config:

Set at least the token and sender name in your .env:

Configuration

All options live in config/viber-bot-api.php and are env-driven:

event_types (the events requested on set_webhook) is an array in the config file and defaults to all of message, subscribed, unsubscribed, conversation_started, delivered, seen, failed.

Outbound

send() / broadcast() return a typed SendMessageResponse (->status, ->message_token, …). A non-zero Viber status throws ViberBotApiException.

Message builders

Every builder implements MessageContract and validates its own Viber constraints in the constructor (throwing ViberBotApiException). Media is URL-based — pass a public https:// URL, not a binary upload.

Every builder also accepts the two send_message parameters common to all message types — trackingData (≤ 4096 chars, echoed back on the matching delivered / seen / message callbacks) and minApiVersion:

Keyboards

Account / webhook

⚠️ A Viber bot has exactly one webhook. setWebhook overwrites the previous one — there is no parallel delivery.

Users

Inbound

The package registers POST /{prefix}/{webhook_key} (default /viber-bot-api/webhook), guarded by the VerifyViberSignature middleware (HMAC-SHA256 of the raw body against your token). Prefix, domain, extra middleware, and on/off are configurable. The controller verifies the signature, parses the payload into a typed event, dispatches it through the container-bound Bot\Viber engine, and always responds 200 fast (Viber retries any non-200).

Registering handlers

Bot\Viber is bound as a singleton, so register handlers once — e.g. in a service provider's boot():

The first matching handler (in registration order) wins. Handlers receive the typed event plus the bot instance; $bot->reply(...) sends a send_message back to the user behind the current update. onText($pattern, ...) matches the message text against an anchored unicode regex.

conversation_started

This event is special: the user is not subscribed yet, so a real send_message is rejected. Return a MessageContract (or payload array) from the handler and the controller emits it inline in the HTTP 200 response, wrapped with the sender envelope:

Console commands

set-webhook defaults to the package webhook route URL when no argument is given, and prompts for confirmation unless --force is passed.

Typed request DTOs (optional)

If you prefer typed request payloads over the array/builder surface, use the RequestData DTOs:

Testing

Viber gotchas baked into the design

• User ids are opaque strings, not numbers.
• conversation_started: the user is not yet subscribed — you can only greet by returning a send_message-shaped body in the HTTP response (within 5 min).
• Media is URL-based (not binary uploads).
• get_user_details is capped at 2 calls / 12h per user — cache it.
• Commercial: customer-initiated session messages (24h window) are free; business-initiated messages are paid.

License

MIT. See LICENSE.md.