GET — Templates List

Retrieve all WhatsApp templates associated with a bot, across all statuses — APPROVED, PENDING, REJECTED, and DRAFT. Use this to render, manage, or trigger templates programmatically.

Overview

Property	Details
Method	GET
Endpoint	https://api.v7.botpenguin.com/whatsapp-automation/wa/templates
Base URL	https://api.v7.botpenguin.com
API Version	v7
Auth Required	Yes — API Key
Content-Type	Not required for GET

---

Authentication

BotPenguin APIs use an API Key for authentication. Pass it in both the request header and as a query parameter.

Method	Location	Key	Value
API Key	Request Header	apiKey	Your BotPenguin WA Chatbot API Key
API Key	Query Parameter	apiKey	Your BotPenguin WA Chatbot API Key

🔑 Where to get your API Key: Navigate to Dashboard → Settings → API Access. For full auth setup, see the API Authentication Guide.

---

Request

Headers

Header	Required	Value
apiKey	✅ Yes	Your BotPenguin WA Chatbot API Key

Query Parameters

Parameter	Type	Required	Description
apiKey	string	✅ Yes	Your BotPenguin WA Chatbot API Key

---

Example Request

curl --location 'https://api.v7.botpenguin.com/whatsapp-automation/wa/templates?apiKey=YOUR_API_KEY' \
--header 'apiKey: YOUR_API_KEY'

---

Response

Success — 200 OK

The response returns an array of all templates for the bot. The example below shows one REGULAR template and one CAROUSEL template, followed by a DRAFT and a REJECTED to illustrate all possible statuses.

{
  "success": true,
  "data": [
    {
      "_id": "691305fe3c261eed3246ef8e",
      "_user": "5fed38e56fb193dcc6c933f5",
      "_bot": "690823e884ec34b46d906126",
      "templateId": "1377958567099477",
      "configuration": {
        "name": "appointment_reminder_notification",
        "category": "MARKETING",
        "language": "en",
        "parameterFormat": "positional",
        "components": [
          {
            "type": "HEADER",
            "format": "TEXT",
            "text": "Appointment Reminder"
          },
          {
            "type": "BODY",
            "text": "Hi {{1}}, this is a reminder for your appointment scheduled on {{2}} at {{3}}.\nPlease confirm if you'll be able to attend.",
            "example": {
              "body_text": [["user", "16 November, 2025", "3 pm"]]
            }
          },
          {
            "type": "FOOTER",
            "text": "Reply STOP to unsubscribe."
          }
        ]
      },
      "status": "APPROVED",
      "headerMediaUrl": "",
      "triggerConfig": [],
      "carousalHeaderUrls": [],
      "templateType": "REGULAR",
      "createdAt": "2025-11-11T09:46:38.422Z",
      "updatedAt": "2025-11-11T09:46:38.422Z",
      "__v": 0
    },
    {
      "_id": "69b7f8f9252c302124846734",
      "_user": "5fed38e56fb193dcc6c933f5",
      "_bot": "678a12ce47a2bd8d197eb432",
      "templateId": "1492838505037557",
      "configuration": {
        "name": "carousel_offer_template",
        "category": "MARKETING",
        "language": "en",
        "parameterFormat": "positional",
        "components": [
          {
            "type": "BODY",
            "text": "Special offer for you, {{1}}. Use the code below.",
            "example": {
              "body_text": [["Sahil"]]
            }
          },
          {
            "type": "CAROUSEL",
            "cards": [
              {
                "components": [
                  {
                    "type": "HEADER",
                    "format": "IMAGE",
                    "example": {
                      "header_handle": ["https://scontent.whatsapp.net/..."]
                    }
                  },
                  {
                    "type": "BODY",
                    "text": "Plan SILVER — 2 passengers, 11 days, $1,585."
                  },
                  {
                    "type": "BUTTONS",
                    "buttons": [
                      {
                        "type": "URL",
                        "text": "Choose",
                        "url": "https://example.com/{{1}}",
                        "example": ["https://example.com/plan/silver"]
                      }
                    ]
                  }
                ]
              }
            ]
          }
        ]
      },
      "status": "APPROVED",
      "headerMediaUrl": "",
      "triggerConfig": [],
      "carousalHeaderUrls": [
        "https://static-assets-v2.s3.us-east-2.amazonaws.com/uploads/image1.jpg"
      ],
      "templateType": "CAROUSEL",
      "createdAt": "2026-03-16T12:35:05.255Z",
      "updatedAt": "2026-03-16T12:35:05.255Z",
      "__v": 0
    },
    {
      "_id": "69b92efda1482bc9b5d032f2",
      "_user": "5fed38e56fb193dcc6c933f5",
      "_bot": "678a12ce47a2bd8d197eb432",
      "templateId": "",
      "configuration": {
        "name": "webinar_reminder",
        "category": "UTILITY",
        "language": "en",
        "parameterFormat": "positional",
        "components": [
          {
            "type": "BODY",
            "text": "Hey {{1}}, thanks for registering for {{2}}! Join at: {{3}}",
            "example": {
              "body_text": [["name", "webinar_name", "join_link"]]
            }
          }
        ]
      },
      "status": "DRAFT",
      "headerMediaUrl": "",
      "triggerConfig": [],
      "carousalHeaderUrls": [],
      "templateType": "REGULAR",
      "createdAt": "2026-03-17T10:37:49.828Z",
      "updatedAt": "2026-03-17T10:37:49.828Z",
      "__v": 0
    },
    {
      "_id": "6a18321eb4ed3f637d61aa23",
      "_user": "5fed38e56fb193dcc6c933f5",
      "_bot": "678a12ce47a2bd8d197eb432",
      "templateId": "1517754233121941",
      "configuration": {
        "name": "test_otp",
        "category": "AUTHENTICATION",
        "language": "en_US",
        "parameterFormat": "named",
        "components": [
          {
            "type": "BODY",
            "text": "*{{1}}* is your verification code. For your security, do not share this code.",
            "add_security_recommendation": true,
            "example": {
              "body_text": [["123456"]]
            }
          },
          {
            "type": "FOOTER",
            "text": "Expires in 5 minutes.",
            "code_expiration_minutes": 5
          },
          {
            "type": "BUTTONS",
            "buttons": [
              {
                "type": "URL",
                "text": "Copy Code",
                "url": "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code_expiration_minutes=5&code=otp{{1}}",
                "example": ["https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code_expiration_minutes=5&code=otp123456"]
              }
            ]
          }
        ]
      },
      "status": "REJECTED",
      "headerMediaUrl": "",
      "triggerConfig": [],
      "carousalHeaderUrls": [],
      "templateType": "REGULAR",
      "createdAt": "2026-05-28T12:16:30.164Z",
      "updatedAt": "2026-05-28T12:16:30.164Z",
      "__v": 0
    }
  ]
}

---

Response Fields

Root Level

Field	Type	Description
success	boolean	true if the request was successful.
data	array	List of all WhatsApp templates for the bot, across all statuses.

---

data[] — Template Object

Field	Type	Description
_id	string	Unique identifier of this template record in BotPenguin.
_user	string	ID of the BotPenguin user (account) who owns the template.
_bot	string	ID of the bot this template is linked to.
templateId	string	WhatsApp (Meta) template ID. Empty string "" for DRAFT templates not yet submitted to Meta.
configuration	object	Full template content and structure. See configuration object below.
status	string	Current approval status. Possible values: APPROVED, PENDING, REJECTED, DRAFT.
headerMediaUrl	string	BotPenguin-hosted URL of the media uploaded for the header. Empty if no media or if using a Meta CDN handle.
triggerConfig	array	Bot flow trigger rules linked to quick reply buttons. Empty if no triggers are configured. See triggerConfig[] below.
carousalHeaderUrls	array	BotPenguin-hosted image URLs for carousel card headers. Populated for CAROUSEL type templates.
templateType	string	Template type. Values: REGULAR, CAROUSEL.
createdAt	string (ISO 8601)	Timestamp when the template record was created.
updatedAt	string (ISO 8601)	Timestamp when the template record was last updated.
__v	number	Internal document versioning field. Not for application use.

---

configuration Object

Field	Type	Description
name	string	Template name registered with WhatsApp. Lowercase, underscores only.
category	string	Template category. Values: MARKETING, UTILITY, AUTHENTICATION.
subCategory	string	(Optional) Sub-category, if applicable. Example: CUSTOM.
language	string	BCP-47 language code. Examples: en, en_US, es, zh_TW.
parameterFormat	string	Variable format used in the template. Values: positional ({{1}}, {{2}}), named ({{name}}, {{key}}). Both are supported.
components	array	Ordered list of message components. See components[] below.

---

components[] Object

Field	Type	Description
type	string	Component type. Values: HEADER, BODY, FOOTER, BUTTONS, CAROUSEL, CALL_PERMISSION_REQUEST.
format	string	(HEADER only) Media format. Values: TEXT, IMAGE, VIDEO, DOCUMENT, LOCATION.
text	string	Text content of the component. Supports dynamic variables in {{1}} or {{name}} format.
add_security_recommendation	boolean	(BODY, AUTHENTICATION only) When true, appends a security disclaimer to the message.
code_expiration_minutes	number	(FOOTER, AUTHENTICATION only) OTP expiry duration in minutes.
buttons	array	(BUTTONS only) List of interactive buttons. See buttons[] below.
cards	array	(CAROUSEL only) List of carousel cards. Each card contains its own components array with HEADER, BODY, and BUTTONS. See cards[] below.
example	object	Sample variable values for preview. See example object below.

---

buttons[] Object

Field	Type	Description
type	string	Button type. Values: QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE, CATALOG.
text	string	Button display label shown to the user.
url	string	(URL buttons only) Destination URL. Supports dynamic suffix via {{1}}.
phone_number	string	(PHONE_NUMBER buttons only) Phone number with country code. Example: [phone].
example	array	Sample values for dynamic variables in the button URL or copy code.

---

cards[] Object (CAROUSEL templates only)

Each card in a carousel is a self-contained unit with its own component structure.

Field	Type	Description
components	array	Components for this carousel card. Follows the same components[] structure above. Each card must contain a HEADER (image), BODY, and BUTTONS.

---

example Object

Provides sample values used when previewing templates with dynamic variables.

Field	Type	Description
body_text	array	(Positional format) Array of sample values for {{1}}, {{2}}, etc. in the body.
header_text	array	(Positional format) Sample value for a dynamic {{1}} in a text header.
header_handle	array	URL or handle of the sample media used in an image, video, or document header.
body_text_named_params	array	(Named format) Array of {param_name, example} objects for named body variables.
header_text_named_params	array	(Named format) Array of {param_name, example} objects for named header variables.

---

triggerConfig[] Object

Defines which bot flow is triggered when a user taps a specific quick reply button.

Field	Type	Description
text	string	The quick reply button text that triggers this flow. Must match the button text exactly.
flow	string	ID of the bot flow to trigger when this button is tapped.
_id	string	Unique identifier of this trigger rule.

---

Template Status Reference

Status	Description
APPROVED	Template approved by Meta and ready to send.
PENDING	Template submitted to Meta and awaiting review.
REJECTED	Template rejected by Meta. Review Meta's rejection reason before resubmitting.
DRAFT	Template saved in BotPenguin but not yet submitted to Meta. templateId will be empty.

---

Parameter Format Reference

BotPenguin supports two variable formats in template content:

Format	Syntax	Example
Positional	{{1}}, {{2}}	Hi {{1}}, your order {{2}} is ready.
Named	{{name}}, {{key}}	Hi {{name}}, your order {{order_id}} is ready.

Both formats are fully supported. The format used is reflected in the parameterFormat field of the configuration object.

---

HTTP Status Codes

Code	Status	Meaning
200	OK	Request succeeded. Templates returned in data array.
401	Unauthorized	API key is missing, invalid, or expired.
403	Forbidden	Valid key but insufficient permissions for this bot.
404	Not Found	Bot not found for the given API key.
429	Too Many Requests	Rate limit exceeded. Retry after the indicated window.
500	Internal Server Error	Server-side error. Contact support if it persists.

---

Error Handling

Errors from this endpoint originate from BotPenguin's API layer. For errors related to template submission or approval status, refer to Meta's official error documentation:

📄 WhatsApp On-Premises Error Codes — Meta for Developers

---

Rate Limits

This endpoint is limited to 100 requests per minute per API key, across all plans. Exceeding this returns 429 Too Many Requests. Use the Retry-After response header (in seconds) to schedule your retry.

---

For questions or issues, contact [e-mail]