Get Templates

What it does

Lists an application’s WhatsApp templates: cursor pagination + status/category/language filters + name/content search + expand. Data is read fresh directly from Meta (no caching); the app_id is verified to belong to the organization.

Endpoint

GET /api/v1/wa/{app_id}/templates

Headers

string

required

Secret key in Bearer sk_... format. See Secret Key authentication.

Path parameters

string

required

Application ID. Must belong to the organization (otherwise 404).

Query parameters

All query parameters are optional.

integer

default:"20"

Maximum records per page. Range 1–100.

string

Next-page cursor (the nextCursor from a previous response). Do not pass it on the first request.

string

Previous-page cursor (the previousCursor from a response). Cannot be used together with after.

string

Status filter: APPROVED, PENDING, REJECTED, PAUSED, DISABLED, IN_APPEAL, PENDING_DELETION, DELETED, LIMIT_EXCEEDED, or UNKNOWN. Any other value returns 422. See Template Status.

string

Category filter: UTILITY, MARKETING, or AUTHENTICATION. Any other value returns 422.

string

Language filter: a BCP-47 code (e.g. en, tr).

string

Meta name_or_content search (matches the template name or body text).

string[]

components → also returns the components (not returned by default). Repeatable. See Template Expand.

Pagination: don’t pass a cursor on the first request; send the response’s nextCursor as after= on the next request.

Response

Type: CursorPagingResult[TemplateResponseModel]. The envelope is { "data": [ ... ], "pagingMetadata": { ... }, "isSuccess": true }.

boolean

true when the request completed successfully.

object[]

The list of templates (TemplateResponseModel).

Show template

string

The template’s Meta ID.

string

Template name.

string

Language code.

string

UTILITY, MARKETING, or AUTHENTICATION. See Template Category.

string

The review/lifecycle state: APPROVED, PENDING, REJECTED, PAUSED, DISABLED, IN_APPEAL, PENDING_DELETION, DELETED, LIMIT_EXCEEDED, or UNKNOWN. See Template Status for what each one means.

object[]

Component details. Returned only with expand=components. Identical shape to Get Template Detail — type (HEADER / BODY / FOOTER / BUTTONS / CAROUSEL / LIMITED_TIME_OFFER) plus the fields relevant to that type, including example, cards, and limitedTimeOffer.

string

Meta’s quality rating: GREEN (high), YELLOW (medium), RED (low), or UNKNOWN (not yet rated).

string

Why Meta rejected the template: NONE, ABUSIVE_CONTENT, INVALID_FORMAT, PROMOTIONAL, TAG_CONTENT_MISMATCH, SCAM, INCORRECT_CATEGORY, or UNKNOWN. See Template Rejected Reason.

string

How variables are referenced: POSITIONAL ({{1}}, {{2}}), NAMED, or UNKNOWN.

object

Show pagingMetadata

string

Next-page cursor (dropped if absent). Pass it as after.

string

Previous-page cursor (dropped if absent). Pass it as before.

boolean

Whether a next page exists.

boolean

Whether a previous page exists.

integer

Number of records in this page.

Null fields (id, createdAt, updatedAt, messageSendTtlSeconds, correctCategory, previousCategory) are dropped from the response. On the first request, do not pass after/before — take the cursors from the response.

Examples

Demo 1 — all (default)

GET /api/v1/wa/{app_id}/templates
Authorization: Bearer sk_...

{
  "data": [
    { "sourceId": "842802041844912", "name": "order_confirmation", "language": "en", "category": "UTILITY", "status": "APPROVED", "qualityScore": "GREEN", "rejectedReason": "NONE", "parameterFormat": "POSITIONAL" },
    { "sourceId": "1560534655590931", "name": "summer_sale", "language": "en", "category": "MARKETING", "status": "APPROVED", "qualityScore": "YELLOW", "rejectedReason": "NONE", "parameterFormat": "POSITIONAL" }
  ],
  "pagingMetadata": { "hasNext": false, "hasPrevious": false, "pageSize": 2 },
  "isSuccess": true
}

Demo 2 — status filter

GET /api/v1/wa/{app_id}/templates?status=APPROVED
Authorization: Bearer sk_...

{
  "data": [
    { "sourceId": "842802041844912", "name": "order_confirmation", "language": "en", "category": "UTILITY", "status": "APPROVED", "qualityScore": "GREEN", "rejectedReason": "NONE", "parameterFormat": "POSITIONAL" }
  ],
  "pagingMetadata": { "hasNext": false, "hasPrevious": false, "pageSize": 1 },
  "isSuccess": true
}

Demo 3 — category + language

GET /api/v1/wa/{app_id}/templates?category=UTILITY&language=en
Authorization: Bearer sk_...

{
  "data": [
    { "sourceId": "842802041844912", "name": "order_confirmation", "language": "en", "category": "UTILITY", "status": "APPROVED", "qualityScore": "GREEN", "rejectedReason": "NONE", "parameterFormat": "POSITIONAL" }
  ],
  "pagingMetadata": { "hasNext": false, "hasPrevious": false, "pageSize": 1 },
  "isSuccess": true
}

Demo 4 — search

GET /api/v1/wa/{app_id}/templates?search=order
Authorization: Bearer sk_...

{
  "data": [
    { "sourceId": "842802041844912", "name": "order_confirmation", "language": "en", "category": "UTILITY", "status": "APPROVED", "qualityScore": "GREEN", "rejectedReason": "NONE", "parameterFormat": "POSITIONAL" }
  ],
  "pagingMetadata": { "hasNext": false, "hasPrevious": false, "pageSize": 1 },
  "isSuccess": true
}

Demo 5 — with components (expand=components)

GET /api/v1/wa/{app_id}/templates?expand=components&status=APPROVED
Authorization: Bearer sk_...

{
  "data": [
    {
      "sourceId": "842802041844912",
      "name": "order_confirmation",
      "language": "en",
      "category": "UTILITY",
      "status": "APPROVED",
      "components": [
        { "type": "HEADER", "format": "TEXT", "text": "Order #{{1}} confirmed", "example": { "headerText": ["12345"] } },
        { "type": "BODY", "text": "Hello {{1}}, your order {{2}} has been confirmed.", "example": { "bodyText": [["John", "#12345"]] } },
        { "type": "FOOTER", "text": "Sent via Connexease" },
        { "type": "BUTTONS", "buttons": [ { "type": "QUICK_REPLY", "text": "Track" } ] }
      ],
      "qualityScore": "GREEN",
      "rejectedReason": "NONE",
      "parameterFormat": "POSITIONAL"
    }
  ],
  "pagingMetadata": { "hasNext": false, "hasPrevious": false, "pageSize": 1 },
  "isSuccess": true
}

Demo 6 — pagination (cursor)

First page:

GET /api/v1/wa/{app_id}/templates?limit=2
Authorization: Bearer sk_...

{
  "data": [
    { "sourceId": "842802041844912", "name": "order_confirmation", "language": "en", "category": "UTILITY", "status": "APPROVED", "qualityScore": "GREEN", "rejectedReason": "NONE", "parameterFormat": "POSITIONAL" },
    { "sourceId": "1831871288221211", "name": "order_update", "language": "en", "category": "UTILITY", "status": "PENDING", "qualityScore": "UNKNOWN", "rejectedReason": "NONE", "parameterFormat": "POSITIONAL" }
  ],
  "pagingMetadata": { "nextCursor": "MAZDZDhYbVZ3PQ", "hasNext": true, "hasPrevious": false, "pageSize": 2 },
  "isSuccess": true
}

Next page (nextCursor → after):

GET /api/v1/wa/{app_id}/templates?limit=2&after=MAZDZDhYbVZ3PQ
Authorization: Bearer sk_...

{
  "data": [
    { "sourceId": "1560534655590931", "name": "summer_sale", "language": "en", "category": "MARKETING", "status": "APPROVED", "qualityScore": "YELLOW", "rejectedReason": "NONE", "parameterFormat": "POSITIONAL" }
  ],
  "pagingMetadata": { "previousCursor": "MQZDZDhYbVZ3PQ", "hasNext": false, "hasPrevious": true, "pageSize": 1 },
  "isSuccess": true
}

Empty result: "data": [] with "pagingMetadata": { "hasNext": false, "hasPrevious": false, "pageSize": 0 }.

Errors

object

Error details with code, group, and description; isSuccess is false.

Auth / tenant

HTTP	Code	When
401	`ORGANIZATION_SECRET_010`	Secret key is missing.
401	`ORGANIZATION_SECRET_011`	Secret key is invalid.
404	`APPLICATION_004`	`app_id` does not belong to the organization.

Request validation (422)

HTTP	When
422	`limit` outside 1–100; invalid `status`/`category` enum value; invalid `expand` value.

Meta-side

HTTP	Code	When
401	`META_034`	Token invalid/expired (190).
403	`META_035`	Permission denied (10 / 200–299).
429	`META_036`	Rate limit (4 / 80007).
400	`META_037`	Invalid parameter (100).
502	`META_004`	General/fallback listing error.

Example error response (429 rate limit):

{ "errors": { "code": "META_036", "group": "...", "description": "Failed to fetch templates. Details: ..." }, "isSuccess": false }

Getting Started

Analytics

Application

Template

Media

Developers

Reference

What it does

Endpoint

Headers

Path parameters

Query parameters

Response

Examples

Errors

Auth / tenant

Request validation (422)

Meta-side

​What it does

​Endpoint

​Headers

​Path parameters

​Query parameters

​Response

​Examples

​Errors

​Auth / tenant

​Request validation (422)

​Meta-side

What it does

Endpoint

Headers

Path parameters

Query parameters

Response

Examples

Errors

Auth / tenant

Request validation (422)

Meta-side