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"
  }'

{
  "data": {
    "id": "msg_viber_e5f6g7h8",
    "status": "queued",
    "channel": "viber"
  },
  "meta": {
    "request_id": "req_xK9f3m2h",
    "timestamp": "2026-03-08T00:00:00Z"
  }
}

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"
  }'

{
  "data": {
    "id": "msg_viber_e5f6g7h8",
    "status": "queued",
    "channel": "viber"
  },
  "meta": {
    "request_id": "req_xK9f3m2h",
    "timestamp": "2026-03-08T00:00:00Z"
  }
}

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).

Send a Tier 1 message

curl -X POST https://api.orbit.devotel.io/api/v1/messages/viber \
  -H "X-API-Key: dv_test_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "from": "OrbitDemo",
    "body": "Your appointment is confirmed for March 10 at 2:00 PM."
  }'

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY });

// Fully-typed per-channel method — prefer it over the generic send.
const message = await orbit.messages.sendViber({
  to: "+14155552671",
  from: "OrbitDemo",
  body: "Your appointment is confirmed for March 10 at 2:00 PM.",
});

console.log(message.data.id);      // msg_viber_a1b2c3d4
console.log(message.data.status);  // 'queued'

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

# The Python SDK has no typed send_viber method — reach the channel
# endpoint through the client.request escape hatch (raw JSON returned).
message = client.request(
    "POST",
    "/messages/viber",
    json_body={
        "to": "+14155552671",
        "from": "OrbitDemo",
        "body": "Your appointment is confirmed for March 10 at 2:00 PM.",
    },
)

print(message["data"]["id"])       # msg_viber_a1b2c3d4
print(message["data"]["status"])   # 'queued'

// The Go SDK has no typed SendViber method — reach the channel endpoint
// through the client.Request escape hatch (raw JSON out).
var message map[string]any
err := client.Request(
    context.Background(),
    "POST",
    "/messages/viber",
    nil,
    map[string]any{
        "to":   "+14155552671",
        "from": "OrbitDemo",
        "body": "Your appointment is confirmed for March 10 at 2:00 PM.",
    },
    &message,
    "",
)
if err != nil {
    panic(err)
}

fmt.Println(message["data"].(map[string]any)["id"])      // msg_viber_a1b2c3d4
fmt.Println(message["data"].(map[string]any)["status"])  // 'queued'

{
  "data": {
    "id": "msg_viber_a1b2c3d4",
    "status": "queued",
    "channel": "viber"
  },
  "meta": {
    "request_id": "req_xK9f3m2h",
    "timestamp": "2026-03-08T00:00:00Z"
  }
}

status: "queued" means the message is persisted and accepted, not yet delivered — the terminal delivered / failed state arrives later via the delivery-status webhook (and in Tier 2, inbound replies arrive at your webhook too). Poll GET /api/v1/messages/{id} if you can’t consume webhooks. 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. The Tier 1 request body is deliberately small:

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

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:

Email 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.
Devotel submits the Rakuten Viber sender registration on your behalf and shepherds the application through Rakuten’s review.
Once Rakuten approves the sender, Devotel attaches the issued auth token to your tenant configuration via the admin panel.
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

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"
  }'

{
  "data": {
    "id": "msg_viber_e5f6g7h8",
    "status": "queued",
    "channel": "viber"
  },
  "meta": {
    "request_id": "req_xK9f3m2h",
    "timestamp": "2026-03-08T00:00:00Z"
  }
}

The envelope is the same in both tiers — the routes share the same POST /api/v1/messages/viber endpoint and the same row shape (id, status, channel). Upgrade from Tier 1 to Tier 2 without changing your client code. 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` object — the card/carousel layout (`ButtonsGroupColumns`, `ButtonsGroupRows`, `Buttons`). When present, the message is sent as a `rich_media` message.
`metadata.keyboard`	A Viber `keyboard` 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 accepts is supported.

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\"}]}"
    }
  }'

{
  "data": {
    "id": "msg_viber_i9j0k1l2",
    "status": "queued",
    "channel": "viber"
  },
  "meta": {
    "request_id": "req_xK9f3m2h",
    "timestamp": "2026-03-08T00:00:00Z"
  }
}

To attach a reply keyboard instead of (or in addition to) a rich card, set metadata.keyboard to a JSON-encoded Viber keyboard object:

{
  "keyboard": "{\"Type\":\"keyboard\",\"Buttons\":[{\"ActionType\":\"reply\",\"ActionBody\":\"yes\",\"Text\":\"Yes\"},{\"ActionType\":\"reply\",\"ActionBody\":\"no\",\"Text\":\"No\"}]}"
}

If Viber rejects the structure — e.g. a malformed rich_media type or a keyboard object failing a business-rule check — the send returns HTTP 502 with the machine-readable code MESSAGE_SEND_FAILED:

{
  "error": {
    "code": "MESSAGE_SEND_FAILED",
    "message": "Viber delivery temporarily unavailable. Please try again or use another channel.",
    "status": 502,
    "details": {
      "provider": "viber",
      "provider_status": 502,
      "viberStatus": 4
    }
  },
  "meta": {
    "request_id": "req_xK9f3m2h",
    "timestamp": "2026-03-08T00:00:00Z"
  }
}

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 status code in details.viberStatus; check your payload against the linked Viber reference.

Inbound webhook semantics (Tier 2)

When a Viber user replies to your Tier 2 branded sender, Viber POSTs the event to the platform’s inbound route POST /api/v1/webhooks/inbound/viber and Orbit relays it to the webhook URL you set under Settings → Webhooks on the standard inbound event. Replies arrive with channel: "viber" and direction: "inbound". Tier 1 is outbound-only — no inbound replies and no inbound webhooks in that tier. The from ↔ to mapping is symmetric with the outbound send: from is the replying Viber user’s phone number, to is your branded sender. To answer a reply, send POST /api/v1/messages/viber with the inbound from value as the outbound to and your branded sender as from.

Inbound (P2A) replies only reach accounts with Viber chatbot capabilities. Standard Viber Business Message accounts are outbound-only (A2P) — Viber does not forward user replies to them. This is a Viber platform limitation, not an Orbit limitation. Ask your Devotel account manager to confirm chatbot capability during sender registration if your flow depends on replies.

A typical inbound payload:

{
  "id": "evt_vib9c7d2e1",
  "type": "message.received",
  "created_at": "2026-09-08T10:12:44Z",
  "data": {
    "message_id": "msg_viber_rx42",
    "channel": "viber",
    "direction": "inbound",
    "from": "+14155552671",
    "to": "OrbitBrand",
    "body": "Do you deliver on weekends?"
  }
}

Viber DLR callbacks (delivered, seen, failed) land on a separate platform route that the sender registration wires automatically — you only ever configure your own URL under Settings → Webhooks.

Onboarding & provisioning

Tier 1 — sender-ID allow-list (self-serve on first send)

Tier 1 is auto-provisioned: no per-tenant Viber Business signup and no platform onboarding step — every paying tenant is wired into the shared SMPP termination route the moment their account is active, and the first send works out of the box. The only per-tenant artifact is your alphanumeric sender ID (up to 11 characters, e.g. OrbitDemo). Sender IDs must be allow-listed by Devotel before first use:

Pick your sender ID and email support@devotel.io (or your Devotel account manager) with your organization ID and the ID you want allow-listed.
Devotel registers the ID with the upstream Viber aggregator. Once allow-listed, the ID participates in SMPP sender resolution for every send.
There is no separate Viber status page — check general channel configuration under Settings → Channels. An ID sent before allow-listing is rejected by the aggregator and surfaces as a failed delivery status on the message and on your status webhook.

Tier 2 — Rakuten Viber Business registration

Tier 2 requires Rakuten Viber to approve a branded Business sender — Orbit cannot register on your behalf silently, but your Devotel account manager coordinates the whole application:

Send your account manager the registration artifacts Rakuten requires: the business display name, the sender profile logo (used as your sender avatar), the destination markets you plan to message, and — when Rakuten’s review asks for verification — trademark or domain ownership proof plus sample message content.
Devotel submits the Rakuten Viber sender registration and shepherds it through Rakuten’s manual review. Expect 5-10 business days end to end.
Rakuten returns your issued Viber Business auth token, an approved sender name, and an approved avatar. Devotel stores them encrypted under your organization’s settings.channels.viber .businessAccount and attaches the token to your tenant through the admin panel.
From that moment the same POST /api/v1/messages/viber endpoint routes your sends through the Viber Business HTTP API instead of SMPP — no code change required. Sends made before the token lands keep routing through Tier 1, so OTP and other time-critical traffic is never blocked on the application.

Plan campaign launches around the queue: Rakuten gates every branded Business sender behind a manual approval queue and there is no expedited path. Start Tier 1 traffic first, then flip to Tier 2 the day the token is attached.

Rate limits & throughput

Tier	Cap	Behaviour when the pool saturates
Tier 1	Rides your tenant’s `POST /messages/viber` rate-limit row — 50 requests/minute per organization (default; raiseable by your admin per tenant).	A burst over the cap returns `429` with a `Retry-After` header. Nothing is queued server-side — back off and retry, or stage high-volume sends through the campaigns API. The cap is per tenant and per channel, so one tenant can never starve another.
Tier 2	Bounded by Rakuten’s API quota on your Viber Business auth token (per-sender). The platform’s `/messages/viber` row above still applies on the request envelope.	When Rakuten’s quota is saturated, the Viber Business HTTP API rejects the call — Orbit retries transient `429`/`5xx` responses with backoff, and if the quota still won’t clear the send fails terminally as `MESSAGE_SEND_FAILED` (502) or lands on the configured cross-channel fallback chain you set up (e.g. Viber → SMS).

Keep sustained throughput below the lease your Rakuten quota grants and split campaigns across the campaigns API so one-off bursts never collide with transactional traffic.

Common errors

Code	HTTP	Tier	Cause	Fix
`INVALID_RECIPIENT`	422	Both	Empty `to`, or a `+`-prefixed `to` (Tier 2) that is not a valid E.164 number.	Pass a non-empty E.164 recipient (Tier 1) or a valid E.164 number / Viber user id (Tier 2).
`VALIDATION_ERROR`	422	Both	Schema rejection on the request body (missing `to` / `body`, invalid `metadata` shape).	Correct the body against the request table above and retry.
`CHANNEL_NOT_CONFIGURED`	503	Both	The platform Tier 1 SMPP route is not registered and no Tier 2 Business token is stored for your organization.	Complete Tier 1 allow-listing or wait for the Tier 2 token to be attached; do not retry blind.
`RATE_LIMITED`	429	Both	Over the tenant’s `/messages/viber` pool (50/min default) on a burst.	Honour the `Retry-After` header; stage bulk sends through the campaigns API.
`MESSAGE_SEND_FAILED`	502	Tier 2	Rakuten’s Business HTTP API rejected the send — malformed `rich_media` / `keyboard` payload, quota saturation, or a provider-side failure. The rejected provider status is returned in `details.viberStatus`.	Check `details.viberStatus` against the Viber reference, fix the payload or wait out the quota window, then retry.
`not-registered` / not-on-Viber	— (delivery status)	Both	The recipient is not reachable on Viber — no Viber installation on that device, or the sender ID not allow-listed in the destination market. This arrives as a `failed` delivery-status webhook, never as a synchronous error — the API itself accepted the send.	Trigger the configured cross-channel fallback (Viber → SMS) or drop the recipient. See Delivery & fallback below.

Pricing

Tier 1 (SMPP) bills on delivered at your plan’s per-message Viber rate — submit-time and rejected messages are free. Tier 2 rides the own-token BYO policy: Rakuten bills your Business account directly, and Devotel attaches the issued token at the platform rate for BYO tokens (see the pricing page for your plan’s per-channel rows). Your plan’s /messages/viber rate-limit row applies to both tiers.

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:

Open Settings → Channels → Cross-Channel Fallback.
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).
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 reference for the full envelope.

Termination plane

The two tiers above differ in how they terminate, not just what they allow: Tier 1 egresses as SMPP through the dedicated orbit-vib account on Devotel’s SMPP hub, while Tier 2 posts to the Rakuten Viber Business HTTP API with your per-organization token — and the retired __VIBER__: content-prefix mechanism predates both. The Viber termination model concept page documents the termination-plane split, what your tier setting flips at send time, and how delivery receipts and sender registration differ between the two paths.

Getting Started

Channels

Channels (Voice)

AI Agents

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Tutorials

Changelog

Send Viber business and SMPP-tier messages

Viber

Tier 1 — One-way Basic Messaging

How it works

Send a Tier 1 message

Tier 2 — Two-way Advanced Messaging

How to enable

Send a Tier 2 rich message

Tier 2 media

Tier 2 rich cards, carousels, and keyboards

Inbound webhook semantics (Tier 2)

Onboarding & provisioning

Tier 1 — sender-ID allow-list (self-serve on first send)

Tier 2 — Rakuten Viber Business registration

Rate limits & throughput

Common errors

Pricing

Delivery & fallback (Tier 1 and Tier 2)

Configure Viber → SMS fallback

What triggers the fallback

Termination plane

​Viber

​Tier 1 — One-way Basic Messaging

​How it works

​Send a Tier 1 message

​Tier 2 — Two-way Advanced Messaging

​How to enable

​Send a Tier 2 rich message

​Tier 2 media

​Tier 2 rich cards, carousels, and keyboards

​Inbound webhook semantics (Tier 2)

​Onboarding & provisioning

​Tier 1 — sender-ID allow-list (self-serve on first send)

​Tier 2 — Rakuten Viber Business registration

​Rate limits & throughput

​Common errors

​Pricing

​Delivery & fallback (Tier 1 and Tier 2)

​Configure Viber → SMS fallback

​What triggers the fallback

​Termination plane

Viber

Tier 1 — One-way Basic Messaging

How it works

Send a Tier 1 message

Tier 2 — Two-way Advanced Messaging

How to enable

Send a Tier 2 rich message

Tier 2 media

Tier 2 rich cards, carousels, and keyboards

Inbound webhook semantics (Tier 2)

Onboarding & provisioning

Tier 1 — sender-ID allow-list (self-serve on first send)

Tier 2 — Rakuten Viber Business registration

Rate limits & throughput

Common errors

Pricing

Delivery & fallback (Tier 1 and Tier 2)

Configure Viber → SMS fallback

What triggers the fallback

Termination plane