Transactional template messages

Transactional template messages are the required format for all transactional Viber messaging from July 1, 2026. They replace both the legacy OTP template messages and the legacy transactional message types (plain text, file, and list messages sent at the transactional rate).

❗️

Important

From July 1, 2026, all transactional notifications must use the transactional template format. Please reach out to your account manager. Contact your account manager to get set up or migrate from your existing Regex templates.

Overview

A Transactional Template is a standardized, pre-approved message format for notifications such as order confirmations, shipping updates, and OTP codes. Each template consists of:

• Fixed text: Static content that remains constant across all sends.
• Placeholders (variables): Dynamic fields (e.g. {{order_id}} or {{pin}}) that are replaced with recipient-specific data at the time of sending.

Templates must be approved by Viber before use. Once approved, you send messages by referencing the template ID and supplying the variable values.

There are two template categories:

Creating templates

Template creation and management is handled by us on your behalf. To get your templates set up, contact your account manager. They will work with you to define your template content, template type (transactional or OTP), submit it for Viber moderation, and confirm approval. Template moderation by Viber takes up to 24 hours.

Sending transactional template messages

Once a template is approved, you send it via the CM Business Messaging API using the same endpoint as other Viber message types, with new fields in richContent.

Rich content fields

Validation rules

Before a message is sent, the following validation is applied:

• The templateId must exist and be associated with your sender account.
• The template must have Approved status. Messages referencing a Pending or Declined template will not be sent.
• The templateParams object must exactly match the variables defined in the template. Missing or extra parameters will result in a validation error.

OTP template type: additional requirements

For templates with category OTP, the templateParams must include a value for the {{pin}} placeholder. If the pin value is missing or null, the message will be rejected even if the template itself is valid and approved.

OTP messages are displayed to the recipient with a dedicated UI: a generic image, the full message text including the actual PIN, and a Copy button that copies the PIN to the recipient's clipboard.

Request example OTP template type

{
  "messages": {
    "msg": [
      {
        "from": "Your Sender",
        "to": [
          {
            "number": "Phone number recipient"
          }
        ],
        "allowedChannels": [
          "Viber"
        ],
        "body": {
          "type": "auto",
          "content": "SMS fallback text"
        },
        "richContent": {
          "conversation": [
            {
              "template": {
                "viber": {
                  "templateId": "2c017482-2f44-41d6-adad-2d6af725fdbr",
                  "templateParams": {
                    "user_name": "John",
                    "pin": "98765"
                  },
                  "templateLang": "en"
                }
              }
            }
          ]
        }
      }
    ]
  }
}

Request example transactional template type

{
  "messages": {
    "msg": [
      {
        "from": "Your Sender",
        "to": [
          {
            "number": "Phone number recipient"
          }
        ],
        "allowedChannels": [
          "Viber"
        ],
        "body": {
          "type": "auto",
          "content": "SMS fallback text"
        },
        "richContent": {
          "conversation": [
            {
              "template": {
                "viber": {
                  "templateId": "2c017482-2f44-41d6-adad-2d6af725fdbr",
                  "templateParams": {
                    "name": "John"
                  },
                  "templateLang": "en"
                }
              }
            }
          ]
        }
      }
    ]
  }
}