Viber

Viber is the smallest of the supported channels but still the dominant messenger in several markets (Eastern Europe, the Balkans, Philippines). Connecting is similar to Telegram — bot account, paste a token.

Connecting

1. Sign up for a Viber Bot at partners.viber.com.
2. Create a Bot (not a Public Account). Pick a display name, avatar, and category.
3. Copy the Authentication Token from the bot's settings page.
4. In Kinderpedia: Integrations → Viber → Connect → paste the token.

Kinderpedia validates via POST https://chatapi.viber.com/pa/get_account_info — a working token returns the bot's account info, which we cache for the integration card.

Webhook setup

After token validates, Kinderpedia auto-registers the webhook via set_webhook:

POST https://chatapi.viber.com/pa/set_webhook
{
  "url": "https://<your-domain>/api/integrations/viber/webhook",
  "event_types": ["subscribed", "unsubscribed", "delivered", "seen", "failed", "message"],
  "send_name": true,
  "send_photo": true
}

Viber requires HTTPS with a valid public cert — no self-signed, no IP addresses. For local dev, use a Cloudflare tunnel or ngrok with a properly-issued cert.

Inbound signature is X-Viber-Content-Signature (HMAC-SHA256 with the bot token as key). Validated server-side; mismatches are 401'd.

How conversations start

A user must subscribe to your bot before you can message them. Subscribe happens when:

• The user opens your bot from a Viber deep-link or search and taps the conversation row.
• Viber sends a subscribed event to your webhook with their user_id.

After subscribe, the bot can send messages anytime — no 24h window.

We render a deep-link QR on the post-submit form (when Viber is connected) similar to the WeChat flow, so leads can subscribe in one scan.

User identity

Viber exposes a stable per-bot user_id plus the user's display name, avatar, country, language, and (sometimes) Viber API version. Conversation keys: viber:<user_id>.

Phone number is not exposed unless the user explicitly shares it via Viber's contact-share feature. Same caveat as Telegram — prompt for it if you need it.

Message types

Viber has a richer message-type spectrum than the others:

Type	Inbound	Outbound
Text	✓	✓
Picture	✓	✓
Video	✓ (50 MB cap)	✓
File (PDF / etc.)	✓	✓ (50 MB cap)
Sticker	✓	—
URL	✓	✓
Contact	✓	✓
Location	✓	✓
Rich Media (carousels)	—	✓

Rich Media — Viber's killer feature for bots — is a card-based carousel (image + text + buttons) you can send from the composer's "Rich Media" mode. We expose a simple builder for it in Templates → Viber Rich Media but most schools don't need to bother.

Keyboards

Bot messages can carry a keyboard — a grid of buttons rendered under the message bubble. Tapping a button sends a reply_keyboard event back to the bot. We don't surface keyboard authoring in the basic composer (yet) — it lives in the rich-media template builder.

Delivery receipts

Viber sends delivered and seen events for every outbound. The inbox renders these as ✓ / ✓✓ tick marks on the message bubble, identical to WhatsApp's UX.

Unsubscribe

If a user blocks your bot or deletes the conversation, Viber sends an unsubscribed event. We mark the thread as Blocked + the parent's Viber identity as unreachable. Sending to an unsubscribed user fails with failed_with_text: "userNotSubscribed".

Common errors

Symptom	Likely cause
Webhook registration fails	URL not reachable over HTTPS with a valid cert (Viber rejects self-signed).
Send returns userNotSubscribed	User blocked / unsubscribed. Mark thread Blocked.
Send returns notAllowed	Bot account is suspended / under review.
Rich Media doesn't render	Image URLs not HTTPS, or aspect ratio off (Viber recommends 1:1 thumbnails).
No webhook events at all	Cert chain incomplete (Viber is strict). Test with openssl s_client -connect ….

Pricing

Viber Bot is free for unlimited messaging to subscribers. Commercial Public Accounts (different surface, with broadcast features) are paid — we don't support those.

Related

• Connecting channels
• Conversations
• Attachments