> ## 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 day one: allowlist a sender ID and send your first Tier 1 message

> Take a fresh tenant from Viber not yet used to a first delivered Tier 1 message: allowlist your alphanumeric sender ID with Devotel, send over POST /api/v1/messages/viber, read DLRs, arm Viber-to-SMS fallback, and know when to graduate to Tier 2.

# Viber Day One: Allowlist a Sender ID and Send Your First Tier 1 Message

Orbit's Viber Tier 1 (one-way SMPP) is live for every tenant on day one: no Rakuten registration, no per-tenant Viber Business signup, no approval window. This guide takes you from "Viber not yet used" to a first delivered Tier 1 message, and tells you when to start the Tier 2 registration that adds replies and rich media.

The [Viber channel reference](https://docs.orbit.devotel.io/channels/viber.md) holds the per-field detail and the [Viber termination model](https://docs.orbit.devotel.io/concepts/viber-termination-model.md) explains the two lanes; this page is the day-one task. If you are already sending Tier 1 and want the branded two-way sender, go to [Upgrade Viber from Tier 1 to Tier 2](https://docs.orbit.devotel.io/guides/viber-upgrade.md).

## 1. Decide the lane

Tier 1 is the right day-one choice when your traffic is one-shot and outbound: OTPs, appointment and shipping alerts, account and fraud notifications. You can send as soon as your sender ID is allow-listed. Wait for Tier 2, or start its registration now and send Tier 1 meanwhile, when you need inbound replies, images and rich cards, or a verified branded sender profile.

| | **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 |
| Media | Text + inline links | Text, images, rich cards, carousels, reply keyboards |
| Provisioning | Live as soon as your sender ID is allow-listed | Out-of-band Rakuten registration, 5–10 business days |
| Billing | Billed on DLR `delivered`; pre-submit rejections free, terminal failures refunded | Per your plan's Viber Business rates |
| Best for | OTPs, alerts, one-shot notifications | Conversational support, campaigns, ongoing engagement |

Both tiers share one endpoint, `POST /api/v1/messages/viber`, so starting on Tier 1 never blocks the upgrade: when Tier 2 is approved the platform reroutes your sends without a client change.

> [!NOTE]
>
> The tiers are not either/or. Most tenants send Tier 1 transactional traffic from day one and keep it as the fallback lane after Tier 2 goes live.

## 2. Allowlist your sender ID

A Tier 1 send carries an alphanumeric sender ID of up to 11 characters (for example `OrbitDemo`) in the `from` field. Devotel allowlists each ID with the upstream Viber aggregator before it can send; a sender ID that is not allow-listed is rejected at send time.

1. Pick the sender ID your recipients will see: alphanumeric, up to 11 characters.
2. Email [support@devotel.io](mailto:support@devotel.io) or your Devotel account manager with your organization ID and the ID you want allow-listed. Submit each ID during onboarding, and submit any new ID the same way before its first use.
3. Devotel registers the ID with the upstream aggregator. There is no self-serve allowlist and no per-tenant Viber Business signup; allow-listing is the only onboarding step Tier 1 needs.

A send attempted with a not-yet-listed ID is rejected and never billed, so testing an ID before confirmation costs nothing.

## 3. Send your first message

Tier 1 is text-only; put any call-to-action URL inline in `body`.

```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 order 4471 shipped. Track it: https://example.com/track/4471"
  }'
```

A successful request is accepted for delivery and returns `202`:

```json 202 theme={null}
{
  "data": {
    "id": "msg_viber_a1b2c3d4",
    "status": "queued",
    "channel": "viber"
  },
  "meta": {
    "request_id": "req_xK9f3m2h",
    "timestamp": "2026-10-27T09:15:00Z"
  }
}
```

`queued` means persisted and accepted, not delivered. The status moves to `submitted` when the SMPP hub accepts the handoff and to a terminal `delivered` or `failed` when the DLR arrives. Follow it either way:

* Poll `GET /api/v1/messages/{id}` until the status is terminal.
* Consume the delivery-status webhook and match on the message `id`, the same envelope every channel uses.

| Field | Type | Required | Description |
| - | - | - | - |
| `to` | string | yes | Recipient phone number in E.164 digits. |
| `body` | string | yes | Message text; inline links allowed. Rich media needs Tier 2. |
| `from` | string | no | Your allow-listed alphanumeric sender ID; falls back to your tenant default when omitted. |

## 4. Billing and DLR semantics

Tier 1 bills on DLR `delivered`. A message rejected before submit is free, and a terminal delivery failure refunds the charge, so you only pay for messages that reached the recipient's device.

Delivery reports arrive on the Jasmin DLR path and move the message through the usual `delivered` / `failed` / `rejected` lifecycle; there is nothing extra to configure on your side. To run your own consumer against the status webhook, follow the [DLR webhook consumer guide](https://docs.orbit.devotel.io/guides/dlr-webhook-consumer.md); the [delivery log](https://docs.orbit.devotel.io/guides/delivery-log.md) is the in-dashboard view of the same receipts.

Viber-specific failure reasons (recipient has no Viber install, sender not allow-listed in the destination market) land in the failure detail on the message and on the webhook.

## 5. Guardrails: rate limit and fallback

Tier 1 shares the platform's `POST /messages/viber` row: 50 requests per minute per organization by default. A burst above the row returns `429` with a `Retry-After` header and nothing is queued server-side; back off and retry, or stage bulk sends through the campaigns API so bursts never collide with transactional traffic.

Arm the safety net before your first production send: open **Settings → Channels → Cross-Channel Fallback** and add a rule with **Primary: Viber, Fallback: SMS**. When a Viber send fails for a Viber-specific reason (no Viber install on the device, aggregator rejection in that market), Orbit retries it over SMS automatically, from the next send after you save. The request body has no per-message fallback field by design; the organization-level rule keeps every send path consistent. If the recipient has opted out of SMS, the fallback leg is suppressed rather than delivered.

## 6. Inbound caveat: replies land nowhere until Tier 2

Tier 1 is outbound-only. When a recipient replies to your Tier 1 sender ID, that reply is not delivered to your webhook or inbox; there is no inbound Viber surface in this tier. Set the expectation in the message copy itself (for example "Replies are not monitored; contact support at [support@acme.com](mailto:support@acme.com)") and route conversational flows to a channel with inbound today, or to Tier 2 once it is approved.

## 7. When to graduate to Tier 2

Start the Tier 2 registration when you need replies, rich media, or a branded sender profile. Rakuten gates every Business sender behind a manual review of **5–10 business days**, brokered by your Devotel account manager; there is no expedited path, so plan campaign dates around the window. Before you submit, gather what Rakuten checks: the business registration details (legal name, registration number, registered address, country, contact email and phone, website), the branded sender display name (max 28 characters), the sender profile logo, and your destination markets. Your Tier 1 traffic keeps running throughout the review, and after approval the same endpoint reroutes to Tier 2 with no client change. The field-by-field registration walkthrough, status tracking, and the mid-flight cutover live in [Upgrade Viber from Tier 1 to Tier 2](https://docs.orbit.devotel.io/guides/viber-upgrade.md).

## 8. Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| First send rejected, unknown sender | The `from` sender ID is not allow-listed yet. | Submit the ID to Devotel (section 2) and retry once confirmed; the rejection was free. |
| `429` on a burst | Over the shared 50 requests per minute `/messages/viber` row. | Honour `Retry-After`; spread sends or stage them through the campaigns API (section 5). |
| Status never reaches a terminal state | The DLR has not arrived: consumer lag on your side, or the recipient device unreachable on Viber. | Match receipts with the [DLR webhook consumer guide](https://docs.orbit.devotel.io/guides/dlr-webhook-consumer.md); check the delivery log; confirm your status webhook subscription covers `viber`. |
| `failed` with a not-registered reason | Recipient has no Viber install, or the sender is not allow-listed in that market. | Arm Viber → SMS fallback (section 5) or drop the recipient from Viber sends. |


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