Template Definition & Codegen

Learn how to define templates manually with defineTemplate() or automatically via the CLI.

Manual Definition (defineTemplate)

If you prefer not to use the CLI, you can manually define templates. You must use as const for the definition to provide full TypeScript autocomplete.

Example 1: Positional Parameters

Use param1, param2 if you want to map directly to positional indices (e.g. {{1}}) without sending explicit parameter names to Meta.

import { defineTemplate } from "whatsapp-cloud-ts";

const positionalTemplate = defineTemplate({
  name: "shipping_update",
  language: "en_US",
  header: { type: "DOCUMENT" },
  body: {
    params: { 1: "param1", 2: "param2" }
  },
  buttons: [
    { type: "URL", index: 0, paramName: "trackingUrl" }
  ]
} as const);

// Usage:
await client.sendFromDefinition(positionalTemplate, "919876543210", {
  param1: "Rahul",
  param2: "#12345",
  header: { url: "https://example.com/doc.pdf" },
  trackingUrl: "order123"
});

Example 2: Name-wise Parameters

Use descriptive names if you want the client to automatically attach parameter_name in the Meta API payload (required by newer template formats).

import { defineTemplate } from "whatsapp-cloud-ts";

const namedTemplate = defineTemplate({
  name: "shipping_update",
  language: "en_US",
  header: { type: "DOCUMENT" },
  body: {
    params: { 1: "customerName", 2: "trackingNumber" }
  },
  buttons: [
    { type: "URL", index: 0, paramName: "trackingUrl" }
  ]
} as const);

// Usage:
await client.sendFromDefinition(namedTemplate, "919876543210", {
  customerName: "Rahul",
  trackingNumber: "#12345",
  header: { url: "https://example.com/doc.pdf" },
  trackingUrl: "order123"
});

TemplateConfig Properties

Positional vs Name-wise Parameters

The package handles two types of template parameters based on the variable name you define in body.params:

• Positional (e.g. param1, param2): If your parameter is exactly named like param1, the client sends only the text value to Meta (which maps directly to positional indexes like {{1}}).
• Name-wise (e.g. customerName): If you use a descriptive custom name, the client automatically attaches parameter_name: "customerName" inside the Meta API payload. This is fully supported and required by newer Meta template formats.

Auto-Generating Template Types (CLI)

Instead of typing the configurations above manually, our built-in CLI tool fetches your actual approved templates from the WhatsApp Cloud API and generates the definitions automatically.

# Set up credentials
WA_ACCESS_TOKEN=your_token
WA_BUSINESS_ACCOUNT_ID=your_waba_id

# Run the generator
npx whatsapp-cloud-ts

This generates a whatsapp-templates/ folder in your project with an individual file for each template and an index.ts. You can directly import these into your sendFromDefinition calls.