Templates

Templates.whatsapp lists the WhatsApp message templates on one of the agent’s WhatsApp channels and sends one to a list of phone numbers. To send a template to one end user as part of their conversation, with a delivery record, use Channels.whatsapp.sendTemplate instead. Marketplace agent templates are a different thing; see lua marketplace. Available in tools, jobs, webhooks, triggers, processors, and workflow code steps. Verified against lua-cli 3.33.0.

import { Templates } from 'lua-cli';

Quick example

Find the channel id with lua channels list, then pass it to every call.

import { Templates, env } from 'lua-cli';

const channelId = env('WHATSAPP_CHANNEL_ID') ?? '';
const page = await Templates.whatsapp.list(channelId, { search: 'order' });

const result = await Templates.whatsapp.send(channelId, 'order_confirmation', {
  phoneNumbers: ['+15551234567'],
  values: { body: { first_name: 'Ada', order_number: 'ORD-4471' } },
});

Methods

whatsapp.list(channelId, options?)

Lists the channel’s templates, paginated, optionally filtered by name.

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

string

required

The WhatsApp channel identifier from lua channels list.

number

default:1

Page number, starting at 1.

number

default:10

Templates per page.

string

Filters templates by name.

Returns

PaginatedTemplatesResponse

Show properties

WhatsAppTemplate[]

The templates on this page.

number

Matching templates across all pages.

number

The page returned.

number

The page size used.

number

Number of pages.

Example

import { Templates, env } from 'lua-cli';

const channelId = env('WHATSAPP_CHANNEL_ID') ?? '';
const approved = (await Templates.whatsapp.list(channelId, { limit: 50 })).templates.filter(
  (t) => t.status === 'APPROVED',
);

Errors — Failed to list templates when the platform gives no message.

whatsapp.get(channelId, templateId)

Reads one template with its components.

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

string

required

The WhatsApp channel identifier.

string

required

Meta’s numeric template id, or the template’s exact name (case-insensitive).

Returns — a WhatsAppTemplate. Example

import { Templates, env } from 'lua-cli';

const channelId = env('WHATSAPP_CHANNEL_ID') ?? '';
const template = await Templates.whatsapp.get(channelId, 'order_confirmation');
if (template.status !== 'APPROVED') {
  throw new Error(`${template.name} is ${template.status}`);
}

Errors — Template "<name>" not found. Use a numeric template ID or an exact template name.; Failed to get template when the platform gives no message.

whatsapp.send(channelId, templateId, data)

Sends one approved template to a list of phone numbers and reports the outcome per recipient.

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

string

required

The WhatsApp channel identifier.

string

required

Meta’s numeric template id, or the template’s exact name (case-insensitive). The template must be APPROVED.

string[]

required

Recipients in E.164 form. A leading +, spaces, and dashes are stripped; entries with no digits are dropped.

Record<string, string>

Header parameters. For a media header, pass the public HTTPS URL as image_url, video_url, or document_url (plus document_filename), or a Meta media id as image_id, video_id, or document_id. A media id wins when both are given.

Record<string, string>

Body parameters keyed by the template’s parameter names.

Array<{ sub_type, index, text?, coupon_code? }>

Button parameters; sub_type is QUICK_REPLY, URL, PHONE_NUMBER, or COPY_CODE, and index the button’s position as a string.

Returns

SendTemplateResponse

Recipients are processed in batches of 10 with a one-second pause between batches and 30 seconds per recipient. Entries keep recipient order but don’t carry the phone number; send one recipient per call when you need to correlate.

Show properties

any[]

One entry per recipient the provider answered: Meta’s response object. On success messages[0].id is the WhatsApp message id (wamid…); a recipient Meta rejected appears here with an error object instead.

any[]

One entry per recipient whose send failed before the provider answered; read message.

number

results.length.

number

errors.length.

Example

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

export default class SendOrderConfirmationTool implements LuaTool {
  name = 'send_order_confirmation';
  description = 'Send the order confirmation template to a customer';
  inputSchema = z.object({
    phoneNumber: z.string().describe('E.164 phone number'),
    orderNumber: z.string(),
    customerName: z.string(),
  });

  async execute(input: z.infer<typeof this.inputSchema>) {
    const channelId = env('WHATSAPP_CHANNEL_ID') ?? '';
    const result = await Templates.whatsapp.send(channelId, 'order_confirmation', {
      phoneNumbers: [input.phoneNumber],
      values: { body: { customer_name: input.customerName, order_number: input.orderNumber } },
    });
    if (result.totalErrors > 0) {
      return { sent: false, error: String(result.errors[0]?.message ?? 'send failed') };
    }
    return { sent: true, messageId: result.results[0]?.messages?.[0]?.id };
  }
}

Errors — Template must be approved before sending; Template "<name>" not found. Use a numeric template ID or an exact template name.; No valid recipient phone numbers (numbers must contain digits); a 400 naming the component when a parameter value is missing or extra; Failed to send template when the platform gives no message.

Types

interface

page?, limit?, search?.

interface

The result of list.

interface

Show properties

string

Meta’s numeric id.

string

The template name.

WhatsAppTemplateStatus

APPROVED, PENDING, or REJECTED.

WhatsAppTemplateCategory

AUTHENTICATION, MARKETING, or UTILITY.

string

The language code, for example en_US.

WhatsAppTemplateComponent[]

HEADER (with format TEXT, IMAGE, VIDEO, or DOCUMENT), BODY, FOOTER, and BUTTONS components.

'NAMED' | 'POSITIONAL'

How the template names its parameters.

string | number

Meta review metadata, when present.

interface

phoneNumbers and values? (a SendTemplateValues), as on send.

interface

The result of send. results and errors are typed any[].

SDK

CLI

REST API

Quick example

Methods

whatsapp.list(channelId, options?)

whatsapp.get(channelId, templateId)

whatsapp.send(channelId, templateId, data)

Types

See also

​Quick example

​Methods

​whatsapp.list(channelId, options?)

​whatsapp.get(channelId, templateId)

​whatsapp.send(channelId, templateId, data)

​Types

​See also

Quick example

Methods

whatsapp.list(channelId, options?)

whatsapp.get(channelId, templateId)

whatsapp.send(channelId, templateId, data)

Types

See also