Templates API

Overview

The Templates API allows you to list, retrieve, and send template messages programmatically. Templates are pre-approved message formats for proactive communication across different channels.

Sending a template as part of a conversation? Channels.whatsapp.sendTemplate is the canonical way to send a WhatsApp template to a specific user — it resolves the recipient by userId or phone number and records the send to the conversation thread, so your agent remembers the outreach. Use the Templates.whatsapp.send below for bulk / campaign sends by channel ID and a list of phone numbers. Both are supported; pick by use case.

Supported Template Types

WhatsApp Templates

Pre-approved message formats for WhatsApp Business Accounts. Required for initiating conversations outside the 24-hour messaging window.

Additional template types may be added in the future. The API is designed to work consistently across different template types.

Quick Start

import { Templates } from 'lua-cli';

// List all WhatsApp templates for a channel
const result = await Templates.whatsapp.list(channelId);
console.log(result.templates);  // Array of templates
console.log(result.total);      // Total count

// Get a specific template
const template = await Templates.whatsapp.get(channelId, 'template_123');
console.log(template.name);   // Template name
console.log(template.status); // 'APPROVED', 'PENDING', etc.

// Send a WhatsApp template message
const response = await Templates.whatsapp.send(channelId, 'template_123', {
  phoneNumbers: ['+447551166594'],
  values: {
    body: { first_name: 'John', order_number: '12345' }
  }
});

Template Listing

List and search templates with pagination

Template Retrieval

Get template details including components

Batch Sending

Send to multiple recipients at once

Dynamic Values

Fill template parameters dynamically

WhatsApp Templates

Use Templates.whatsapp for WhatsApp Business templates.

list()

List WhatsApp templates for a channel with optional pagination and search.

Templates.whatsapp.list(
  channelId: string,
  options?: ListTemplatesOptions
): Promise<PaginatedTemplatesResponse>

string

required

The WhatsApp channel identifier

object

Optional pagination and search options

number

default:1

Page number (1-indexed)

number

default:10

Items per page

string

Search query to filter templates by name

Returns:

{
  templates: Template[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

Examples:

// List all templates (first page)
const result = await Templates.whatsapp.list(channelId);

// With pagination
const page2 = await Templates.whatsapp.list(channelId, { page: 2, limit: 20 });

// Search by name
const orderTemplates = await Templates.whatsapp.list(channelId, { search: 'order' });

// Combine options
const filtered = await Templates.whatsapp.list(channelId, {
  page: 1,
  limit: 5,
  search: 'welcome'
});

get()

Retrieve a specific WhatsApp template by ID.

Templates.whatsapp.get(
  channelId: string,
  templateId: string
): Promise<WhatsAppTemplate>

string

required

The WhatsApp channel identifier

string

required

The template identifier

Returns: WhatsAppTemplate object Example:

const template = await Templates.whatsapp.get(channelId, 'template_123');

console.log(template.name);       // "order_confirmation"
console.log(template.status);     // "APPROVED"
console.log(template.category);   // "UTILITY"
console.log(template.language);   // "en"
console.log(template.components); // Array of components

send()

Send a WhatsApp template message to one or more phone numbers.

Templates.whatsapp.send(
  channelId: string,
  templateId: string,
  data: SendTemplateData
): Promise<SendTemplateResponse>

string

required

The WhatsApp channel identifier

string

required

The template identifier

object

required

Send data including recipients and template values

string[]

required

Array of recipients. For WhatsApp: phone numbers in E.164 format (e.g., +447551166594)

object

Template parameter values

object

Header component parameter values. For media headers, either use image_url (IMAGE format), video_url (VIDEO format), or document_url + optional document_filename (DOCUMENT format) — or pass a Meta media ID instead via image_id, video_id, or document_id. A media ID takes precedence if both are given.

object

Body component parameter values

SendTemplateButtonValue[]

Array of button parameter values. Each entry has sub_type ('QUICK_REPLY' | 'URL' | 'PHONE_NUMBER' | 'COPY_CODE'), index, and optional text or coupon_code.

Returns:

{
  results: Array<{
    phoneNumber: string;
    success: boolean;
    messageId?: string;
  }>;
  errors: Array<{
    phoneNumber: string;
    error: string;
  }>;
}

Examples:

// Simple send to one recipient
const result = await Templates.whatsapp.send(channelId, 'welcome_template', {
  phoneNumbers: ['+447551166594']
});

// Send with body parameters
const orderResult = await Templates.whatsapp.send(channelId, 'order_confirmation', {
  phoneNumbers: ['+447551166594'],
  values: {
    body: {
      first_name: 'John',
      order_number: '12345',
      delivery_date: 'December 25, 2025'
    }
  }
});

// Send to multiple recipients (batch)
const batchResult = await Templates.whatsapp.send(channelId, 'promotion', {
  phoneNumbers: ['+447551166594', '+447551166595', '+447551166596'],
  values: {
    header: { image_url: 'https://example.com/promo.jpg' },
    body: { discount: '20%' }
  }
});

// Send with video header
const videoResult = await Templates.whatsapp.send(channelId, 'product_demo', {
  phoneNumbers: ['+447551166594'],
  values: {
    header: { video_url: 'https://example.com/product-demo.mp4' },
    body: { product_name: 'Acme Widget' }
  }
});

// Send with document header
const docResult = await Templates.whatsapp.send(channelId, 'invoice', {
  phoneNumbers: ['+447551166594'],
  values: {
    header: {
      document_url: 'https://example.com/invoice-12345.pdf',
      document_filename: 'invoice-12345.pdf'
    },
    body: { order_number: '12345', total: '$99.99' }
  }
});

// Handle response
batchResult.results.forEach(r => {
  if (r.success) {
    console.log(`Sent to ${r.phoneNumber}: ${r.messageId}`);
  }
});

batchResult.errors.forEach(e => {
  console.error(`Failed for ${e.phoneNumber}: ${e.error}`);
});

Template Structure

WhatsApp Templates

WhatsApp templates have the following structure:

interface Template {
  id: string;
  name: string;
  status: 'APPROVED' | 'PENDING' | 'REJECTED';
  category: 'UTILITY' | 'MARKETING' | 'AUTHENTICATION';
  language: string;
  components: TemplateComponent[];
}

interface TemplateComponent {
  type: 'HEADER' | 'BODY' | 'FOOTER' | 'BUTTONS';
  format?: 'TEXT' | 'IMAGE' | 'VIDEO' | 'DOCUMENT';
  text?: string;
  buttons?: TemplateButton[];
}

interface TemplateButton {
  type: 'QUICK_REPLY' | 'URL' | 'PHONE_NUMBER' | 'COPY_CODE';
  text: string;
  url?: string;
  phone_number?: string;
  example?: string[];
}

Template structure may vary by template type. The above shows the WhatsApp template structure.

Media Headers

WhatsApp templates support media headers in addition to text headers. Headers can contain an image, video, or document:

IMAGE: Static image (format: 'IMAGE')
VIDEO: Playable video clip (format: 'VIDEO')
DOCUMENT: Downloadable document like a PDF (format: 'DOCUMENT')

When creating a template with a media header, you provide:

format — one of 'IMAGE', 'VIDEO', or 'DOCUMENT'
mediaUrl — a publicly-reachable HTTPS URL to a sample file for approval. This URL must:
- Be accessible over HTTPS
- Match the format’s MIME type requirements:
  - IMAGE: .jpg, .png, .webp
  - VIDEO: .mp4, .3gp
  - DOCUMENT: .pdf, .docx, .xlsx, .pptx (up to 10 MB)
- Be within Meta’s size limits (images ≤ 5 MB, videos ≤ 16 MB, documents ≤ 10 MB)

Once the template is approved, when you send it via the Templates.whatsapp.send() API, you provide the actual media URL in the values.header object:

image_url for IMAGE format templates
video_url for VIDEO format templates
document_url (and optionally document_filename) for DOCUMENT format templates

The media URL provided at send time must also be publicly reachable over HTTPS.

Sending by media ID instead of URL

WhatsApp re-downloads the URL on every send. For bulk campaigns you can upload the asset to Meta once and reuse the returned media ID across every recipient, which skips that per-send fetch entirely:

const response = await Templates.whatsapp.send('channel_123', 'promo_template', {
  phoneNumbers: ['+1234567890', '+0987654321'],
  values: {
    header: { image_id: '1234567890123456' },
    body: { discount: '20%' },
  },
});

Use image_id, video_id, or document_id to match the template’s header format. document_filename still applies. If you pass both a media ID and a URL, the media ID wins.

Three constraints decide whether a media ID resolves at send time:

Upload it via POST /{phone-number-id}/media. The Resumable Upload API (POST /{app-id}/uploads) returns an h:... file handle instead, which is only valid for creating a template — it will never work as a send-time media ID.
Media IDs are scoped to the business phone number they were uploaded on. That must be the phone number behind the channel you’re sending from, or Meta won’t resolve the ID.
Meta expires media IDs after 30 days. Plan on re-uploading per campaign rather than once forever.

Template Parameters

Templates use named parameters in the format {{parameter_name}}. When sending, provide values for each parameter:

// Template body: "Hello {{first_name}}, your order {{order_number}} is ready!"

await Templates.whatsapp.send(channelId, templateId, {
  phoneNumbers: ['+447551166594'],
  values: {
    body: {
      first_name: 'John',
      order_number: 'ORD-12345'
    }
  }
});

All required parameters must be provided when sending a template. Missing parameters will cause the send to fail.

WhatsApp Examples

The following examples demonstrate using the Templates API with WhatsApp templates.

Order Confirmation Tool

import { LuaTool, Templates } from 'lua-cli';
import { z } from 'zod';

export default class SendOrderConfirmationTool implements LuaTool {
  name = "send_order_confirmation";
  description = "Send order confirmation via WhatsApp template";
  
  inputSchema = z.object({
    channelId: z.string().describe("WhatsApp channel ID"),
    phoneNumber: z.string().describe("Customer phone number"),
    orderNumber: z.string().describe("Order number"),
    customerName: z.string().describe("Customer name"),
    deliveryDate: z.string().describe("Expected delivery date")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const result = await Templates.whatsapp.send(input.channelId, 'order_confirmation', {
      phoneNumbers: [input.phoneNumber],
      values: {
        body: {
          customer_name: input.customerName,
          order_number: input.orderNumber,
          delivery_date: input.deliveryDate
        }
      }
    });
    
    if (result.errors.length > 0) {
      return {
        success: false,
        error: result.errors[0].error
      };
    }
    
    return {
      success: true,
      messageId: result.results[0].messageId,
      message: `Order confirmation sent to ${input.phoneNumber}`
    };
  }
}

Webhook: Send Welcome Template on New User

import { LuaWebhook, LuaWebhookConfig, Templates } from 'lua-cli';

const config: LuaWebhookConfig = {
  name: 'new-user-welcome',
  description: 'Send welcome template when a new user signs up'
};

const webhook: LuaWebhook = {
  config,
  execute: async (event) => {
    const { channelId, phoneNumber, firstName } = event.data;
    
    // Find welcome template
    const listResult = await Templates.whatsapp.list(channelId, { search: 'welcome' });
    const welcomeTemplate = listResult.templates.find(t => t.name === 'welcome_message');
    
    if (!welcomeTemplate) {
      return { error: 'Welcome template not found' };
    }
    
    // Send welcome message
    const sendResult = await Templates.whatsapp.send(channelId, welcomeTemplate.id, {
      phoneNumbers: [phoneNumber],
      values: {
        body: { first_name: firstName }
      }
    });
    
    return {
      sent: sendResult.results.length > 0,
      messageId: sendResult.results[0]?.messageId
    };
  }
};

export default webhook;

List Templates Tool

import { LuaTool, Templates } from 'lua-cli';
import { z } from 'zod';

export default class ListTemplatesTools implements LuaTool {
  name = "list_whatsapp_templates";
  description = "List available WhatsApp templates";
  
  inputSchema = z.object({
    channelId: z.string().describe("WhatsApp channel ID"),
    search: z.string().optional().describe("Search query to filter templates"),
    page: z.number().optional().describe("Page number")
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const result = await Templates.whatsapp.list(input.channelId, {
      search: input.search,
      page: input.page || 1,
      limit: 10
    });
    
    return {
      templates: result.templates.map(t => ({
        id: t.id,
        name: t.name,
        status: t.status,
        category: t.category,
        language: t.language
      })),
      total: result.total,
      page: result.page,
      totalPages: result.totalPages
    };
  }
}

Use Cases (WhatsApp)

Transactional Notifications

// Order shipped
await Templates.whatsapp.send(channelId, 'order_shipped', {
  phoneNumbers: [customerPhone],
  values: {
    body: {
      order_number: order.id,
      tracking_number: shipment.trackingNumber,
      carrier: shipment.carrier
    }
  }
});

// Appointment reminder
await Templates.whatsapp.send(channelId, 'appointment_reminder', {
  phoneNumbers: [patientPhone],
  values: {
    body: {
      patient_name: patient.name,
      appointment_date: appointment.date,
      doctor_name: appointment.doctor
    }
  }
});

Marketing Campaigns

// Get all customers who opted in
const customers = await getOptedInCustomers();

// Send promotion to all
const result = await Templates.whatsapp.send(channelId, 'holiday_sale', {
  phoneNumbers: customers.map(c => c.phone),
  values: {
    header: { image_url: 'https://example.com/sale-banner.jpg' },
    body: { discount_code: 'HOLIDAY25' }
  }
});

console.log(`Sent: ${result.results.length}, Failed: ${result.errors.length}`);

Authentication / OTP

// Send OTP
const otp = generateOTP();
await Templates.whatsapp.send(channelId, 'otp_verification', {
  phoneNumbers: [userPhone],
  values: {
    body: { otp_code: otp }
  }
});

Tracking Delivery Status

After sending template messages, you can track whether they were delivered, read, or failed using webhook event subscriptions.

Setup

Create a webhook to handle delivery events
Subscribe it to the status events you care about

lua webhooks subscribe --webhook-name campaign-tracker --event message.sent
lua webhooks subscribe --webhook-name campaign-tracker --event message.delivered
lua webhooks subscribe --webhook-name campaign-tracker --event message.read
lua webhooks subscribe --webhook-name campaign-tracker --event message.failed

Example: Campaign Analytics

import { LuaWebhook, Data, Templates } from 'lua-cli';

const campaignTracker = new LuaWebhook({
  name: 'campaign-tracker',
  description: 'Track template message delivery for campaigns',
  
  execute: async (event) => {
    const { body } = event;
    
    await Data.create('campaign-metrics', {
      messageId: body.messageWamid,
      recipient: body.recipientId,
      status: body.status,
      timestamp: body.timestamp,
      billable: body.pricing?.billable
    }, `${body.status} ${body.recipientId}`);
    
    return { tracked: true };
  }
});

export default campaignTracker;

After sending a batch of templates, your webhook receives individual status updates for each recipient as messages are sent, delivered, and read. Use this data to measure open rates, delivery rates, and catch failures.

The messageId returned by Templates.whatsapp.send() corresponds to messageWamid in the status event payload, allowing you to correlate sends with delivery outcomes.

Best Practices

Handle Batch Send Results

When sending to multiple recipients, always check for partial failures:

const result = await Templates.whatsapp.send(channelId, templateId, {
  phoneNumbers: phoneNumbers
});

// Log successes
result.results.forEach(r => {
  console.log(`✓ Sent to ${r.phoneNumber}`);
});

// Handle failures
if (result.errors.length > 0) {
  result.errors.forEach(e => {
    console.error(`✗ Failed for ${e.phoneNumber}: ${e.error}`);
  });
}

Validate Phone Numbers

Use E.164 format for phone numbers:

// ✅ Good
phoneNumbers: ['+447551166594', '+14155552671']

// ❌ May cause issues
phoneNumbers: ['07551166594', '(415) 555-2671']

Check Template Status

Only send approved templates:

const template = await Templates.whatsapp.get(channelId, templateId);

if (template.status !== 'APPROVED') {
  throw new Error(`Template ${template.name} is not approved (status: ${template.status})`);
}

Match Parameter Names Exactly

Parameter names in values must match template parameters exactly:

// If template has: "Hello {{first_name}}, order {{order_id}} is ready"

// ✅ Correct
values: {
  body: {
    first_name: 'John',
    order_id: '12345'
  }
}

// ❌ Wrong parameter names
values: {
  body: {
    name: 'John',      // Should be 'first_name'
    orderId: '12345'   // Should be 'order_id'
  }
}

TypeScript Types

interface ListTemplatesOptions {
  page?: number;
  limit?: number;
  search?: string;
}

interface PaginatedTemplatesResponse {
  templates: Template[];
  total: number;
  page: number;
  limit: number;
  totalPages: number;
}

// WhatsApp template structure
interface WhatsAppTemplate {
  id: string;
  name: string;
  status: 'APPROVED' | 'PENDING' | 'REJECTED';
  category: 'UTILITY' | 'MARKETING' | 'AUTHENTICATION';
  language: string;
  components: TemplateComponent[];
  correct_category?: string;
  message_send_ttl_seconds?: number;
  parameter_format?: 'NAMED' | 'POSITIONAL';
  previous_category?: string;
  rejected_reason?: string;
}

interface SendTemplateData {
  phoneNumbers: string[];  // Recipients (phone numbers for WhatsApp)
  values?: {
    header?: Record<string, string>;
    body?: Record<string, string>;
    buttons?: SendTemplateButtonValue[];
  };
}

interface SendTemplateButtonValue {
  sub_type: 'QUICK_REPLY' | 'URL' | 'PHONE_NUMBER' | 'COPY_CODE';
  index: string;
  text?: string;
  coupon_code?: string;
}

interface SendTemplateResponse {
  results: Array<{
    phoneNumber: string;
    success: boolean;
    messageId?: string;
  }>;
  errors: Array<{
    phoneNumber: string;
    error: string;
  }>;
  totalProcessed: number;
  totalErrors: number;
}

Getting Started

Core Concepts

CLI Commands

API Reference

Template & Examples

Overview

Supported Template Types

WhatsApp Templates

Quick Start

Template Listing

Template Retrieval

Batch Sending

Dynamic Values

WhatsApp Templates

list()

get()

send()

Template Structure

WhatsApp Templates

Media Headers

Sending by media ID instead of URL

Template Parameters

WhatsApp Examples

Order Confirmation Tool

Webhook: Send Welcome Template on New User

List Templates Tool

Use Cases (WhatsApp)

Transactional Notifications

Marketing Campaigns

Authentication / OTP

Tracking Delivery Status

Setup

Example: Campaign Analytics

Best Practices

TypeScript Types

Next Steps

User API

Jobs API

​Overview

​Supported Template Types

WhatsApp Templates

​Quick Start

Template Listing

Template Retrieval

Batch Sending

Dynamic Values

​WhatsApp Templates

​list()

​get()

​send()

​Template Structure

​WhatsApp Templates

​Media Headers

​Sending by media ID instead of URL

​Template Parameters

​WhatsApp Examples

​Order Confirmation Tool

​Webhook: Send Welcome Template on New User

​List Templates Tool

​Use Cases (WhatsApp)

​Transactional Notifications

​Marketing Campaigns

​Authentication / OTP

​Tracking Delivery Status

​Setup

​Example: Campaign Analytics

​Best Practices

​TypeScript Types

​Next Steps

User API

Jobs API

Overview

Supported Template Types

Quick Start

WhatsApp Templates

list()

get()

send()

Template Structure

WhatsApp Templates

Media Headers

Sending by media ID instead of URL

Template Parameters

WhatsApp Examples

Order Confirmation Tool

Webhook: Send Welcome Template on New User

List Templates Tool

Use Cases (WhatsApp)

Transactional Notifications

Marketing Campaigns

Authentication / OTP

Tracking Delivery Status

Setup

Example: Campaign Analytics

Best Practices

TypeScript Types

Next Steps