What this API is for

The Octopods VBM API sends approved template messages from your own backend or automation tools. Typical use cases:

Shipping and delivery notifications from your fulfillment system.
One-time passcodes (OTP) from your login or checkout flow.
Promotional broadcasts triggered from your own marketing tools.

Like WhatsApp, VBM only allows business-initiated outreach via approved templates. Freeform messaging works only once the customer starts a conversation; template sends are what this API is built for.

Before you start

You need:

A VBM channel in Active status. See Setting Up Viber Business Messages.
At least one Approved VBM template. See Managing VBM Templates.
The channel API key, visible on the VBM channel detail page.

Endpoint

The template ID goes in the URL path. Send a POST to:

POST https://app.octopods.io/api/v1/vbm/templates/{template_id}/messages

Replace {template_id} with the ID of the approved VBM template (from the template detail page).

Authenticate with your channel API key in the X-Octopods-Auth header:

X-Octopods-Auth: <your-channel-api-key>

Required parameters

Send the payload as JSON:

destination_phone — the recipient’s phone number in E.164 format (for example, +15551234567).
message_variables — the template’s variable values, if it has any. See Message variables below for the shape this takes.

Optional parameters

header_image_url — required only if the template has an image header (Promotional templates only — Transactional and OTP templates are always text-only). The public URL of the image for this send, matching the aspect ratio Viber approved during template review.
open_intercom_conversation — true to open a new conversation in your workspace inbox alongside the send. Accepts true/false, 1/0, yes/no, on/off. Defaults to false.
intercom_teammate_id — the teammate who should appear as the sender of the conversation, if one is opened.

Message variables

The shape of message_variables depends on what kind of variables the template uses.

Numbered variables — classic {{1}}, {{2}}-style placeholders are fully supported, and are still the most common way templates are built. Send a plain array of values in placeholder order, either as message_variables directly or nested under a body key — both are equivalent:

{
  "destination_phone": "+447700900123",
  "message_variables": ["Jane", "ORD-9876"]
}

{
  "destination_phone": "+447700900123",
  "message_variables": {
    "body": ["Jane", "ORD-9876"]
  }
}

Named variables — every Transactional and OTP template, and a Promotional template built with Named variables, uses variable names like {{first_name}} instead. Supply an object with a body key mapping each variable name to its value:

{
  "destination_phone": "+447700900123",
  "message_variables": {
    "body": {
      "first_name": "Jane",
      "order_id": "ORD-9876"
    }
  }
}

An OTP template’s variables must include pin.

If the template has no variables at all, omit message_variables.

Example request

curl -X POST \
  "https://app.octopods.io/api/v1/vbm/templates/60214/messages" \
  -H "X-Octopods-Auth: <your-channel-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_phone": "+447700900123",
    "message_variables": {
      "body": {
        "first_name": "Jane",
        "order_id": "ORD-9876"
      }
    }
  }'

The template body Hi {{first_name}}, your order {{order_id}} is out for delivery. renders as:

Hi Jane, your order ORD-9876 is out for delivery.

Response

On success, Octopods returns HTTP 201 Created with no body. The message has been accepted and handed to Viber for delivery. To follow the send’s delivery, open the corresponding conversation in your workspace inbox.

On failure, the response includes a numeric error code and a description:

{
  "request_id": "e23080fd-8b63-460e-83bd-cf5d2c1497b6",
  "error_code": 3,
  "error": "Message Template does not exist."
}

Common errors

Template not approved — the template hasn’t finished Viber’s review yet, was declined, or was deactivated.
Missing or blank variables — a variable the template declares wasn’t supplied, or an OTP template is missing pin.
Invalid destination phone — destination_phone isn’t a valid E.164 number.
Unauthorized or deprecated key — the X-Octopods-Auth header is missing, revoked, or belongs to a different channel.

For the full numeric error-code table, see Send VBM Template Message.

Best practices

Honor frequency caps. Avoid sending multiple templates to the same recipient in a short time window.
Use the right category. Transactional and OTP templates should stay strictly transactional — promotional content in these categories gets declined on review, and repeat violations put your account’s template access at risk.
Double-check example values before submitting a Transactional or OTP template. Once Viber accepts it, it can’t be edited — only copied into a new template.

What’s next

Managing VBM Templates
Send VBM Template Message
Setting Up Viber Business Messages
See the Broadcasts section for sending VBM templates to many recipients at once

Sending VBM Messages via API