> ## 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

> Send Viber messages via two tiers — basic SMPP termination or full Viber Business HTTP API

# 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](/guides/rate-limits)).

### Send a Tier 1 message

```bash theme={null}
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:

1. Email [support@devotel.io](mailto: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.
2. Devotel submits the Rakuten Viber sender registration on your behalf and shepherds the application through Rakuten's review.
3. Once Rakuten approves the sender, Devotel attaches the issued auth token to your tenant configuration via the admin panel.
4. 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

```bash theme={null}
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`](https://developers.viber.com/docs/api/rest-bot-api/#rich-media-message) object — the card/carousel layout (`ButtonsGroupColumns`, `ButtonsGroupRows`, `Buttons`). When present, the message is sent as a `rich_media` message. |
| `metadata.keyboard`   | A Viber [`keyboard`](https://developers.viber.com/docs/api/rest-bot-api/#keyboards) 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](https://developers.viber.com/docs/api/rest-bot-api/)
accepts is supported.

```bash theme={null}
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:

```json theme={null}
{
  "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:

1. Open **Settings → Channels → Cross-Channel Fallback**.
2. 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).
3. 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](/api-reference/endpoints/messaging) reference for the full
envelope.