Skip to main content

​
Viber termination model

Orbit terminates Viber over two architecturally distinct paths that both bind to the same channel, viber, at the router. Tier 1 egresses as SMPP through a dedicated termination account, orbit-vib, on Devotel’s SMPP hub; the hub routes anything bound under that identity to Viber by construction. Tier 2 calls the Rakuten Viber Business HTTP API directly with your per-organization auth token. Your request never names a tier: one endpoint, one envelope, and your organization’s configuration decides which path carries each send. The Viber channel reference covers the per-field API surface and the Tier 1 → Tier 2 upgrade guide walks the migration. This page is the architecture underneath both — the piece you need when you are reading a delivery receipt, debugging a rejection, or planning an upgrade.

​
Two tiers, one channel

Both tiers serve POST /api/v1/messages/viber. On every send the API asks two questions, in order:
  1. Does this organization hold a Tier 2 Business auth token? The token is stored on your organization at settings.channels.viber.businessAccount.authToken and attached by Devotel once Rakuten approves your branded sender. When it is present, the send is offered to the Tier 2 Viber Business HTTP path first.
  2. Otherwise, the send runs the Tier 1 SMPP path. Tier 1 is registered globally for every tenant — no per-tenant credential exists — so an organization without a Business token terminates on orbit-vib by default.
That ordering is the whole dispatch. Providers for a channel are tried in priority order, so a Tier 2 organization also falls back to Tier 1 when the Business API cannot take a particular send — for example, when the recipient is not a Viber user. The same fallback carries into your configured cross-channel fallback chain (Viber → SMS) when every Viber path fails.

​
What a tier change flips

The tier you run is not a request field and not a per-message flag; it is the presence of the Business token on your organization: Upgrading therefore changes nothing on your side except waiting for the token to land. The endpoint, the request body, and the response envelope are identical on both tiers — to, body, from, and the 202 with id / status / channel: "viber". Fields that only the Business API understands (media_url, metadata.rich_media, metadata.keyboard) are rejected while you are on Tier 1 and start working the moment the token is attached. Nothing in your client code names a provider; the router’s channel-neutral request is picked up by whichever provider your configuration resolves.

​
Tier 1 — Viber over SMPP

Tier 1 is wholesale Viber termination: Devotel holds the upstream aggregator relationship, and every tenant’s traffic rides it. The path is: apps/api → Jasmin HTTP API → SMPP client smppc(viber) bound as orbit-vib → upstream aggregator → Viber. The terminating hop is a plain SMPP session: same PDU shape and same DLR machinery as the SMS platform, with the channel bound at the account rather than in the message. See SMPP edge model for the hub and reconciler underneath.

​
Why orbit-vib sits apart from orbit-new

The SMPP hub terminates two dedicated accounts on the same hub: orbit-new carries SMS and orbit-vib carries Viber. Two properties fall out of that split:
  • The channel is decided at bind time. Anything bound with the Viber system_id is routed to Viber by the hub itself; nothing in the message body selects a destination. The SMS and Viber flows can never cross-contaminate, and each account carries its own throughput, aggregation, and DLR accounting.
  • The posture matches the traffic. Tier 1 is transactional by design — one-way, text-only, alphanumeric sender ID. Sending media over it returns VALIDATION_ERROR (422), and inbound replies are not delivered in this tier. Keeping those constraints on a dedicated account keeps the transactional-only posture enforced at the termination plane, not as an afterthought in application code.
The SMPP session for Viber rides Devotel’s wholesale routing egress — the same egress discipline the rest of the platform’s outbound traffic follows.

​
The retired __VIBER__: content prefix

Before the dedicated Viber SMPP account existed, the HTTP gateway design had no channel binding on the wire: Viber traffic was distinguished by prefixing the message content with __VIBER__: and stripping it before termination. That mechanism is gone:
  • Content was doing routing’s job. A prefix inside body is data as far as SMS is concerned; a misformatted body misrouted, and the prefix could leak to handsets if the strip step ever ran out of order.
  • Registry-level routing is what replaced it. The orbit-vib account plus the channel = "viber" provider entry mean channel selection lives in the routing registry and the bind, where it belongs. The send path became identical to SMS end to end — same PDU shape, same DLRs — with the channel advertised at the registry instead of smuggled in the text.
No API ever exposed the prefix; if you encounter it in an old integration note or payload it is a museum piece and safe to delete — the SMPP path ignores nothing and strips nothing, because there is nothing left to strip.

​
Tier 2 — Viber Business HTTP

Tier 2 is your own relationship with the Viber Business platform, brokered through Devotel. Rakuten Viber is the operator of Viber’s business messaging; branded Business senders sit behind Rakuten’s manual approval queue, and Devotel submits and shepherds the registration on your behalf — the upgrade guide lists the artifacts Rakuten reviews and the typical 5–10 business-day window. Once approved, Devotel attaches the issued auth token (plus your approved sender name and avatar) to your organization under settings.channels.viber.businessAccount, and sends egress to Rakuten’s endpoint: the provider posts each message to https://chatapi.viber.com/pa/send_message authenticated with your token via the X-Viber-Auth-Token header. That is the same canonical Viber Business REST API your payload options come from — text, picture, video, file, url, rich cards, carousels, and reply keyboards. What the Business path adds over Tier 1:
  • Brand surface — recipients see your verified business name and logo, not a bare alphanumeric ID.
  • Rich media — media_url attachments and the native rich_media / keyboard structures passed through metadata.
  • Inbound two-way — user replies POST to the platform’s inbound route and relay to your webhook (channel: "viber", direction: "inbound"); the channel reference documents the envelope and the chatbot capability an account needs to receive replies.
Tier 2 also honors your own Rakuten account: an organization that registered a sender directly with Rakuten can bring that token, and sends resolve through it by the same tenant configuration — see the upgrade guide’s hosted-vs-BYO DLR section.

​
Delivery receipts by tier

Both tiers end in the same canonical status lifecycle — sent, delivered, failed — and surface at the same three places: the delivery log, the message-status webhook, and GET /api/v1/messages/{id}. The upstream receipt differs: Receipts never skip the plane they started on: a Tier 1 send is receipted over the SMPP wire, a Tier 2 send over the signed callback. What your integration sees is one vocabulary either way, which is also why cross-channel fallback can treat “Viber failed” uniformly when deciding to retry over SMS.

​
Sender registration and market availability

The sender you appear as — and who clears it — is tier-specific:
  • Tier 1 — an alphanumeric sender ID up to 11 characters (e.g. OrbitDemo). Devotel registers the ID with the upstream Viber aggregator before first use; until it is allow-listed, sends for that ID are rejected at the aggregator and surface as a failed delivery status. Registration happens per ID, per market: an ID cleared for one destination market is not automatically cleared for another, so submit every ID for every market you send to.
  • Tier 2 — a branded sender profile (verified name + logo, sender name up to 28 characters) approved by Rakuten itself. Availability is gated by Rakuten’s market rules and brand review: business category, destination markets, and — when asked — trademark or domain-ownership proof all decide whether and where a sender goes live.
The allow-list model explains a Tier 1 failure class operators meet often: “send accepted by the API, then failed on the status webhook” is usually an ID not yet allow-listed in the destination market, not a platform fault — the API accepted the send because acceptance and market clearance are different gates.

​
Interoperating with the router

Because the dispatch is channel-neutral at the request and provider-picked at the configuration, Viber composes with the router’s other planes without tier-specific code:
  • Cross-channel fallback — the organization-level chain (Viber → SMS and longer chains) fires when the Viber path in use fails terminally, and the TCPA re-check applies on fall-through to SMS.
  • Rate limits — your /messages/viber per-organization row bounds the request envelope on both tiers; Tier 2 additionally rides your Rakuten quota.
  • DLR-driven billing and analytics — both tiers stamp the same canonical statuses, so cost rollups and delivery-rate reporting read one stream.
The send envelope, rate-limit row, and fallback chain are platform-level contracts; what your tier setting changes is only which upstream terminates the message and which receipts close it out.