​
Overview

WhatsApp template messages are pre-approved message formats that allow businesses to send notifications and initiate conversations with users. This guide covers all the ways to send template messages through Kapso, including support for various template types and parameter formats.

​
Sending Templates via API

​
Basic Template Message

Send a simple text template with positional parameters: 
curl -X POST https://api.kapso.ai/whatsapp_templates/{template_id}/send_template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "phone_number": "+1234567890",
      "template_parameters": ["John", "ORDER123"]
    }
  }'

​
Named Parameters

For templates using named parameters (e.g., \{\{customer_name\}\}, \{\{order_id\}\}): 
curl -X POST https://api.kapso.ai/whatsapp_templates/{template_id}/send_template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "phone_number": "+1234567890",
      "template_parameters": {
        "customer_name": "John Smith",
        "order_id": "ORDER123"
      }
    }
  }'

​
Templates with Headers

​
Text Header with Parameter

For headers with dynamic text like “Welcome {{customer_name}}!” or “Welcome {{1}}!”: For templates with positional parameters: 
curl -X POST https://api.kapso.ai/whatsapp_templates/{template_id}/send_template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "phone_number": "+1234567890",
      "template_parameters": ["Your order is ready"],
      "header_type": "text",
      "header_params": "John Smith"
    }
  }'
For templates with named parameters: 
curl -X POST https://api.kapso.ai/whatsapp_templates/{template_id}/send_template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "phone_number": "+1234567890",
      "template_parameters": {
        "order_status": "ready",
        "delivery_date": "tomorrow"
      },
      "header_type": "text",
      "header_params": "John Smith"  # Or {"name": "John Smith"} for named header param
    }
  }'
WhatsApp headers support only ONE parameter. The header_params field accepts either:
  • A single string value (e.g., "John Smith")
  • For named parameter templates, you can also use a hash with the parameter name (e.g., {"name": "John Smith"})
Both formats work and will correctly replace the placeholder in the header text.

​
Image Header

curl -X POST https://api.kapso.ai/whatsapp_templates/{template_id}/send_template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "phone_number": "+1234567890",
      "template_parameters": ["John", "ORDER123"],
      "header_type": "image",
      "header_params": "https://example.com/product-image.jpg"
    }
  }'

​
Video Header

curl -X POST https://api.kapso.ai/whatsapp_templates/{template_id}/send_template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "phone_number": "+1234567890",
      "template_parameters": ["Welcome message"],
      "header_type": "video",
      "header_params": "https://example.com/intro-video.mp4"
    }
  }'

​
Document Header

curl -X POST https://api.kapso.ai/whatsapp_templates/{template_id}/send_template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "phone_number": "+1234567890",
      "template_parameters": ["Invoice for your order"],
      "header_type": "document",
      "header_params": "https://example.com/invoice.pdf",
      "header_filename": "Invoice_2024.pdf"
    }
  }'

​
Templates with Location Headers

Send a template with a location header: 
curl -X POST https://api.kapso.ai/whatsapp_templates/{template_id}/send_template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "phone_number": "+1234567890",
      "template_parameters": ["Your order is ready"],
      "location_params": {
        "latitude": 37.7749,
        "longitude": -122.4194,
        "name": "Pickup Location",
        "address": "123 Market St, San Francisco, CA 94105"
      }
    }
  }'

​
Templates with Interactive Buttons

​
URL Buttons with Dynamic Parameters

curl -X POST https://api.kapso.ai/whatsapp_templates/{template_id}/send_template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "phone_number": "+1234567890",
      "template_parameters": ["Your order is ready"],
      "button_url_params": {
        "0": "ORDER123"  # Parameter for first URL button
      }
    }
  }'

​
Quick Reply Buttons

curl -X POST https://api.kapso.ai/whatsapp_templates/{template_id}/send_template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "phone_number": "+1234567890",
      "template_parameters": ["Please confirm your appointment"],
      "button_quick_reply_payloads": {
        "0": "CONFIRM_YES",
        "1": "CONFIRM_NO"
      }
    }
  }'

​
Copy Code Buttons

curl -X POST https://api.kapso.ai/whatsapp_templates/{template_id}/send_template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "phone_number": "+1234567890",
      "template_parameters": ["Use this code for 20% off"],
      "button_copy_code_params": {
        "0": "SAVE20"
      }
    }
  }'

​
Complete Example with All Features

Here’s a comprehensive example combining headers, body parameters, and buttons: 
curl -X POST https://api.kapso.ai/whatsapp_templates/{template_id}/send_template \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template": {
      "phone_number": "+1234567890",
      "template_parameters": {
        "customer_name": "John Smith",
        "order_id": "ORDER123",
        "delivery_date": "December 25, 2024"
      },
      "header_type": "image",
      "header_params": "https://example.com/package.jpg",
      "button_url_params": {
        "0": "ORDER123"
      },
      "button_quick_reply_payloads": {
        "1": "NEED_HELP"
      }
    }
  }'

​
Sending Templates with Flows

Flows provide a powerful way to send template messages as part of automated workflows. When configuring a Send Template action in a flow, you specify the parameters in the “Parameters” field.

​
Structured Parameters Format

All Send Template actions in flows use the structured format with specific parameter keys. This provides consistent support for all template features including headers, buttons, and advanced components.

​
Basic Structured Format

​
For Simple Text Templates

For templates with only body parameters (positional): 
{
  "template_params": ["the_customer_name", "the_order_id"]
}
For templates with named parameters: 
{
  "template_params": {
    "customer_name": "the_user_name", 
    "order_id": "the_order_number"
  }
}

​
For Templates with Advanced Features

To configure headers, buttons, and other features, add the corresponding keys: 
{
  "template_params": ["the_customer_name", "the_order_id"],
  "header_params": "the_document_url",
  "header_filename": "Invoice_the_invoice_number.pdf",
  "button_url_params": {
    "0": "the_tracking_code"
  }
}

​
Flow Parameter Examples

​
Text Header with Parameter

For a template with header text “Welcome {{1}}!” (positional) or “Welcome {{name}}!” (named) and body parameters: Positional parameters: 
{
  "template_params": ["the_order_id", "the_delivery_date"],
  "header_params": "the_customer_name"
}
Named parameters: 
{
  "template_params": {
    "order_id": "the_order_id",
    "delivery_date": "the_delivery_date"
  },
  "header_params": "the_customer_name"
}
Or with explicit parameter name for the header: 
{
  "template_params": {
    "order_id": "the_order_id",
    "delivery_date": "the_delivery_date"
  },
  "header_params": {"name": "the_customer_name"}
}
Remember: header_params accepts either a single string value or a hash with the parameter name. Flow variables like \{\{customer_name\}\} will be substituted before sending.

​
Order Confirmation with Image Header and Tracking Button

For a template with image header, body text, and a URL button with dynamic parameter: 
{
  "template_params": {
    "customer_name": "the_user_name",
    "order_id": "the_order_number",
    "total_amount": "the_order_total"
  },
  "header_params": "https://cdn.example.com/orders/\{\{order_number\}\}.jpg",
  "button_url_params": {
    "0": "the_order_number"
  }
}

​
Appointment Reminder with Location

For a template with location header and quick reply buttons: 
{
  "template_params": ["the_patient_name", "the_appointment_time"],
  "location_params": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "name": "the_clinic_name",
    "address": "the_clinic_address"
  },
  "button_quick_reply_payloads": {
    "0": "CONFIRM_APPOINTMENT",
    "1": "RESCHEDULE_REQUEST"
  }
}

​
Promotional Message with Copy Code

For a marketing template with image header and copy code button: 
{
  "template_params": ["the_customer_name", "the_discount_percentage"],
  "header_params": "https://cdn.example.com/promotions/holiday-sale.jpg",
  "button_copy_code_params": {
    "0": "the_promo_code"
  }
}

​
Document Header with Filename

For templates with document headers: 
{
  "template_params": ["the_invoice_date", "the_amount_due"],
  "header_params": "https://cdn.example.com/invoices/the_invoice_id.pdf",
  "header_filename": "Invoice_the_invoice_number.pdf"
}

​
Simple Text Template

For templates with only text parameters (most common case): 
{
  "template_params": ["the_customer_name", "the_order_status", "the_delivery_date"]
}

​
Parameter Types Reference

​
Template Body Parameters

FormatUse CaseExample
ArrayPositional parameters (\{\{1}}, \{\{2\}\})["John", "ORDER123"]
ObjectNamed parameters (\{\{name\}\}, \{\{order\}\}){"name": "John", "order": "ORDER123"}

​
Header Parameters

TypeParameterDescriptionExample
textheader_paramsText value to replace {{1}} or {{param_name}} in header"John Smith" for header “Welcome {{1}}!“
imageheader_paramsImage URL"https://example.com/image.jpg"
videoheader_paramsVideo URL"https://example.com/video.mp4"
documentheader_params + header_filenameDocument URL and filenameURL: "https://example.com/doc.pdf"
Filename: "Invoice.pdf"
locationlocation_paramsLocation objectSee location example above
Important: WhatsApp headers support only ONE parameter. Even if you design a header with multiple placeholders, WhatsApp will only accept one value in header_params.

​
Button Parameters

Button TypeParameter KeyDescriptionExample
URLbutton_url_paramsDynamic URL parameters{"0": "ORDER123"}
Quick Replybutton_quick_reply_payloadsCustom payloads{"0": "YES", "1": "NO"}
Copy Codebutton_copy_code_paramsCoupon codes{"0": "SAVE20"}
Button indices (0, 1, 2, etc.) correspond to the order of buttons defined in your template.