WhatsApp Templates API

Submit, fetch, list, update, and delete WhatsApp message templates for a WhatsApp Business Account (WABA) linked to your Plivo account. See the WhatsAppTemplate object for the resource schema. Templates start in PENDING; Meta reviews them asynchronously and emits status events that Plivo forwards to your configured WABA webhook URL.

Use this API to manage WhatsApp templates programmatically as an alternative to the WhatsApp Manager UI. All operations are scoped to a single WABA identified by waba_id. API Endpoint

https://api.plivo.com/v1/Account/{auth_id}/WhatsApp/Template/{waba_id}/

Find your waba_id in the Plivo console under Messaging > WhatsApp Business Account.

Authentication All endpoints use HTTP Basic Auth. Use your Plivo auth_id as the username and auth_token as the password. Find these on the Plivo console. Asynchronous review When you create or update a template, Meta reviews it asynchronously. The template’s status moves from PENDING to APPROVED, REJECTED, PAUSED, or DISABLED over time. Meta emits an event for each transition, which Plivo forwards to the webhook URL configured for your WABA. You can also call Get a Template or List Templates at any time to fetch the current status.

The WhatsAppTemplate Object

Attributes

string

Meta-issued template ID. Use this in path parameters for Get, Update, and Delete.

string

snake_case template name, unique per WABA. Allowed characters: a-z, 0-9, underscore.

string

BCP-47 language code. Examples: en, en_US, es_MX.

string

Template category. Values: MARKETING, UTILITY, AUTHENTICATION.

string

Current Meta-assigned status. Values: PENDING, APPROVED, REJECTED, PAUSED, DISABLED.

object

Quality metric assigned by Meta. When present, contains a single field score with values GREEN, YELLOW, RED, or UNKNOWN. May be null or absent for templates in PENDING status — check for the field before reading quality_score.score.

string

Reason for rejection assigned by Meta. Returned as NONE for templates that have not been rejected. Possible values when status is REJECTED: ABUSIVE_CONTENT, INVALID_FORMAT, PROMOTIONAL, TAG_CONTENT_MISMATCH, INCORRECT_CATEGORY, SCAM.

array

Ordered list of template sections. See Component object below.

Component Object

Each item in components is a TemplateComponent:

string

Component type. Values: HEADER, BODY, FOOTER, BUTTONS, CAROUSEL.

string

Header format. Only meaningful when type is HEADER. Values: TEXT, IMAGE, VIDEO, DOCUMENT, LOCATION.

string

Text content for BODY, FOOTER, and text-format HEADER. Use {{1}}, {{2}} for positional placeholders, or named placeholders like {{customer_name}} paired with example.body_text_named_params.

object

Sample values Meta uses during review. Pick the variant matching your component:

header_text — array of sample strings for a TEXT header with placeholders.
header_handle — array of media handles from Meta’s resumable-upload API for IMAGE, VIDEO, or DOCUMENT headers.
header_text_named_params — array of { param_name, example } for a TEXT header that uses {{name}} style placeholders.
body_text — array of example sets for positional {{1}}, {{2}} placeholders. The outer array contains one or more example sets; each inner array contains one sample value per placeholder, in order.
body_text_named_params — array of { param_name, example } for a body that uses {{name}} style placeholders.

array

Only meaningful when type is BUTTONS. Each button has type (QUICK_REPLY, PHONE_NUMBER, URL, OTP, COPY_CODE), text, and optionally phone_number, url, or example.

array

Only meaningful when type is CAROUSEL. Each card has its own components array (at minimum a HEADER and a BODY).

Example Object

{
  "api_id": "db342550-7f1d-11e1-8ea7-1231380bc196",
  "template_id": "123456789012345",
  "name": "order_confirmation",
  "language": "en_US",
  "category": "MARKETING",
  "status": "APPROVED",
  "quality_score": { "score": "GREEN" },
  "rejected_reason": "NONE",
  "components": [
    {
      "type": "BODY",
      "text": "Hi {{1}}, your order {{2}} is on its way.",
      "example": {
        "body_text": [["Alex", "ORD-12345"]]
      }
    }
  ]
}

Create a Template

Submit a new template to Meta via the bound WABA. The new template starts in PENDING. Meta reviews it asynchronously and emits a status event that Plivo forwards to your configured WABA webhook URL. Create returns an action confirmation envelope (api_id, template_id, template_status, etc.) — not the full template object. Call Get a Template to fetch components and other fields.

POST https://api.plivo.com/v1/Account/{auth_id}/WhatsApp/Template/{waba_id}/

Arguments

string

required

snake_case template name, unique per WABA. After you delete a template, Meta enforces a 30-day cooldown before the same name can be reused.

string

required

BCP-47 language code (for example, en_US).

string

required

Values: MARKETING, UTILITY, AUTHENTICATION.

array

required

Non-empty array of components. At least one BODY component is required; HEADER, FOOTER, BUTTONS, and CAROUSEL are optional. See Component object.

boolean

When true, Meta is allowed to switch the template’s category during review (for example, UTILITY to MARKETING) instead of rejecting the submission for mismatched content. Defaults to false, in which case Meta typically rejects templates whose content doesn’t match the requested category.

Example — Text-only marketing template

curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/WhatsApp/Template/{waba_id}/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_confirmation",
    "language": "en_US",
    "category": "MARKETING",
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{1}}, your order {{2}} is on its way.",
        "example": {
          "body_text": [["Alex", "ORD-12345"]]
        }
      }
    ]
  }'

Example — Body with named parameters

curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/WhatsApp/Template/{waba_id}/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{
    "name": "account_alert_named",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{customer_name}}, your balance is {{balance}}.",
        "example": {
          "body_text_named_params": [
            { "param_name": "customer_name", "example": "Alex" },
            { "param_name": "balance", "example": "$42.00" }
          ]
        }
      }
    ]
  }'

Example — Image header with media handle

Upload your media via Meta’s resumable-upload API and pass the returned handle in header_handle.

curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/WhatsApp/Template/{waba_id}/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{
    "name": "receipt_image",
    "language": "en_US",
    "category": "UTILITY",
    "components": [
      {
        "type": "HEADER",
        "format": "IMAGE",
        "example": {
          "header_handle": ["4::aW1hZ2UvanBlZw==:..."]
        }
      },
      {
        "type": "BODY",
        "text": "Your receipt is attached."
      }
    ]
  }'

Example — Carousel template

Meta requires a CAROUSEL component to contain between 2 and 10 cards.

curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/WhatsApp/Template/{waba_id}/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{
    "name": "product_carousel",
    "language": "en_US",
    "category": "MARKETING",
    "components": [
      { "type": "BODY", "text": "Check out our new arrivals!" },
      {
        "type": "CAROUSEL",
        "cards": [
          {
            "components": [
              {
                "type": "HEADER",
                "format": "IMAGE",
                "example": { "header_handle": ["4::aW1nMQ==:..."] }
              },
              {
                "type": "BODY",
                "text": "Card 1: {{1}}",
                "example": { "body_text": [["Free shipping"]] }
              }
            ]
          },
          {
            "components": [
              {
                "type": "HEADER",
                "format": "IMAGE",
                "example": { "header_handle": ["4::aW1nMg==:..."] }
              },
              {
                "type": "BODY",
                "text": "Card 2: {{1}}",
                "example": { "body_text": [["20% off"]] }
              }
            ]
          }
        ]
      }
    ]
  }'

Response

{
  "api_id": "a5f1e9b2-58b6-11e1-86da-77300b68f8bb",
  "status": "success",
  "message": "template submitted to meta for review",
  "template_id": "123456789012345",
  "template_name": "order_confirmation",
  "template_status": "PENDING",
  "template_language": "en_US",
  "template_category": "MARKETING"
}

List Templates

Retrieve a paginated list of templates for a WABA. List returns a summary projection of each template — call Get a Template to fetch components, quality_score, and rejected_reason.

GET https://api.plivo.com/v1/Account/{auth_id}/WhatsApp/Template/{waba_id}/

Query Parameters

string

Substring filter on template name.

integer

The number of results per page. The maximum number of results that can be fetched is 20. Defaults to 20.

integer

The number of value items by which the results should be offset. Defaults to 0. Read more about offset-based pagination.

Example

curl "https://api.plivo.com/v1/Account/{auth_id}/WhatsApp/Template/{waba_id}/?limit=20&offset=0" \
  -u '<auth_id>:<auth_token>'

Response

{
  "api_id": "b1c2d3e4-58b6-11e1-86da-77300b68f8bb",
  "status": "success",
  "meta": {
    "limit": 20,
    "offset": 0,
    "next": "/v1/Account/{auth_id}/WhatsApp/Template/{waba_id}/?limit=20&offset=20",
    "previous": null
  },
  "objects": [
    {
      "template_id": "123456789012345",
      "name": "order_confirmation",
      "language": "en_US",
      "category": "MARKETING",
      "status": "APPROVED"
    },
    {
      "template_id": "234567890123456",
      "name": "account_alert_named",
      "language": "en_US",
      "category": "UTILITY",
      "status": "PENDING"
    }
  ]
}

Get a Template

Retrieve the current state of a single template, including its components.

GET https://api.plivo.com/v1/Account/{auth_id}/WhatsApp/Template/{waba_id}/{template_id}/

Example

curl "https://api.plivo.com/v1/Account/{auth_id}/WhatsApp/Template/{waba_id}/123456789012345/" \
  -u '<auth_id>:<auth_token>'

Response

{
  "api_id": "c1d2e3f4-58b6-11e1-86da-77300b68f8bb",
  "template_id": "123456789012345",
  "name": "order_confirmation",
  "language": "en_US",
  "category": "MARKETING",
  "status": "APPROVED",
  "quality_score": { "score": "GREEN" },
  "rejected_reason": "NONE",
  "components": [
    {
      "type": "BODY",
      "text": "Hi {{1}}, your order {{2}} is on its way.",
      "example": {
        "body_text": [["Alex", "ORD-12345"]]
      }
    }
  ]
}

Update a Template

Submit an update to an existing template. The body shape is identical to Create. The template typically transitions back to PENDING while Meta re-reviews; the resulting APPROVED or REJECTED status is delivered to your configured WABA webhook URL.

POST https://api.plivo.com/v1/Account/{auth_id}/WhatsApp/Template/{waba_id}/{template_id}/

Arguments

Same as Create a Template.

Example

curl -X POST "https://api.plivo.com/v1/Account/{auth_id}/WhatsApp/Template/{waba_id}/123456789012345/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_confirmation",
    "language": "en_US",
    "category": "MARKETING",
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{1}}, your order {{2}} has been dispatched.",
        "example": {
          "body_text": [["Alex", "ORD-12345"]]
        }
      }
    ]
  }'

Response

{
  "api_id": "d1e2f3a4-58b6-11e1-86da-77300b68f8bb",
  "status": "success",
  "message": "template update submitted to meta for review",
  "template_id": "123456789012345",
  "template_name": "order_confirmation",
  "template_status": "PENDING",
  "template_language": "en_US",
  "template_category": "MARKETING"
}

Delete a Template

Remove a template from the WABA via Meta. This operation cannot be undone — to reuse the same template name later, you may need to wait out Meta’s name-reuse cooldown.

DELETE https://api.plivo.com/v1/Account/{auth_id}/WhatsApp/Template/{waba_id}/{template_id}/?name={name}

Both template_id (path) and name (query) are required. Meta’s Graph API needs both to delete a specific language variant. Calls missing ?name= are rejected with a 400.

Query Parameters

string

required

The template’s name (the same value you sent on Create or received on List).

Example

curl -X DELETE "https://api.plivo.com/v1/Account/{auth_id}/WhatsApp/Template/{waba_id}/123456789012345/?name=order_confirmation" \
  -u '<auth_id>:<auth_token>'

Response

HTTP Status Code: 204

HTTP Status Codes

Code	Description
200	Request executed successfully.
204	Template deleted (no body).
400	Validation error — missing or invalid parameter.
401	Authentication failed.
404	Template not found.
429	Rate limit exceeded. Rate limits are applied per `auth_id` per endpoint.
502	Upstream service (messaging-whatsapp or Meta) returned a transient failure.

For the canonical error envelope and common error codes, see the Messaging API Response page.

Manage WhatsApp Templates (concept) — UI walkthrough and template structure overview.
Send a Message — Send a templated WhatsApp message once the template is APPROVED.
WhatsApp Prerequisites — WABA setup steps.

Getting Started

Onboarding

Console UI Reference

Messaging

Calling

API Reference

FAQ

WhatsApp Templates API

The WhatsAppTemplate Object

Attributes

Component Object

Example Object

Create a Template

Arguments

Example — Text-only marketing template

Example — Body with named parameters

Example — Image header with media handle

Example — Carousel template

Response

List Templates

Query Parameters

Example

Response

Get a Template

Example

Response

Update a Template

Arguments

Example

Response

Delete a Template

Query Parameters

Example

Response

HTTP Status Codes

​The WhatsAppTemplate Object

​Attributes

​Component Object

​Example Object

​Create a Template

​Arguments

​Example — Text-only marketing template

​Example — Body with named parameters

​Example — Image header with media handle

​Example — Carousel template

​Response

​List Templates

​Query Parameters

​Example

​Response

​Get a Template

​Example

​Response

​Update a Template

​Arguments

​Example

​Response

​Delete a Template

​Query Parameters

​Example

​Response

​HTTP Status Codes

​Related

The WhatsAppTemplate Object

Attributes

Component Object

Example Object

Create a Template

Arguments

Example — Text-only marketing template

Example — Body with named parameters

Example — Image header with media handle

Example — Carousel template

Response

List Templates

Query Parameters

Example

Response

Get a Template

Example

Response

Update a Template

Arguments

Example

Response

Delete a Template

Query Parameters

Example

Response

HTTP Status Codes

Related