Viber transactional messaging — API reference

This guide is for developers building integrations on Routee. It describes the REST endpoints to create and manage Rakuten Viber Business Messages (BM) transactional templates and to send approved templates (including OTP).

For why templates are required, content and OTP rules, moderation timelines, and FAQs, see the customer guide.

Base URL and authentication

Your access token must belong to a Routee account that is allowed to use Viber. Routee resolves which account and which senders you may use from the token and from the parameters you pass (for example senderInfoTrackingId).

Permissions and errors

Your Routee API credentials (application / OAuth setup) must include:

• Viber-related OAuth scopes — typically viber or all (as configured for your integration).
• Rights to manage templates — create, read, and delete transactional templates for your Viber sender(s).
• Rights to send — permission to send Viber messages for the same account.

If the token is missing, invalid, or not allowed to perform the operation, the API usually returns HTTP 403. If a resource (for example account or sender context) cannot be resolved, you may receive HTTP 404.

Quick start — typical flow

1. Authenticate — Obtain a valid Bearer token with Viber access.
2. Pick a sender — Use the Routee tracking id of your Viber sender (senderInfoTrackingId) when you create templates and when you send.
3. Create a template — POST /viber/transactional/templates?senderInfoTrackingId=… and wait until the template is approved in Routee (see the customer guide for moderation and optional notifications).
4. Send — Call POST /viber/transactional/messages for every approved template (transactional or OTP category). There is no separate greenfield /viber/transactional/otp. Use templateId, templateLang, templateParams, and optional deliveryScope. OTP-category templates must include pin in templateParams.
5. Optional webhooks — You may set a callbackUrl on the template for moderation status updates, and a callbackUrl on each send for delivery status. Those callbacks use different JSON payloads (see Moderation callback).

flowchart LR
  A[Create template] --> B[Wait until approved]
  B --> C[Send template message]
  C --> D[Optional delivery callback]

Request conventions

Transactional templates

All paths below are relative to the base URL, for example:

https://connect.routee.net/viber/transactional/templates

List, read, create, update webhook, delete

Create template — JSON body (POST)

Parameters (params items)

Locales (locales items)

Examples (varExample items)

Example body:

{
  "category": "Transactional",
  "params": [{ "name": "user_name", "type": "TEXT" }],
  "locales": [
    { "lang": "en", "template": "Hello {{user_name}}, your appointment is confirmed." }
  ],
  "varExample": [{ "name": "user_name", "example": "Alex" }]
}

Update moderation webhook only (PATCH)

This request only updates Routee settings for your template moderation webhook. It does not change the template text sent to Viber.

• Send callbackUrl with an HTTPS URL, or "callbackUrl": null to remove the stored URL.
• You may use the alternative property name lifecycleCallbackUrl instead of callbackUrl (same meaning).
• The body must include callbackUrl or lifecycleCallbackUrl as a key. An empty body {} or omitting both keys returns HTTP 400 on greenfield paths (/viber/transactional/templates/...). Legacy /viber/bm/transactional-templates/... PATCH remains backward compatible (empty body may no-op).

Send transactional template messages

Paths are under:

https://connect.routee.net/viber/transactional/

There is no greenfield POST /viber/transactional/otp. Legacy POST /viber/otp on Routee Connect remains for older integrations.

POST /viber/transactional/messages — request body

Example — non-OTP

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

{
  "senderInfoTrackingId": "your-viber-sender-tracking-id",
  "to": "+972500000000",
  "templateId": "YOUR-APPROVED-TEMPLATE-ID",
  "templateLang": "en",
  "templateParams": {
    "user_name": "Alex",
    "order_id": "4829"
  },
  "deliveryScope": "PRIMARY_DEVICE"
}

Example — OTP-category template

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

POST /viber/transactional/messages — response (success)

HTTP 200 means the message was accepted for processing, not that the handset has received it yet.

The JSON includes fields such as:

Other fields (label, sessionMessage, callbackUrl, ttl, etc.) may appear depending on your request and product behaviour.

Delivery status: tracking GET and callbackUrl

Poll GET /viber/tracking/{trackingId} or receive delivery callbacks on the optional callbackUrl from the send request.

Full field reference, examples, and backward-compatibility notes:
Tracking and delivery callbacks (for public Routee / readme.io documentation).

messageKind and transactionalTemplate (summary)

Template-based sends add a discriminator and a nested metadata block. Values depend on the send path and stored record type — see the tracking guide for full examples.

Shared transactional block

When the send used an approved BM template (POST /viber/transactional/messages, or legacy template fields on POST /viber / POST /viber/otp), responses include:

Legacy rich single and campaign messages omit messageKind and transactionalTemplate. Existing fields (message, body.text, campaignTrackingId, etc.) are unchanged.

Callback status shape (unchanged): status.name, status.updatedDate. Tracking GET uses status.status, status.date.

Template sends on callback: empty body is omitted (no "body": {}). Legacy single/campaign callbacks still include body when present.

Example delivery callback:

{
  "trackingId": "304177c4-2478-4c49-bcea-3b6cede1b064",
  "to": "+306973359331",
  "status": {
    "name": "DELIVERED",
    "updatedDate": "2026-05-20T05:45:13.606Z"
  },
  "messageKind": "transactional_template",
  "transactionalTemplate": {
    "templateId": "2c017482-2f44-41d6-adad-2d6af725fdbe",
    "templateLang": "en",
    "deliveryScope": "PRIMARY_DEVICE",
    "seq": 1747719911946
  }
}

Send-time validation (before queue)

Routee validates templateLang and templateParams against the approved template before the message is queued. Invalid requests fail immediately with HTTP 400 instead of failing later at Viber with status 39.

Error response shape

Example — file-extension-like parameter:

{
  "code": "400019029",
  "developerMessage": "Parameter document_name must not look like a file name or extension (e.g. test.pdf).",
  "validationIssues": [
    {
      "code": "PARAM_CONTAINS_FILE_EXTENSION",
      "message": "Parameter document_name must not look like a file name or extension (e.g. test.pdf)."
    }
  ]
}

Common validationIssues codes

These checks are in addition to auth (403), unknown template projection (404 / not approved), and Viber partner codes (7, 38, 39) after the send reaches the provider.

Moderation callback (callbackUrl on the template)

If you set callbackUrl when creating (or updating) a template, Routee will POST to that HTTPS URL when the template’s moderation status changes (for example pending → approved or rejected).

• Content-Type: application/json
• Payload — Routee sends a focused object, for example:

Do not depend on extra fields such as serviceId, eventId, or vendor-specific raw codes unless Routee documents them for your integration.

Important: This payload is not the same as delivery callbacks you configure on POST /viber/transactional/messages. Use separate URLs unless you deliberately route both types through your own gateway and distinguish them there.

Moderation email (internal AMQP → Notifications)

Routee also sends moderation lifecycle emails when moderationNotifyEmail is set (or via Profile notification settings). The internal VIBER_BM_TRANSACTIONAL_TEMPLATE_LIFECYCLE AMQP payload (api → notifications) includes:

templateName is derived from the stored template body snapshot or the first locale returned by Viber Partners API. statusNote defaults to “Your template has been approved and is ready to send.” on approval when Viber sends no moderation text.

Common issues

Partner error codes can change; treat tables as indicative and verify against the latest Viber / Routee documentation you receive.

Postman and samples

Routee provides a Postman collection with ready-made calls for transactional templates and sends (collection name along the lines of Routee Viber BM Transactional). Use the copy supplied in your Routee developer / onboarding materials, or ask your Routee contact for the latest export.