> For the complete documentation index, see [llms.txt](https://help.botpenguin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.botpenguin.com/api-documentation/whatsapp-cloud-api/get-templates-list.md). # GET — Templates List ### 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 | {% hint style="info" %} 🔑 **Where to get your API Key:** Navigate to **Dashboard → Settings → API Access**.\ For full auth setup, see the [API Authentication Guide.](/bots/whatsapp-bot/whatapp-chatbot-settings/api-key-settings.md) {% endhint %} *** ### 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 ```bash 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. ```json { "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: `+919876543210`. | | `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](https://developers.facebook.com/docs/whatsapp/on-premises/errors) *** ### 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* [*support@botpenguin.com*](mailto:support@botpenguin.com)