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")
  
  // Dynamic template variables (optional)
  var_[variableName]: string;  // Template variables with "var_" prefix
                              // Example: var_customer_name, var_order_id, var_date
}

​
Template Variables

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"
  }),
  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

{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 WhatsApp MessageList CRM Conversation Logs