This guide explains how to initiate conversations with customers using WhatsApp templates, including syncing templates from Meta, testing them, and sending them via API.
WhatsApp requires pre-approved message templates to initiate conversations with customers or send messages outside the 24-hour customer service window. This ensures quality and prevents spam.

​
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

Kapso seamlessly integrates with Meta’s WhatsApp template system:
  • Create in Meta: Design and submit templates in Meta WhatsApp Manager
  • Sync to Kapso: Once approved (typically 24-48 hours), sync them to your project
  • Use everywhere: Send via API, test in the UI, or use in agent flows
The 24-hour customer service window ensures quality conversations. After this window, templates help you re-engage customers professionally.

​
Template categories

Meta classifies templates into three categories:

Marketing

Promotional content, product announcements, sales

Utility

Order updates, account alerts, transaction confirmations

Authentication

One-time passwords, verification codes

​
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
Template placeholders can be:
  • Positional: {{1}}, {{2}}, {{3}}
  • Named: {{customer_name}}, {{order_id}}, {{amount}}
Kapso supports both formats.
  1. 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
Re-sync templates whenever you:
  • Get new templates approved
  • Modify existing templates
  • Notice missing templates

​
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

Set up broadcasts

Send template messages to multiple recipients

Configure webhooks

Receive notifications when customers respond