> ## 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.
# Upgrade Viber from Tier 1 to Tier 2
> Register a branded Viber Business sender, move your tenant from one-way Tier 1 SMPP messaging to two-way Tier 2 without changing client code, and wire inbound routing and DLR monitoring.
# Upgrade Viber from Tier 1 to Tier 2
Orbit carries Viber in two non-overlapping tiers. Tier 1 (one-way SMPP) works on day one for every tenant; Tier 2 (two-way Viber Business, branded sender) unlocks inbound replies, rich media, and a verified sender profile — but Rakuten Viber gates the branded sender behind a manual registration that takes 5–10 business days.
This guide walks the full upgrade: picking the right tier for each traffic class, running Tier 1 properly while you wait, submitting the Tier 2 registration, switching over mid-flight, wiring inbound routing, and watching delivery receipts after the cutover. The [Viber channel reference](/channels/viber) holds the per-field detail; this page is the task.
## 1. Pick Tier 1 vs Tier 2
| | **Tier 1 — One-way Basic** | **Tier 2 — Two-way Business** |
| --------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| Sender identity | Allow-listed alphanumeric sender ID (up to 11 characters) | Branded Viber Business sender — verified business name + logo |
| Direction | Outbound only | Outbound + inbound replies |
| Latency class | Same routing network both tiers; send latency is identical — the difference is provisioning, not per-message speed | Same routing network both tiers; send latency is identical |
| Media | Text + inline links only | Text, images via `media_url`, rich cards, carousels, reply keyboards |
| Provisioning | Auto-provisioned — live on first send | Out-of-band Rakuten registration, 5–10 business days |
| Billing | Charged on DLR `delivered` | Per your plan's Viber Business rates |
| Best for | OTPs, appointment alerts, one-shot notifications | Conversational support, campaigns, ongoing engagement |
Both tiers share one endpoint — `POST /api/v1/messages/viber`. The platform routes each send through the right provider based on your tenant configuration, so the upgrade never touches client code.
The tiers are not necessarily either/or. Keep Tier 1 as a fallback lane for time-sensitive transactional traffic while the Tier 2 registration is in council review, and route conversational traffic to Tier 2 once it is approved.
## 2. Run Tier 1 correctly while you wait
Tier 1 is wholesale Viber-over-SMPP termination that Devotel maintains upstream — no per-tenant Viber Business signup.
* **Sender-ID allow-listing.** Submit each alphanumeric sender ID (up to 11 characters, e.g. `OrbitDemo`) to Devotel during onboarding, and submit a new one before first use. A sender ID that is not allow-listed is rejected at send time.
* **DLR semantics.** Tier 1 bills on DLR `delivered` — submit-time and rejected messages are free. Delivery reports arrive on the Jasmin DLR path and update message status to the usual `delivered` / `failed` / `rejected` lifecycle.
* **Rate limits.** Tier 1 shares the platform's `/messages/viber` row (50 requests per minute by default — see [Rate Limits](/guides/rate-limits)). Bursts above the row return `429`.
* **Conversation fallback stays available.** Enable **Settings → Channels → Cross-Channel Fallback** with **Primary: Viber, Fallback: SMS** so an undeliverable Tier 1 send retries over SMS automatically.
## 3. Register the Tier 2 branded sender
Rakuten Viber does not offer a self-serve Business sender API. Registration with Rakuten is brokered by your Devotel account manager — Orbit submits on your behalf, shepherds the application through Rakuten's manual review, and attaches the issued auth token to your tenant once approved. Typical end-to-end onboarding is **5–10 business days**; Rakuten may extend that if they request additional brand verification (trademark proof, domain ownership, sample message content).
### What to prepare
Gather everything before you submit — an incomplete application restarts the review clock:
| Field | What Rakuten checks |
| --------------------- | ------------------------------------------------------------------------ |
| `legal_name` | Registered legal entity name (2–200 characters) |
| `registration_number` | Company / business registration number (VAT, company no.) |
| `registered_address` | Full registered business address |
| `country` | ISO-3166-1 alpha-2 country code of registration |
| `contact_email` | Primary verification contact email — Rakuten may write to it |
| `contact_phone` | Primary contact phone in E.164 form |
| `website` | Public business website — optional, but strongly recommended |
| `sender_name` | The branded sender display name recipients see — **max 28 characters** |
| `business_category` | Business vertical (free text; Viber maps to its taxonomy) |
| `description` | Intended use + sample message content — optional, up to 1,000 characters |
A logo for the sender profile is part of the branding package — the dashboard onboarding dialog collects it alongside the business details.
### Submit from the dashboard or the API
In the dashboard, open **Settings → Channels → Viber** and start the Tier 2 onboarding dialog on the channel card. Via API:
```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/settings/channels/viber/tier2/submit \
-H "X-API-Key: dv_live_sk_..." \
-H "Content-Type: application/json" \
-d '{
"legal_name": "Acme Corporation Inc.",
"registration_number": "HRB-123456",
"registered_address": "1 Market St, San Francisco, CA 94105",
"country": "US",
"contact_email": "messaging@acme.com",
"contact_phone": "+14155551234",
"website": "https://acme.com",
"sender_name": "Acme",
"business_category": "Retail",
"description": "Order updates and customer support over Viber."
}'
```
**Response (`200`):**
```json theme={null}
{
"data": {
"status": "pending",
"sender_name": "Acme",
"business_category": "Retail",
"legal_name": "Acme Corporation Inc.",
"submitted_at": "2026-08-24T12:00:00Z",
"updated_at": "2026-08-24T12:00:00Z",
"forwarded_at": "2026-08-24T12:00:00Z",
"rejection_reason": null
}
}
```
The submission lands in `status: "pending"` and is recorded as forwarded to the onboarding queue. A malformed field returns `400 INVALID_SUBMISSION` with per-field errors.
### Track the review
```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/settings/channels/viber/tier2/status \
-H "X-API-Key: dv_live_sk_..."
```
| Status | Meaning |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `not_submitted` | No application yet |
| `pending` | Submitted and forwarded; Rakuten review in progress |
| `approved` | Sender registered — Devotel attaches the auth token to your tenant and Tier 2 routing goes live |
| `rejected` | Rakuten declined — `rejection_reason` carries the reviewer's reason; fix the flagged detail and resubmit through the same endpoint (a resubmission resets the clock to `pending`) |
Plan campaign launch dates around the 5–10 business-day window. Expedited onboarding is not available — Rakuten gates every branded sender behind a manual approval queue.
## 4. Migrate mid-flight without client changes
When the status flips to `approved`, Devotel attaches the issued Viber Business auth token to your tenant and the same `POST /api/v1/messages/viber` endpoint starts routing through the Business HTTP API instead of SMPP. There is nothing to redeploy:
* **No endpoint change.** One `POST /api/v1/messages/viber` serves both tiers; the tenant configuration picks the provider.
* **No request-shape change.** `to`, `body`, and `from` mean the same thing on both tiers — on Tier 2, `from` is your branded sender. Now that Tier 2 is live you can add `media_url` and the `metadata.rich_media` / `metadata.keyboard` payloads for rich cards and keyboards; a Tier 1 tenant sending those fields gets a provider rejection.
* **Keep Tier 1 sends running during the review.** The registration never suspends Tier 1 — transactional traffic on the SMPP lane continues uninterrupted until you repoint it.
* **After approval, resubmissions are unnecessary.** The same status endpoint becomes your health check: `approved` means the branded sender is live.
## 5. Wire inbound routing on Tier 2
Tier 2 is the first tier where Viber users can reply. Replies arrive on the Viber inbound webhook and land at your configured endpoint as the standard inbound envelope (`channel: "viber"`, `direction: "inbound"`).
1. Open **Settings → Webhooks** and register your inbound message endpoint if you have not already.
2. Subscribe to inbound message events for the `viber` channel.
3. Handle the envelope like any other channel — the conversation appears in the inbox the same way SMS and WhatsApp replies do.
Viber signs each Tier 2 callback with your tenant's own Business auth token, so inbound from your branded sender verifies per-tenant — no shared global secret to rotate. (Rakuten also persists your webhook callback URL on the sender profile during registration; the platform-side routing above is what delivers the message into your account.)
## 6. Watch DLRs on the hosted vs BYO path
Delivery receipts reach the same message-status lifecycle either way, but the upstream path differs — know which one you run so you read the right signal:
* **Hosted tier.** When Devotel holds the Viber Business sender relationship and attaches it to your tenant (the normal flow above), delivery reports arrive on the Viber Tier 2 DLR path. Message status moves to `delivered` / `failed` with the provider's reason on failures.
* **BYO Business account.** If you bring your own Viber Business credentials (a sender you registered with Rakuten directly), the send path resolves to your provider by the same tenant preference. Delivery reports still flow in and update the same message status — the only difference is whose Rakuten account the traffic bills against.
In both cases, watch status from the same places: the [message delivery log](/guides/delivery-log), message status webhooks, and the per-message `GET /api/v1/messages/{id}` read. Viber-specific failure reasons (recipient has no Viber install, sender not registered in the destination market) land in the failure detail field.
## 7. Production checklist
* [ ] Your Tier 1 sender IDs are allow-listed **before** first send, in every market you send to.
* [ ] Cross-channel fallback (Viber → SMS) is configured under **Settings → Channels → Cross-Channel Fallback** for unreachable recipients.
* [ ] Tier 2 registration form submitted with a `sender_name` of 28 characters or fewer and complete legal details.
* [ ] Status polled to `approved` (or dashboard card green) before announcing the branded sender to customers.
* [ ] Client sends unchanged — same endpoint, same fields — with `media_url`, `rich_media`, and `keyboard` added only where Tier 2 is live.
* [ ] Inbound webhook subscribed to Viber inbound events; replies visible in the inbox.
* [ ] DLR monitoring points at the delivery log and status webhooks for both the hosted and (if used) BYO paths.
* [ ] Campaign launch dates padded by the 5–10 business-day Rakuten review window, with Tier 1 as the fallback lane.