This guide explains how to initiate conversations with customers using WhatsApp templates, including syncing templates from Meta, testing them, and sending them via API.

​

Understanding WhatsApp templates

WhatsApp templates are pre-approved message formats that businesses use to:

• Start new conversations with customers
• Send notifications outside the 24-hour window
• Ensure consistent, compliant messaging

​

How templates work with Kapso

​

Template categories

Meta classifies templates into three categories:

​

Step 1: Create templates in Meta

Before using templates in Kapso, you must create them in Meta WhatsApp Manager:

1. Log in to Meta Business Suite
2. Navigate to WhatsApp Manager → Message Templates
3. Click Create Template
4. Design your template with:
   • Template name and category
   • Message content with placeholders ({{1}}, {{2}} or {{customer_name}})
   • Optional header (text, image, document, or video)
   • Optional footer and buttons

5. Submit for approval and wait for Meta’s review

​

Step 2: Sync templates to Kapso

Once your templates are approved by Meta:

1. Navigate to WhatsApp → Templates in your Kapso project

2. Select your WhatsApp configuration from the dropdown

3. Click Sync Templates

4. Kapso will fetch all approved templates from Meta and display them with:

   • Template name and language
   • Category and status
   • Content preview
   • Required parameters

​

Step 3: Test templates

Before using templates in production, test them:

1. Click the Test button next to any template

2. In the test dialog:

   • Enter the recipient phone number
   • Fill in all required parameters
   • Preview how the message will look

3. Click Send Test to send the message

The test will:

• Validate parameter count and format
• Show a live preview with your values
• Send the actual WhatsApp message
• Display success or error feedback

​

Step 4: Send templates via API

Use the external API to send templates programmatically:

​

List available templates

GET /api/external/v1/whatsapp_templates

Query parameters:

• whatsapp_config_id: Filter by specific config
• status: Filter by status (e.g., “approved”)
• category: Filter by category

Example response:

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "order_confirmation",
      "language_code": "en_US",
      "category": "UTILITY",
      "status": "approved",
      "components": [
        {
          "type": "BODY",
          "text": "Hi \{\{1\}\}, your order #\{\{2\}\} has been confirmed and will be delivered by \{\{3\}\}."
        }
      ],
      "parameter_count": 3
    }
  ]
}

​

Send a template message

POST /api/v1/whatsapp_templates/:template_id/send_template

Request body with positional parameters:

{
  "template": {
    "phone_number": "+1234567890",
    "template_parameters": ["John", "ORD-12345", "December 25, 2024"]
  }
}

Or with named parameters:

{
  "template": {
    "phone_number": "+1234567890",
    "template_parameters": {
      "customer_name": "John",
      "order_id": "ORD-12345", 
      "delivery_date": "December 25, 2024"
    }
  }
}

Example using cURL:

curl -X POST https://app.kapso.ai/api/v1/whatsapp_templates/123e4567/send_template \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "phone_number": "+1234567890",
      "template_parameters": ["John", "ORD-12345", "December 25, 2024"]
    }
  }'

​

Response

Success response:

{
  "success": true,
  "message_id": "wamid.XXX",
  "conversation_id": "456e7890-e89b-12d3-a456-426614174001"
}

Error response:

{
  "error": "Invalid parameter count. Template requires 3 parameters, but 2 were provided."
}

​

Common issues and solutions

​

Parameter count mismatch error

Error: “Template requires 3 parameters, but 2 were provided”

Solution:

• Count placeholders in your template ({{1}}, {{2}}, etc.)
• Ensure your API call includes all required parameters
• Check for missing or null values in your parameter array

​

Template delivery failures

Error: “Failed to send template message” or delivery failures

Common cause: No payment method configured in Meta Business Manager

Solution:

1. Go to Meta Business Manager → Payment Methods
2. Add a valid payment method for WhatsApp charges
3. Ensure your WhatsApp Business account is active
4. Check for any outstanding balances

​

Next steps