Skip to main content

Documentation Index

Fetch the complete documentation index at: https://plivo.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

​
template_id
string
Meta-issued template ID. Use this in path parameters for Get, Update, and Delete.
​
name
string
snake_case template name, unique per WABA. Allowed characters: a-z, 0-9, underscore.
​
language
string
BCP-47 language code. Examples: en, en_US, es_MX.
​
category
string
Template category. Values: MARKETING, UTILITY, AUTHENTICATION.
​
status
string
Current Meta-assigned status. Values: PENDING, APPROVED, REJECTED, PAUSED, DISABLED.
​
quality_score
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.
​
rejected_reason
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.
​
components
array
Ordered list of template sections. See Component object below.

​
Component Object

Each item in components is a TemplateComponent:
​
type
string
Component type. Values: HEADER, BODY, FOOTER, BUTTONS, CAROUSEL.
​
format
string
Header format. Only meaningful when type is HEADER. Values: TEXT, IMAGE, VIDEO, DOCUMENT, LOCATION.
​
text
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.
​
example
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.
​
buttons
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.
​
cards
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

​
name
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.
​
language
string
required
BCP-47 language code (for example, en_US).
​
category
string
required
Values: MARKETING, UTILITY, AUTHENTICATION.
​
components
array
required
Non-empty array of components. At least one BODY component is required; HEADER, FOOTER, BUTTONS, and CAROUSEL are optional. See Component object.
​
allow_category_change
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."
      }
    ]
  }'
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

​
template_name
string
Substring filter on template name.
​
limit
integer
The number of results per page. The maximum number of results that can be fetched is 20. Defaults to 20.
​
offset
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

​
name
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

CodeDescription
200Request executed successfully.
204Template deleted (no body).
400Validation error — missing or invalid parameter.
401Authentication failed.
404Template not found.
429Rate limit exceeded. Rate limits are applied per auth_id per endpoint.
502Upstream service (messaging-whatsapp or Meta) returned a transient failure.
For the canonical error envelope and common error codes, see the Messaging API Response page.