Viber transactional templates

July 1 2026 — mandatory

From July 1 2026, every transactional Viber Business Message — local and international — must be sent using a pre-approved template. Transactional content sent outside an approved template may be billed as promotional and can be rejected.

1. What is changing, in one paragraph

Rakuten Viber is moving transactional Business Messages to a pre-approved template model. You submit a template with fixed text and named placeholders (for example {{pin}}, {{order_id}}). After Viber approves it, each send references that template’s ID, language, and the values for each placeholder. The result is more consistent formatting, clearer separation from promotional traffic, and less room for spoofing.

Templates are tied to your Viber sender. Routee supports up to 2,000 transactional templates per sender. Templates cannot be edited after submission — you delete and create a new template (and use the new template ID) if wording must change.

2. Why Viber is doing this

3. Transactional vs promotional — the line that matters

Transactional templates are for non-commercial notifications and OTP. They must not promote products or offers.

Promotional content is not allowed in transactional templates. Discounts, loyalty pushes, “buy now” calls to action, cross-sells, or wording whose main purpose is to sell or market belongs in Viber’s promotional formats — not in transactional templates. Misclassified content may be rejected or re-rated.

Transactional examples (typically allowed)

• Order or booking confirmations and receipts
• Shipping and delivery updates
• Appointment, reservation, or trip reminders
• Security alerts (new sign-in, password change or expiry)
• Payment or transfer confirmations
• Service notices (outage, maintenance)
• Subscription renewal reminders (informational, not upsell)
• One-time passwords (OTP) and verification codes

Examples that are not transactional templates

• “20% off your next order — shop now”
• Loyalty or points promotions
• Newsletter-style launches, carousels, broad marketing campaigns

Pricing note: Transactional templates are charged at transactional rates where the traffic qualifies. Off-template transactional sending may be treated as promotional under Viber’s rules from July 2026 onward.

4. The template lifecycle

flowchart LR
  Draft[Draft template]
  Submit[Submit for moderation]
  Pending[Pending up to about 24h]
  Approved[Approved ready to send]
  Declined[Declined with reason]
  Send[Send via Routee API]
  Dispute[Discuss with Routee]
  Replace[Delete and create new]

  Draft --> Submit --> Pending
  Pending --> Approved
  Pending --> Declined
  Approved --> Send
  Approved --> Replace
  Declined --> Dispute
  Declined --> Replace

Timing: Moderation often completes sooner, but you should plan for up to about 24 hours before go-live.

No in-place edits: Any change to text or variables requires delete → new template → new template ID.

5. What a template looks like

Every template includes:

1. Locale — ISO 639-1 code (e.g. en, fr). One locale per template; use a separate template per language.
2. Category — OTP or Transactional.
3. Text body — Static text with placeholders like {{name}}. Routee validates up to 875 characters; the body must start and end with real text; two placeholders cannot sit back-to-back with nothing between them.
4. Variables — Up to 5 placeholders. Names use English letters and underscores, up to 50 characters, type TEXT, with sample values up to 100 characters for moderation.

Example — delivery

Hi {{name}},
your order has shipped!
It will be delivered on Monday between {{time_start}} and {{time_end}}.

Example — OTP

Your account verification code is {{pin}}.

Validation summary (what Routee enforces when you create templates)

6. Special rules for OTP templates

OTP templates must include a {{pin}} placeholder in the template text.

At send time, your request must supply a non-empty pin (and any other placeholders your template defines). OTP sends use the same POST /viber/transactional/messages endpoint as other transactional templates — see §7 and the API reference.

Approved OTP templates may get device-side behaviour such as “copy code” actions, depending on Viber’s app.

7. Sending an approved template

You integrate with Routee — not directly with Viber

Use https://connect.routee.net and a Routee OAuth 2.0 Bearer token. Routee is the Viber Business Messages partner; you do not call Viber’s partner-only APIs with your Routee credentials.

Recommended API surface (current integrations)

• Templates: GET, POST, PATCH, DELETE under /viber/transactional/templates (see API reference). Create requires query parameter senderInfoTrackingId.
• Send (all template categories): POST /viber/transactional/messages only — body uses templateId, templateLang, templateParams, optional deliveryScope (PRIMARY_DEVICE or ALL_DEVICES), and optional seq. OTP-category templates must include pin in templateParams. There is no greenfield POST /viber/transactional/otp. Legacy POST /viber/otp remains for older integrations.

Routee send-time validation: Before your message is queued, Routee checks templateLang and templateParams against the approved template. Invalid values (missing pin, wrong language, URLs, values like test.pdf, or length over 25 characters) return HTTP 400 with code 400019029 and a validationIssues array — see API reference — Send-time validation.

Listing templates: GET /viber/transactional/templates can return templates for all eligible senders on your account if you omit senderInfoTrackingId; pass that query parameter to filter to one sender.

Updating only the moderation webhook URL: PATCH /viber/transactional/templates/{templateId} changes Routee’s stored callbackUrl for template status events. The JSON body must include callbackUrl (or the alternate name lifecycleCallbackUrl). Use "callbackUrl": null to clear the URL. An empty body {} returns HTTP 400 on greenfield paths — this call is intentionally strict so webhook changes are always explicit. Legacy /viber/bm/transactional-templates/... PATCH may accept an empty body as a no-op.

7.1 Example — transactional message

POST https://connect.routee.net/viber/transactional/messages
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "senderInfoTrackingId": "your-viber-sender-tracking-id",
  "to": "+972500000000",
  "ttl": 86400,
  "templateId": "2c017482-2f44-41d6-adad-2d6af725fdbe",
  "templateLang": "en",
  "templateParams": {
    "name": "John",
    "time_start": "10:00",
    "time_end": "14:00"
  },
  "deliveryScope": "PRIMARY_DEVICE",
  "sessionMessage": false
}

7.2 Example — OTP-category template

Use the same URL as non-OTP transactional sends. Only the template (category and placeholders) and templateParams differ. There is no separate greenfield OTP send path.

POST https://connect.routee.net/viber/transactional/messages
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "senderInfoTrackingId": "your-viber-sender-tracking-id",
  "to": "+972500000000",
  "templateId": "APPROVED_OTP_TEMPLATE_UUID",
  "templateLang": "en",
  "templateParams": {
    "pin": "482910",
    "minutes": "5"
  },
  "deliveryScope": "PRIMARY_DEVICE",
  "ttl": 86400
}

templateParams must include pin. seq is optional; if you omit it, Routee assigns a value and echoes it in the response, tracking GET, and delivery callbacks. Optional callbackUrl receives delivery status callbacks — see Tracking and delivery callbacks (distinct from the template moderation webhook in §8.1).

7.3 Send-time errors

Routee validation (before the message is queued)

When templateLang or templateParams do not match the approved template, Routee returns HTTP 400 with:

• code: 400019029
• validationIssues: list of { code, message } (e.g. PARAM_CONTAINS_FILE_EXTENSION, OTP_PIN_REQUIRED, TEMPLATE_LANG_MISMATCH)

Fix the request and retry — the message was not accepted for delivery. See the API reference.

Viber partner codes (after Routee accepts the send)

Viber may return numeric codes when a send fails at the provider. Routee forwards partner information when applicable. Codes can change — treat this table as guidance and confirm with the latest documentation your Routee contact provides.

8. How status updates reach you

sequenceDiagram
  participant Viber as Rakuten Viber
  participant Routee as Routee
  participant UI as Routee portal
  participant You as Your systems

  Viber->>Routee: Status webhook
  Routee->>UI: Pending / Approved / Declined
  Routee->>You: Optional email
  Routee-->>You: Optional HTTPS callback

Raw vendor event types (for background only — rely on Routee’s normalized status in the portal and callbacks):

8.1 HTTPS lifecycle callback (callbackUrl on the template)

If you set callbackUrl when creating or updating a template, Routee POSTs JSON to that HTTPS URL when moderation status changes. The payload focuses on the template itself — do not rely on undocumented extra fields.

Example — pending

{
  "templateId": "9c605a49-c6c4-4295-a569-509d5648f0bf",
  "templateStatus": "PENDING_MODERATION",
  "templateBody": "Hello {{name}}, your code is ready.",
  "variables": ["name"]
}

Example — rejected

{
  "templateId": "9c605a49-c6c4-4295-a569-509d5648f0bf",
  "templateStatus": "REJECTED",
  "rejectionReason": "Template violates content policy."
}

This lifecycle callback is not the same as a per-message delivery callbackUrl on a send request. Delivery callbacks carry trackingId, status, and (for template sends) messageKind / transactionalTemplate — documented in Tracking and delivery callbacks. Use different URLs unless you merge them intentionally behind your own gateway.

8.2 Email notifications (optional)

When you set moderationNotifyEmail on template create, Routee can email that address when moderation status changes (approved / rejected). If you omit it, Routee may email addresses from your account balance notification settings when an account id is available on the lifecycle event.

Email content includes:

9. Where this appears in your Routee account

In the Routee management experience (where enabled): Viber → Transactional templates.

You can usually:

• View templates per sender, with status, category, language, and last update.
• Delete templates you no longer need (old IDs stop working once deleted).
• Refresh to see updates shortly after moderation completes or after a webhook fires.

For first-time setup, policy disputes, or sender configuration, use your Routee account contact unless your agreement includes full self-service template creation in the product.

Partner portal: The Viber Business Messages partner environment is operated by Routee on behalf of customers. You do not receive separate Viber “partner login” credentials for that path.

10. Region-specific notice — UA / RU / BY

Customers in Ukraine, Russia, and Belarus may already use regional transactional-template processes. Viber’s materials describe convergence toward one model. There is no guaranteed automatic migration of every existing template — some may need to be re-submitted under the new rules.

Confirm dates and steps with your Routee representative and official Viber announcements.

11. Onboarding checklist

• List all transactional use cases (OTP, delivery, bookings, alerts, security, …).
• One template per language per message variant.
• For each template: static text, ≤ 5 variables, clear names, TEXT, realistic examples.
• Remove promotional wording from transactional copy.
• Work with Routee to submit templates and collect approved UUIDs.
• Store templateId and templateLang in your configuration.
• Use GET /viber/transactional/templates to verify status (optionally filter by senderInfoTrackingId).
• If you use lifecycle webhooks, implement PATCH on /viber/transactional/templates/{id} with an explicit callbackUrl body (empty {} is rejected).
• Implement POST /viber/transactional/messages with templateId, templateLang, templateParams, optional deliveryScope, and optional seq. For OTP-category templates, always send pin in templateParams.
• Handle HTTP 400 / 400019029 / validationIssues from Routee send-time validation.
• Validate at send time: parameter length, no URLs, no file-extension-like values, locale match.
• If you operate in UA/RU/BY, confirm timelines with Routee.

12. FAQ

Will my transactional pricing change?
Qualified transactional template traffic stays on transactional pricing. Off-template transactional may be priced or handled as promotional after July 2026 per Viber.

Can templates be in any language?
Use one ISO 639-1 locale per template; add more languages with more templates.

Can I edit after submit?
No — delete and create a new template (new ID).

My template was declined — what now?
Discuss with Routee or submit revised wording.

How long does moderation take?
Often within hours; plan for up to ~24h.

Why does OTP fail despite an approved template?
Typical causes: missing pin, wrong placeholder keys, wrong language, file-extension-like param values (test.pdf), or using a non-OTP template id — compare with §7.2 and the API reference. Check for 400019029 in the response before assuming a Viber network error.

Is there POST /viber/transactional/otp?
No. Use POST /viber/transactional/messages for OTP-category templates. Legacy POST /viber/otp remains for older integrations only.

Images, buttons, carousels?
Not in the text transactional template model here; rich layouts use other Viber message types.

How many templates can I have?
Up to 2000 per Viber sender on Routee.

Self-service submission?
Depends on your Routee product; the portal may allow create/list where enabled.

How do I get programmatic status events?
Configure callbackUrl on the template for moderation (§8.1). For message delivery, set callbackUrl on the send request or poll GET /viber/tracking/{trackingId} — see Tracking and delivery callbacks.

What is seq?
An optional number you send (or Routee assigns) to correlate a message with your systems. It is echoed in the send response, tracking GET, and delivery callbacks under transactionalTemplate.seq.

13. Glossary

Need help?

• Templates, disputes, sender setup — your Routee account or support channel.
• Partner guideline PDFs — ask Routee for the current BM transactional guidelines and API summaries.
• Viber partner channels — reserved for partners; customer questions should go through Routee.