Messaging

Listing templates

Find existing approved templates and the language and parameter data needed to send them.

DevelopersAdvancedAvailable

What this guide covers

Filter the catalog to templates available for the selected Sender.
Use only approved templates for production sends.
Map application data to the template's declared components.

Read a Sender's approved catalog

GET /v1/templates requires templates:read. The from query is required and must be an E.164 Sender available to the current key.

The catalog is Sender-specific. A template name and language approved for one WhatsApp Business Account must not be assumed to exist for another Sender.

List approved templates

import { WhatsAppClient } from "@yanola/whatsapp"

const apiKey = process.env.YANOLA_API_KEY

if (!apiKey) {
  throw new Error("Missing YANOLA_API_KEY")
}

const yanola = new WhatsAppClient({ apiKey })

const catalog = await yanola.templates.list({
  from: "+15557654321",
  limit: 100,
})

for (const template of catalog.data) {
  console.log(
    template.name,
    template.languageCode,
    template.category
  )
}

Catalog response

Template catalog fields
Field	Meaning
`data[].name`	Template name to pass to messages.sendTemplate.
`data[].languageCode`	Approved language code; pass it exactly as returned.
`data[].status`	Public catalog entries are approved; the SDK type also reserves paused and disabled states.
`data[].category`	Provider message category captured for the approved template.
`data[].components`	Declared component structure, text, format, and examples used to build parameters.
`data[].syncedAt`	Time this template snapshot was synchronized.
`sender`	E.164 Sender whose catalog was queried.
`syncedAt`	Synchronization time shared by this catalog response.

Use cached data or request a refresh

By default, Yanola serves the approved catalog from its managed cache. Pass refresh: true only when you need Yanola to request a fresh provider snapshot.

A forced refresh requires a Live Mode key. Test Mode reads the cached approved catalog and returns 422 template_refresh_live_mode_required if refresh is true.

Force a Live Mode refresh

import { WhatsAppClient } from "@yanola/whatsapp"

const apiKey = process.env.YANOLA_API_KEY

if (!apiKey) {
  throw new Error("Missing YANOLA_API_KEY")
}

const yanola = new WhatsAppClient({ apiKey })

const refreshed = await yanola.templates.list({
  from: "+15557654321",
  refresh: true,
})

console.log(refreshed.syncedAt)

Refresh sparingly

Provider refreshes can be rate-limited. For normal sending, reuse the cached catalog and refresh only after template changes or when troubleshooting stale approval state.

Map a catalog entry to a send

Use the exact name and languageCode from the selected catalog entry. Build component parameters in the order and types declared by components.

Send a listed template

import { WhatsAppClient } from "@yanola/whatsapp"

const apiKey = process.env.YANOLA_API_KEY

if (!apiKey) {
  throw new Error("Missing YANOLA_API_KEY")
}

const yanola = new WhatsAppClient({ apiKey })

const { data } = await yanola.templates.list({
  from: "+15557654321",
})
const template = data.find(
  (item) =>
    item.name === "order_update" &&
    item.languageCode === "en_US"
)

if (!template) {
  throw new Error("Approved template not found")
}

const accepted = await yanola.messages.sendTemplate({
  from: "+15557654321",
  to: "+15551234567",
  name: template.name,
  languageCode: template.languageCode,
  components: [
    {
      type: "body",
      parameters: [{ type: "text", text: "A-1042" }],
    },
  ],
})

console.log(accepted.id)

Paginate a stable snapshot

Template lists use opaque cursor pagination with a default of 20 and a maximum of 100. The cursor is bound to the key, Sender, environment, and catalog synchronization time.

If the catalog changes between pages, Yanola rejects the old cursor with invalid_cursor. Restart the listing so every page comes from one synchronized snapshot.

Template catalog errors

Common template list errors
Status and code	Meaning	Action
`400 invalid_cursor`	The cursor is invalid for this Sender or synchronized snapshot.	Restart from the first page.
`403 insufficient_scope / sender_access_denied`	The key lacks templates:read or cannot use this Sender.	Use an appropriately scoped and permitted key.
`422 template_refresh_live_mode_required`	refresh: true was sent with a Test Mode key.	Read the cached catalog or use a Live Mode key.
`422 sender_reconnect_required`	Yanola cannot refresh through the Sender's provider connection.	Reconnect the Sender.
`429 template_catalog_refresh_rate_limited`	The provider catalog cannot be refreshed yet.	Honor Retry-After and continue using cached data when suitable.
`503 template_catalog_unavailable`	The cache or provider catalog is temporarily unavailable.	Retry only when retryable is true.