Skip to main content

Sending VBM Messages via API

Send approved Viber Business Messages (VBM) templates through the Octopods API, authenticated with your VBM channel API key.

Written by Tarek Khalil

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.

  • Appointment reminders from a scheduling system.

  • Transactional alerts that need Viber’s rich image/button format.

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:

Endpoint

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

POST https://api.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 — an object mapping {{N}} placeholders to their values. Keys are the placeholder numbers as strings ("1", "2", …).

Optional parameters

  • header_image_url — if the template has a header image, include the public URL of the image for this send. Must match the aspect ratio Viber approved during template review.

  • open_intercom_conversation — true to open a new conversation in your Intercom inbox. (For HubSpot workspaces, the conversation is created in HubSpot regardless.)

  • intercom_teammate_id — the Intercom teammate who should appear as the sender of the conversation.

Example request

curl -X POST \
  "https://api.octopods.io/api/v1/vbm/templates/delivery_update_v2/messages" \
  -H "X-Octopods-Auth: <your-channel-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_phone": "+447700900123",
    "message_variables": {
      "1": "Jane",
      "2": "ORD-9876",
      "3": "25 April"
    },
    "header_image_url": "https://example.com/images/delivery-map-ORD-9876.png"
  }'

The template body Hi {{1}}, your parcel {{2}} is out for delivery on {{3}}. renders as:

Hi Jane, your parcel ORD-9876 is out for delivery on 25 April.

Response

On success, Octopods returns details about the queued send:

{
  "request_id": "req_01HT5Q...",
  "message_id": "msg_01HT5Q...",
  "message_status_url": "https://api.octopods.io/api/v1/vbm/messages/msg_01HT5Q...",
  "phone_number": "+447700900123"
}

Use the message_status_url to poll for delivery state.

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

{
  "error_code": 4,
  "error": "Template 'delivery_update_v2' is still pending review."
}

Delivery statuses

  • Sent — Octopods has handed the message to Viber.

  • Delivered — Viber confirmed delivery to the recipient’s device.

  • Read — the recipient opened the message.

  • Failed — delivery failed. The conversation shows the reason (for example, recipient not on Viber in the supported country).

Common errors

  • Template not approved — the VBM template hasn’t been approved yet or has been deactivated.

  • Invalid variables — a placeholder is missing a value, or a value contains characters Viber rejects.

  • Recipient outside territory — the recipient’s phone number country isn’t in your channel’s approved territories. Update the channel settings or pick a different recipient.

  • Rate limit exceeded — you’ve exceeded your channel’s sending rate. Space out sends.

  • Unauthorized — the X-Octopods-Auth header is missing, revoked, or from a different channel.

For the full numeric error-code table, see API Error Reference.

Best practices

  • Honor frequency caps. Avoid sending multiple templates to the same recipient in a short time window.

  • Use the right template category. Transactional templates should not contain promotional content and vice versa — reviewers will reject repeat violations.

  • Include a plain fallback in the template body even when using an image header, so the message is readable if the header fails to load.

What’s next

Did this answer your question?