Viber

Viber reaches 1 billion users worldwide. Orbit offers two non-overlapping tiers — pick the one that matches your use case.

Tier	Direction	Sender	Provisioning	Use case
Tier 1 — One-way Basic Messaging	Outbound only	Allow-listed alphanumeric sender ID	Auto-provisioned by Devotel (self-serve on first send)	Transactional alerts, OTPs, one-shot notifications
Tier 2 — Two-way Advanced Messaging	Inbound + Outbound	Branded Viber Business sender (logo + verified name)	Out-of-band: Rakuten Viber sender registration coordinated by your Devotel account manager — typical onboarding is 5-10 business days	Conversational support, campaigns, rich media, ongoing engagement

Both tiers share the same POST /api/v1/messages/viber endpoint — the platform routes through the right provider based on your tenant configuration. You don’t need to change client code when you upgrade from Tier 1 to Tier 2.

Tier 1 — One-way Basic Messaging

Tier 1 is wholesale Viber-over-SMPP termination. Devotel maintains the upstream aggregator relationship, so every paying tenant gets outbound Viber the moment their account is wired into the platform’s SMPP route — no per-tenant Viber Business signup is required.

How it works

Routing: messages flow apps/api → Jasmin HTTP API → SMPP client smppc(viber) → upstream aggregator → Viber.
Sender identity: an alphanumeric sender ID (up to 11 characters, e.g. OrbitDemo). Sender IDs must be allow-listed by Devotel before first use — submit yours during onboarding.
Direction: outbound only. Inbound replies are not delivered to your webhook in this tier.
Billing: charged on DLR delivered. Submit-time and rejected messages are free.
Throughput: subject to your plan’s /messages/viber rate-limit row (see Rate Limits).

Send a Tier 1 message

curl -X POST https://api.orbit.devotel.io/api/v1/messages/viber \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "OrbitDemo",
    "body": "Your appointment is confirmed for March 10 at 2:00 PM."
  }'

The sender ID is passed in the from field (the allow-listed alphanumeric ID — there is no sender_name field). Tier 1 is text-only. Rich media (attach a media_url) and inbound replies require Tier 2.

Tier 2 — Two-way Advanced Messaging

Tier 2 uses the Viber Business HTTP API directly with a per-tenant authentication token. You get a branded sender (verified business name, logo), inbound replies routed to your webhook, and media-rich messages (image attachments via media_url).

How to enable

Tier 2 is not self-serve — branded Viber Business sender activation requires sender registration directly with Rakuten Viber, which Orbit cannot bypass. The registration is coordinated out-of-band by your Devotel account manager. Typical end-to-end onboarding is 5-10 business days, sometimes longer if Rakuten Viber requests additional brand verification artifacts (trademark proof, domain ownership, sample message content). To provision your tenant:

Email support@devotel.io or contact your Devotel account manager with your organization ID, the business name + logo you want on the sender profile, and the destination markets you plan to message.
Devotel submits the Rakuten Viber sender registration on your behalf and shepherds the application through Rakuten’s review.
Once Rakuten approves the sender, Devotel attaches the issued auth token to your tenant configuration via the admin panel.
You’re live and the same POST /api/v1/messages/viber endpoint starts routing through the Business HTTP API instead of SMPP — no code change required.

Why the timeline matters: Rakuten Viber gates every branded Business Messages sender behind a manual approval queue. Expedited onboarding is not available — plan campaign launch dates around the 5-10 business-day window and have Tier 1 (SMPP) ready as a fallback for time-sensitive transactional traffic during the wait.

Send a Tier 2 rich message

curl -X POST https://api.orbit.devotel.io/api/v1/messages/viber \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "OrbitBrand",
    "body": "Check out our spring collection! https://example.com/shop",
    "media_url": "https://example.com/images/promo.jpg"
  }'

The basic request body is the same simple shape on both tiers — to, body, an optional from (branded sender), and an optional media_url for an image or other media attachment. For a plain text or media message, put any call-to-action link inline in body.

Tier 2 media

Field	Description
`body`	Message text (required). Put any CTA URL inline here.
`media_url`	URL of an image or other media to attach to the message.
`from`	Branded Viber Business sender ID.

Tier 2 rich cards, carousels, and keyboards

Tier 2 also sends Viber’s structured message types — rich cards (buttons with images, prices, and tap actions), multi-card carousels, and reply keyboards. You supply the native Viber payload through two metadata keys on the same POST /api/v1/messages/viber request:

Metadata key	Description
`metadata.rich_media`	A Viber `rich_media` object — the card/carousel layout (`ButtonsGroupColumns`, `ButtonsGroupRows`, `Buttons`). When present, the message is sent as a `rich_media` message.
`metadata.keyboard`	A Viber `keyboard` object — reply buttons attached beneath the message. Can be sent on its own (with `body`) or alongside `metadata.rich_media`.

metadata values are strings, so pass each payload as a JSON string. The platform parses it and forwards the native structure to Viber unchanged, so any field the Viber Business REST API accepts is supported.

curl -X POST https://api.orbit.devotel.io/api/v1/messages/viber \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "OrbitBrand",
    "body": "Spring collection is live",
    "metadata": {
      "rich_media": "{\"Type\":\"rich_media\",\"ButtonsGroupColumns\":6,\"ButtonsGroupRows\":6,\"BgColor\":\"#FFFFFF\",\"Buttons\":[{\"Columns\":6,\"Rows\":3,\"ActionType\":\"open-url\",\"ActionBody\":\"https://example.com/shop\",\"Image\":\"https://example.com/images/promo.jpg\"},{\"Columns\":6,\"Rows\":2,\"ActionType\":\"reply\",\"ActionBody\":\"shop-now\",\"Text\":\"Shop now\",\"TextSize\":\"large\"}]}"
    }
  }'

To attach a reply keyboard instead of (or in addition to) a rich card, set metadata.keyboard to a JSON-encoded Viber keyboard object:

{
  "keyboard": "{\"Type\":\"keyboard\",\"Buttons\":[{\"ActionType\":\"reply\",\"ActionBody\":\"yes\",\"Text\":\"Yes\"},{\"ActionType\":\"reply\",\"ActionBody\":\"no\",\"Text\":\"No\"}]}"
}

Rich cards, carousels, and keyboards require a Tier 2 branded sender — a Tier 1 SMPP tenant can only send text and inline links. If Viber rejects the structure, the send returns a 502 with the provider’s reason in details; check your payload against the linked Viber reference.

Inbound replies (Tier 2)

When a Viber user replies, the message lands at your configured webhook endpoint with a standard inbound envelope (channel: "viber", direction: "inbound"). Configure your webhook URL under Settings → Webhooks.

Delivery & fallback (Tier 1 and Tier 2)

When a Viber message cannot be delivered (recipient does not have Viber installed, sender ID is not allow-listed in the destination market, the upstream aggregator returns a permanent failure, or — for Tier 2 — the Rakuten Viber Business HTTP API rejects the send), Orbit can automatically retry the send over another channel (typically SMS) without changing your request. The fallback chain is configured per organization, not per request. Once configured, every Viber send transparently retries the next channel in the chain when delivery fails for a Viber-specific reason.

Configure Viber → SMS fallback

The cross-channel fallback chain lives on the organization, under settings.cross_channel_fallback. Enable it once from the dashboard:

Open Settings → Channels → Cross-Channel Fallback.
Add a rule with Primary: Viber and Fallback: SMS (you can chain more channels — e.g. Viber → WhatsApp → SMS — and they will be tried in order).
Save. The change takes effect on the next send; no redeploy or send-path change is required.

What triggers the fallback

Recipient is not reachable on Viber — the destination number is not registered with Viber, or (Tier 2) the Viber Business API returns a capability error. The router advances to the next channel in the chain.
All Viber providers fail — every registered Viber provider (Tier 1 SMPP and any Tier 2 HTTP API) returns a non-retryable error within the configured retry budget.
TCPA opt-out re-check — when the chain falls through to SMS, Orbit re-runs the SMS opt-out + DNC check against the recipient. If they have opted out of SMS (even though they accepted Viber), the message is suppressed rather than delivered over SMS.

The request body for /messages/viber does not accept a fallback field — passing one is ignored. Fallback behavior is entirely driven by the organization-level configuration so it stays consistent across every send path (API, campaigns, journeys, inbox replies) without requiring callers to remember to set a flag. The fallback runs through the standard SMS billing path — see the Messaging API reference for the full envelope.

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Billing

Webhooks

Compliance

Legal

Changelog

Viber

Viber

Tier 1 — One-way Basic Messaging

How it works

Send a Tier 1 message

Tier 2 — Two-way Advanced Messaging

How to enable

Send a Tier 2 rich message

Tier 2 media

Tier 2 rich cards, carousels, and keyboards

Inbound replies (Tier 2)

Delivery & fallback (Tier 1 and Tier 2)

Configure Viber → SMS fallback

What triggers the fallback

​Viber

​Tier 1 — One-way Basic Messaging

​How it works

​Send a Tier 1 message

​Tier 2 — Two-way Advanced Messaging

​How to enable

​Send a Tier 2 rich message

​Tier 2 media

​Tier 2 rich cards, carousels, and keyboards

​Inbound replies (Tier 2)

​Delivery & fallback (Tier 1 and Tier 2)

​Configure Viber → SMS fallback

​What triggers the fallback

Viber

Tier 1 — One-way Basic Messaging

How it works

Send a Tier 1 message

Tier 2 — Two-way Advanced Messaging

How to enable

Send a Tier 2 rich message

Tier 2 media

Tier 2 rich cards, carousels, and keyboards

Inbound replies (Tier 2)

Delivery & fallback (Tier 1 and Tier 2)

Configure Viber → SMS fallback

What triggers the fallback