With our VBM integration, you can predefined message templates to send to your customer via API or open new conversation proactively.

Template message can be:

Text only
Text with buttons
Text & images with buttons

Through Octopods, you can use our Message Templates API to programmatically send Message Templates to your Users directly.

Authentication

Once your Viber Business approved and provisioned, we generate an API Key for your account to be used.

You can retrieve your API Key directly from our Octopods App by selecting your VBM channel and copying the key.

You need to use your API Key by adding a header as the following:

X-Octopods-Auth: YOUR_API_KEY

API Endpoints

Retrieve Message Template(s)

HTTP GET

https://app.octopods.io/api/v1/vbm/templates

You can filter the templates retrieved by this endpoint using any of the query parameters below

Query Parameters

Parameter	Possible Values	Description	Required
active	["true", "false"]	Filters the templates by their active status	No
lang	ISO 639-1 language code e.g. ["en", "pt", "ar", ...]	Filters the templates by the language	No

Request (in cURL)

curl --location --request GET 'https://app.octopods.io/api/v1/vbm/templates/' \
--header 'X-Octopods-Auth: YOUR_API_KEY' \
--header 'Content-Type: application/json'

Response (in JSON)

[
    {
        "created_at": "2025-11-05T10:40:48.000Z",
        "template_id": 1,
        "template_name": "vbm_new_template",
        "template_body": {
            "type": "BODY",
            "text": "Hello world."
        },
        "template_components": [
            {
                "type": "BODY",
                "text": "Hello world."
            }
        ],
        "account_phone_number": "<business_phone_number>"
    }
]

HTTP GET

https://app.octopods.io/api/v1/vbm/templates/:TEMPLATE_ID

Request (in cURL)

curl --location --request GET 'https://app.octopods.io/api/v1/vbm/templates/1' \
--header 'X-Octopods-Auth: YOUR_API_KEY' \
--header 'Content-Type: application/json'

Send a Message Template

Templates can be created with variables marked {{1}} and/or images. When sending a message using such a template, make sure you include the variable value and image URL(s) in the payload. More details below.

HTTP POST

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

Payload must be in JSON.

Request (in cURL)

curl --location --request POST 'https://app.octopods.io/api/v1/vbm/templates/019S7WT/messages' \--header 'X-Octopods-Auth: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data-raw '{
  "destination_phone": "+353838000000",
  "message_variables": {
    "body": ["variable1", "variable2"]
  },
  "header_image_url": "url_to_image",
  "open_intercom_conversation": false,
  "intercom_teammate_id": "5173352"
}'

Parameter	Possible Values	Description	Required
destination_phone	any e164 valid phone	the destination phone to send a message template to	Yes
message_variables*	object	has variable values for body macros	Yes, if your message template has variables
message_variables.body	array	if your message template's body has variables like {{1}} and {{2}} , you can specify your variables here	Yes, if your message template has body variables
open_intercom_conversation	true or false	if you want Octopods to create an Intercom conversation in your Inbox	No
header_image_url	string	URL to a media file, used for templates with images	Yes, if your template has an image
intercom_teammate_id**	string	Intercom teammate ID assigned to this message.	No

*The message_variables object only supports body variables for now. This might change later.

**In case this proactive message created a new conversation with the end-user, we will start & assign this teammate-initiated conversation to the admin ID equal to the specified intercom_teammate_id. If blank, we resolve to the workspace admin.

Response (Created 201)

201 Created

{
  "message_id": 42,
  "phone_number": "<destination_phone_number",
  "request_id": "d8c0d247-cfc9-48d7-868d-e6afdadb44dc",
}

Errors

Example:

{

  "request_id": "d8c0d247-cfc9-48d7-868d-e6afdadb44dc",
  "error_code": 4,
  "error": "Your Message Template has 2 variables which you must supply."

}

Phone Number Format

Your phone number should be in the E164 format in order to avoid receiving an Invalid Phone number error.

Rate Limiting

API Rate Limits are implemented to ensure high performance and continuous availability for Octopods services. These rate limits are in place to safeguard our databases from API traffic spikes and prevent hitting our providers’ rate limits.

Each channel connection would have a default rate limit of 330 requests per minute evenly distributed into 10 seconds sections. This means that each channel connection is limited to 55 requests per 10 seconds.

When the number of API requests sent from a single channel connection exceeds the mentioned rate limit, this channel connection will be put on a cool-down period of 5 minutes. Any requests beyond the rate limit or within the cool-down period will receive a response of '429 Too Many Requests' with a message indicating the time at which the cool-down period will end.