Endpoint

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

{template_id} is the ID of the approved VBM template you want to send.
Authentication: X-Octopods-Auth: YOUR_CHANNEL_API_KEY for the VBM channel you want to send from (see API Overview and Authentication).
Content type: application/json.

Finding a template ID

Templates must be approved on the VBM channel before they can be sent.

Open Settings → Channels and select your VBM channel.
Open the Templates tab.
Click the template you want to send. The ID appears in the template details.

Request body

Field	Type	Required	Description
`destination_phone`	string	Yes	Recipient phone in E.164 format, e.g. `+14155552671`.
`message_variables`	object or array	Conditional	Values for the template’s placeholders. Required when the template has variables.
`header_image_url`	string	Conditional	Public URL of the header image. Required when the template has an image header.
`open_intercom_conversation`	boolean	No	Set to `true` to open a CRM conversation thread when the message is sent. Defaults to `false`. Accepts `true`/`false`, `1`/`0`, `yes`/`no`, `on`/`off`.
`intercom_teammate_id`	string	No	The ID of the teammate the sent message should be attributed to.

Message variable formats

VBM templates support placeholders in the header, body, and footer.

Body-only templates. Send an array of strings:

{
  "destination_phone": "+14155552671",
  "message_variables": ["Alex", "1234"]
}

Templates with header or footer placeholders. Send an object with one array per section:

{
  "destination_phone": "+14155552671",
  "message_variables": {
    "header": ["Order #1234"],
    "body":   ["Alex", "1234"],
    "footer": []
  }
}

Image headers

For templates with an image header, provide a public URL in header_image_url. The URL must be reachable by Octopods’s servers.

{
  "destination_phone": "+14155552671",
  "header_image_url": "https://example.com/banner.jpg",
  "message_variables": { "header": [], "body": ["Alex"], "footer": [] }
}

Full example

curl -X POST "https://app.octopods.io/api/v1/vbm/templates/456/messages" \
  -H "X-Octopods-Auth: YOUR_CHANNEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_phone": "+14155552671",
    "message_variables": ["Alex", "1234"],
    "open_intercom_conversation": true
  }'

Successful response

On success, Octopods returns HTTP 201 Created with an empty body. The message has been accepted and handed to the VBM provider. Final delivery status is tracked per-message in the Octopods UI.

Error codes

Errors return HTTP 400 Bad Request with:

{ "request_id": "…", "error_code": N, "error": "…" }

Code	Meaning	Fix
1	A required argument is missing (e.g. `destination_phone`, `vbm_template_id`, `header_image_url`).	Include the named field.
2	`message_variables` is the wrong type.	Send an array for body-only templates or an object for templates with non-body placeholders.
3	Template does not exist or is not approved on this channel.	Re-check the template ID and confirm it is in the Approved state.
4	The number of variables you supplied does not match the template.	Count the placeholders in the template and supply exactly that many.
5	`destination_phone` is invalid.	Use E.164 format (leading `+`, country code, no spaces).
6	Deprecated API key.	Copy the current key from the VBM channel settings screen.
7	VBM provider returned an error.	See the `error` field for provider-side details.
8	Invalid header media URL.	Confirm the URL is public and points to a valid image.

Note: Full details and recovery steps for provider errors are in Troubleshooting Failed Proactive Messages.

Sending VBM Template Messages via API