Endpoint

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

The template’s ID is part of the URL path — not a body field. Find it on the template’s detail page in Octopods or via the list templates endpoint.

Only a template that is Approved and active can be sent through this endpoint.

Authentication

Include your Channel API Key in the request header:

X-Octopods-Auth: YOUR_CHANNEL_API_KEY

The key must belong to the Viber channel connection the template was registered against.

See API Key Authentication for how to find this key.

Required parameters

Send the request body as JSON with Content-Type: application/json.

destination_phone — the recipient’s phone number in E.164 format (for example, +15551234567). Numbers that fail validation are rejected with error code 5 (PHONE_INVALID).
message_variables — substitution values for the template’s variables. Structure depends on the variable style the template uses — see Variable structure below.

If the template has no variables, message_variables can be omitted.

Optional parameters

header_image_url — required only if the template’s header is an image header. This only applies to Promotional templates — Transactional and OTP templates never have an image header. Must be a publicly reachable URL returning a supported image type. Missing it when the header requires it returns error code 1 (ARGUMENT_MISSING); an invalid or unreachable URL returns error code 8 (INVALID_HEADER).
open_intercom_conversation — true to open a new conversation in your workspace inbox alongside the send, false (default) to send without opening a conversation. Accepts true, false, 1, 0, yes, no, on, off.
intercom_teammate_id — the ID of the teammate who should appear as the sender. Defaults to the workspace’s configured default sender.

Variable structure

The shape of message_variables depends on whether the template’s variables are numbered ({{1}}, {{2}}) or named ({{first_name}}).

Numbered variables — array shape

Classic {{1}}, {{2}}-style placeholders are fully supported, and are still the most common way templates are built. For a template whose variables are all numbered this way, message_variables accepts a flat array of values in placeholder order — either as the value of message_variables itself, or nested under a body key:

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

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

Both forms are equivalent — use whichever is more convenient for your integration. An array is only valid for a template whose variables are all numbered this way; sending an array for a template with any named variable returns error code 2 (TYPE_MISMATCH).

Named variables — object shape

A template with named variables — every Transactional and OTP template, and a Promotional template built with Named variables — uses variable names like {{first_name}} or {{order_id}} instead of positional placeholders. Send message_variables as an object with a body key, mapping each variable name to its value:

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

Every variable the template declares must be present with a non-blank value. For an OTP template, this must include a pin value — omitting it returns error code 9 (OTP_PIN_MISSING); leaving any other declared variable blank returns error code 10 (MISSING_VARIABLES).

Example request

POST https://app.octopods.io/api/v1/vbm/templates/60214/messages
X-Octopods-Auth: YOUR_CHANNEL_API_KEY
Content-Type: application/json{
  "destination_phone": "+15551234567",
  "message_variables": {
    "body": {
      "first_name": "Jane",
      "order_id": "ORD-9876"
    }
  }
}

Success response

On success the API returns HTTP 201 Created with no body. The send is enqueued for delivery to Viber.

To follow the send’s delivery, open the corresponding conversation in your workspace inbox.

Error response

On failure the API returns HTTP 400 Bad Request with a JSON body that includes the error code and a human-readable message:

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

Error codes

Code	Name	When it happens
1	`ARGUMENT_MISSING`	A required parameter (`destination_phone`, or `header_image_url` for an image-header template) was omitted.
2	`TYPE_MISMATCH`	`message_variables` was neither an object nor an array, or was an array for a template with any named variable.
3	`TEMPLATE_NOT_EXIST`	No approved, active template exists at `:template_id` for this channel.
5	`PHONE_INVALID`	`destination_phone` failed E.164 validation.
6	`DEPRECATED_API_KEY`	The API key has been rotated or revoked. Fetch the current key from Octopods.
7	`VBM_ERROR`	Viber rejected the send. The `error` field carries the reason.
8	`INVALID_HEADER`	`header_image_url` could not be fetched, was the wrong media type, or was blocked.
9	`OTP_PIN_MISSING`	An OTP template’s `message_variables` did not include a non-blank `pin` value.
10	`MISSING_VARIABLES`	One or more of the template’s declared variables was missing or blank.
11	`TEMPLATE_SENDING_DISABLED`	Template sending is temporarily disabled for this account. Contact Octopods support.

A full catalog of error codes across all endpoints is in the API Error Reference.

Send Viber Template Message