POST
/
whatsapp
/
{phoneNumberId}
/
template-message
curl --request POST \
  --url https://api.chatvolt.ai/whatsapp/{phoneNumberId}/template-message \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "to": "55987654321",
  "text": "Hello! Please check our latest offers.",
  "agentId": "abcd123465",
  "templateName": "special_offer",
  "templateLangCode": "en_US"
}'

This endpoint allows you to send WhatsApp template messages with dynamic variables to contacts through your registered WhatsApp Business account.

​
Prerequisites

  • An active premium subscription
  • A configured WhatsApp Business account integration
  • Agent configured with the WhatsApp channel
  • Template must be pre-approved on WhatsApp Business Manager

​
Path Parameters

ParameterTypeRequiredDescription
phoneNumberIdstringYesThe WhatsApp Business phone number ID

​
Request Body

{
  to: string;                  // Recipient's phone number with country code (e.g., "491234567890")
  text: string;                // Message text to store in conversation history
  agentId: string;             // ID of the agent to associate with this message
  templateName: string;        // Name of the pre-approved WhatsApp template
  templateLangCode: string;    // Language code (e.g., "en_US", "es_ES")

  defaultStatus?: "RESOLVED" | "UNRESOLVED" | "HUMAN_REQUESTED"; // Optional: Set a default status for the conversation

  // Media Header (optional)
  header_type?: "image" | "video" | "document" | "text"; // Type of media for the header
  header_text?: string;             // Required if header_type is "text"
  header_link?: string;             // URL for the media file (if not using an ID)
  header_id?: string;               // ID of an uploaded media file
  header_filename?: string;         // Optional: Filename for documents

  // Dynamic template variables (optional)
  var_[variableName]: string;  // Template variables with "var_" prefix
                              // Example: var_customer_name, var_order_id, var_date
}

​
Sending Media Templates

To send a template with a media header (image, video, or document), provide the header_type and the corresponding media source (header_link or header_id).

  • Using a URL: Set header_type and provide the public URL in header_link.
  • Using a Media ID: Set header_type and provide the ID of a previously uploaded media file in header_id.
  • Text Header: Set header_type to "text" and provide the text in header_text.

​
Body Variables

You can include dynamic variables in your template body by adding fields with the var_ prefix to your request body. These will be automatically mapped to the template parameters.

You can include dynamic variables in your template by adding fields with the var_ prefix to your request body. These will be automatically mapped to the template parameters.

Format: var_[parameter_name]: "value"

Examples:

  • var_customer_name: "John Doe" → maps to parameter customer_name
  • var_order_id: "12345" → maps to parameter order_id
  • var_delivery_date: "2024-01-15" → maps to parameter delivery_date

​
Response

Returns the created conversation object.

​
Example JS Code

​
Basic Template (No Variables)

const apiUrl = 'https://api.chatvolt.ai';
const apiKey = 'XXX';
const phoneNumberId = 'XXX'; // Your WhatsApp Business Phone Number ID

const res = await fetch(
  `${apiUrl}/whatsapp/${phoneNumberId}/template-message`,
  {
    method: 'POST',
    body: JSON.stringify({
      to: '491234567890',
      text: 'Hello! Please check our latest offers.',
      agentId: 'abcd123456',
      templateName: 'special_offer',
      templateLangCode: 'en_US',
    }),
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${apiKey}`,
    },
  }
);

const data = await res.json();

​
Template with Variables

const apiUrl = 'https://api.chatvolt.ai';
const apiKey = 'XXX';
const phoneNumberId = 'XXX'; // Your WhatsApp Business Phone Number ID

const res = await fetch(
  `${apiUrl}/whatsapp/${phoneNumberId}/template-message`,
  {
    method: 'POST',
    body: JSON.stringify({
      to: '491234567890',
      text: 'Order confirmation for John Doe - Order #12345',
      agentId: 'abcd123456',
      templateName: 'order_confirmation',
      templateLangCode: 'en_US',

      // Template variables
      var_customer_name: 'John Doe',
      var_order_id: '12345',
      var_delivery_date: 'January 25, 2024',
      var_total_amount: '$299.99',
      defaultStatus: 'RESOLVED',
    }),
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${apiKey}`,
    },
  }
);

const data = await res.json();

​
Template with Image Header

const apiUrl = 'https://api.chatvolt.ai';
const apiKey = 'XXX';
const phoneNumberId = 'XXX'; // Your WhatsApp Business Phone Number ID

const res = await fetch(
  `${apiUrl}/whatsapp/${phoneNumberId}/template-message`,
  {
    method: 'POST',
    body: JSON.stringify({
      to: '491234567890',
      text: 'Here is your ticket.',
      agentId: 'abcd123456',
      templateName: 'ticket_with_image',
      templateLangCode: 'en_US',

      // Header
      header_type: 'image',
      header_link: 'https://example.com/ticket.png',

      // Body variables
      var_event_name: 'Tech Conference 2025',
      var_seat_number: 'A42',
    }),
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${apiKey}`,
    },
  }
);

const data = await res.json();

​
Template Variable Mapping

The API automatically converts var_ prefixed fields into WhatsApp Cloud API template components:

Request Body:

{
  "var_customer_name": "John Doe",
  "var_order_id": "12345"
}

Generated WhatsApp Components:

{
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "parameter_name": "customer_name",
          "text": "John Doe"
        },
        {
          "type": "text",
          "parameter_name": "order_id",
          "text": "12345"
        }
      ]
    }
  ]
}

​
Error Responses

Status CodeDescription
400Bad Request - Missing required parameters
401Unauthorized - Invalid token
402Payment Required - Premium subscription required
404Not Found - Phone number ID or agent not found
500Internal Server Error

​
Webhooks

After sending a template, a webhook with the AGENT_MESSAGE_SENDED event type will be triggered with the following data:

{
  eventType: "AGENT_MESSAGE_SENDED",
  conversationId: string,
  messageId: string,
  agentId: string,
  agentName: string,
  channel: "whatsapp",
  conversationStatus: string,
  conversationPriority: string,
  assigneeUserId: string,
  isAiEnabled: boolean,
  userName: string,
  userEmail: string,
  userPhoneNumber: string,
  summary: string,
  agentResponse: string
}

Authorizations

Authorization
string
headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

phoneNumberId
string
required

ID of the WhatsApp Business phone number

Body

application/json
to
string
required

Recipient's phone number with country code

text
string
required

Message text to store in conversation history

agentId
string
required

ID of the agent to associate with this message

templateName
string
required

Name of the pre-approved WhatsApp template

templateLangCode
string
required

Language code for the template

defaultStatus
enum<string>

The default status to set for the conversation.

Available options:
RESOLVED,
UNRESOLVED,
HUMAN_REQUESTED
{key}
string

Dynamic template variables with 'var_' prefix (e.g., var_customer_name, var_order_id)

Response

200 - application/json
id
string

Conversation ID

channelExternalId
string

External ID for the channel

channel
enum<string>

Conversation channel

Available options:
whatsapp
messages
object[]

Messages in the conversation

Was this page helpful?

Send a message through the Zapper integrationGet Mercado Livre Products