Viber (Integrations)

Integration-tile view. For inbox behaviour and message types, see Chat Inbox → Viber.

Connecting

Viber bots are registered at partners.viber.com:

1. Sign up + create a Bot (not a Public Account).
2. Provide display name, avatar, category.
3. Copy the Authentication Token from the bot settings.

In Kinderpedia: Integrations → Viber → Connect → paste the token. We validate via:

POST https://chatapi.viber.com/pa/get_account_info
X-Viber-Auth-Token: <token>

A 200 { status: 0 } response means the token works. Account info (display name, avatar) gets cached for the tile.

Webhook auto-registration

On successful validation, we auto-register the 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 publicly-trusted cert — self-signed will fail registration. For local dev, you must use Cloudflare Tunnel or ngrok with a properly-issued cert. The dev cert won't work even with --insecure flags on the Viber side.

Signature validation

Every inbound has X-Viber-Content-Signature — HMAC-SHA256 of the raw body with the bot token as the key. We validate constant-time. Mismatches are 401'd.

Subscribe vs unsubscribe events

Viber's lifecycle events:

Event	Triggered by	Effect
subscribed	User opens bot deep-link + taps subscribe	Capture user_id, create conversation
unsubscribed	User blocks bot / deletes conversation	Mark thread Blocked
conversation_started	User opens bot but hasn't subscribed yet	(We send a welcome message inviting them to subscribe)
delivered	Message reached the user's device	Render ✓ on outbound bubble
seen	User opened the message	Render ✓✓
failed	Send failed (e.g. user not subscribed)	Toast error on staff side
message	User sent a message to the bot	Normal inbound

Rich Media

Unique to Viber: Rich Media carousels — card-based messages with image + text + buttons. We expose a basic Rich Media template builder in Templates → Viber. Most schools don't bother and stick with text + media.

Public Account vs Bot

Viber distinguishes between Bots and Public Accounts:

• Bots — free, unlimited messaging to subscribers, full API. What we support.
• Public Accounts — paid, broadcast features, different surface. Not supported.

If you have a Public Account, you'll need to create a separate Bot for Kinderpedia.

Country / language

Viber's API exposes the user's country and language (when available) on the subscribed event. We capture these to conversation metadata for context — useful for staff to know to reply in the user's preferred language.

Disconnecting

Disconnect:

1. Calls POST /pa/set_webhook with empty URL to un-register.
2. Clears credentials.
3. Row → disconnected.

The bot stays alive in partners.viber.com — we just stop receiving events.

Common errors

Symptom	Likely cause
Webhook registration fails	URL not HTTPS with publicly-trusted cert.
Connect rejects with { status: 1 }	Token invalid / revoked.
Send returns userNotSubscribed	User blocked / unsubscribed. Mark thread Blocked.
Send returns notAllowed	Bot account suspended / under review. Check partners.viber.com.
Rich Media doesn't render on user's phone	Image URLs not HTTPS, or wrong aspect ratio (Viber recommends 1:1 thumbnails).
No webhook events at all	Cert chain incomplete. Test with openssl s_client -connect ….

Related

• Viber in the Chat Inbox
• Integrations overview