> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Viber termination model

> How Orbit terminates Viber over two architecturally distinct paths — the SMPP lane on the orbit-vib host:port pair and the Rakuten Viber Business HTTP lane — what your tier setting flips at send time, how the retired content-prefix mechanism was superseded, and how delivery receipts, sender registration, and market availability differ between the two.

# 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](/channels/viber) covers the per-field API surface
and the [Tier 1 → Tier 2 upgrade guide](/guides/viber-upgrade) 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](/concepts/cross-channel-fallback) (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**:

| Organization state | Path taken |
| - | - |
| No `businessAccount.authToken` stored | Tier 1 SMPP, always. |
| Token stored (Tier 2 live) | Tier 2 HTTP first; Tier 1 SMPP when Tier 2 rejects the send. |

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](/concepts/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](/guides/viber-upgrade) 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](https://developers.viber.com/docs/api/rest-bot-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](/channels/viber) 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:

| | Tier 1 (SMPP) | Tier 2 (Business HTTP) |
| - | - | - |
| Acceptance signal | SMPP `submit_sm_resp` on the bind, then wire-level DLRs from the aggregator. | Viber `status: 0` plus `message_token` on the send response. |
| Terminal receipts | SMPP DLR stat vocabulary (`DELIVRD` / `UNDELIV` / `EXPIRED` / `REJECTD`) mapped into the canonical model; mapped tokens are documented on the [SMPP edge model](/concepts/smpp-edge-model). | Rakuten-signed delivery callbacks (`delivered`, `seen`, `failed`) against your auth token, posted to the platform's Viber DLR route and relayed into the same lifecycle. |
| Billing trigger | Charged on DLR `delivered`; submit-time and rejected sends are free. | Per your plan's Viber Business rates (or your own Rakuten account on BYO). |
| Failure detail | Aggregator rejection lands as a `failed` delivery status (recipient not on Viber, sender not allow-listed in market). | `details.viberStatus` carries Viber's own status code on a rejected send. |

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.

## Related

* [Viber channel reference](/channels/viber) — per-tier request fields, rich
  media metadata, inbound webhook envelope, and the full error table.
* [Upgrade Viber from Tier 1 to Tier 2](/guides/viber-upgrade) — the registration
  checklist, mid-flight cutover, and DLR monitoring on the hosted vs BYO path.
* [SMPP edge model](/concepts/smpp-edge-model) — the hub, the reconciler, and the
  DLR stat vocabulary the Tier 1 lane inherits.
* [DLR model: two planes, one vocabulary](/concepts/dlr-model-two-planes) — why
  carrier-side receipts and send-side statuses map into one lifecycle.
* [Cross-channel fallback](/concepts/cross-channel-fallback) — the org-level
  chain that retries a failed Viber send over SMS.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.