> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beem.africa/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve templates
> Retrieve a paginated list of WhatsApp message templates for your account.
Once templates have been approved, they can be managed and used through the Beem Moja API.
## Retrieve WhatsApp templates
Retrieve a paginated list of WhatsApp message templates associated with your account.
This endpoint helps developers manage templates programmatically and supports flexible filtering through query parameters.
### What you can do
* Retrieve all templates created for your account.
* View templates regardless of approval status.
* Filter templates using supported query parameters.
* Browse templates efficiently using pagination.
Search and filter templates by supported query parameters such as category, language or approval status.
Retrieve templates page by page when working with large template collections.
### Template statuses
Templates returned by this endpoint may have one of the following statuses:
* Pending
* Enabled
* Rejected
* Failed
### Template categories
Templates belong to one of the following categories:
* Authentication
* Utility
* Marketing
Only **Enabled (Approved)** templates can be used to initiate WhatsApp conversations.
***
## Query parameters
| Parameter | Type | Description |
| ---------------- | ------- | ------------------------------------------------------------ |
| `page` | integer | Page number (starts at 1) |
| `limit` | integer | Results per page |
| `q` | string | Search across name, content, header, footer, buttons, and id |
| `category` | string | `AUTHENTICATION`, `UTILITY`, or `MARKETING` |
| `status` | string | `pending`, `enabled`, `rejected`, or `failed` |
| `channel_number` | string | Filter by WhatsApp channel number in template metadata |
| `type` | string | Template type filter |
| `id` | string | Fetch a specific template by Beem ID |
| `botId` | string | Filter by bot / vendor ID (role-dependent) |
| `isFile` | boolean | When `false`, exclude templates with file placeholders |
See [List message templates](/api-reference/moja/list-message-templates) for the interactive API reference.
***
## Response fields
Each object in the `data` array contains:
| Field | Type | Description |
| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | integer | Beem template ID — use as `messageTemplateData.id` when [sending templates](/guides/moja/send-template). Not the same as `template_id` from Meta. |
| `template_id` | string | Template ID assigned by Meta (WhatsApp) after approval. |
| `facebook_template_id` | string | Facebook/Meta platform ID for the approved template. |
| `name` | string | Template name. |
| `category` | string | `AUTHENTICATION`, `UTILITY`, or `MARKETING`. |
| `type` | string | Template type, e.g. `TEXT` or media types. |
| `status` | string | `pending`, `enabled`, `rejected`, or `failed`. |
| `botId` | string | Bot ID associated with the template. |
| `language` | string | Language code, e.g. `en_US`. |
| `content` | string | Message body with `{{1}}`, `{{2}}` placeholders. |
| `mediaUrl` | string | Media URL when the template includes an attachment. |
| `mimeType` | string | MIME type for media templates (`application/pdf`, `video/mp4`, `image/jpeg`, etc.). |
| `buttons` | array | CTA, OTP, or quick-reply button objects. |
| `footer` | string | Footer text. |
| `header` | string | Header text or media header. |
| `metadata` | array | Per-channel approval flags (`failed`, `pending`, `approved`, `rejected`). |
| `createdAt` | string | Creation timestamp (ISO 8601). |
| `updatedAt` | string | Last update timestamp (ISO 8601). |
The `pagination` object includes:
| Field | Type | Description |
| ------------- | ------- | ----------------------------------- |
| `totalItems` | integer | Total templates matching the query. |
| `currentPage` | integer | Current page number. |
| `totalPages` | integer | Total pages available. |
***
## Sample responses
```json theme={null}
{
"data": [
{
"id": 10913,
"template_id": "fbce0d08-4ecb-456c-9c13-a709767396531",
"facebook_template_id": "107484765349667",
"type": "TEXT",
"category": "AUTHENTICATION",
"name": "auth_template_api1",
"botId": "9a87df7c-0fcd-42fb-9a69-66c58ff66a92",
"status": "",
"language": "en_US",
"content": "{{1}} is your verification code. For your security, do not share this code.",
"mediaUrl": null,
"mimeType": null,
"buttons": [
{
"type": "OTP",
"otp_type": "COPY_CODE",
"text": "COPY OTP"
}
],
"footer": "The code will expire in 1min",
"header": null,
"metadata": [
{
"failed": true,
"pending": true,
"approved": false,
"rejected": false
}
],
"createdAt": "2024-09-05T09:01:22.000Z",
"updatedAt": "2024-09-05T10:48:53.000Z"
}
],
"pagination": {
"totalItems": 150,
"currentPage": 1,
"totalPages": 6
}
}
```
```json theme={null}
{
"data": [
{
"id": 10826,
"template_id": "4829bf2d-2bd5-451d-a297-55111ebb4111",
"facebook_template_id": "107484761119667",
"type": "TEXT",
"category": "AUTHENTICATION",
"name": "beemsupporttest2",
"botId": "9a87df7c-0fcd-11fb-9a69-66c58ff11a11",
"status": "requested",
"language": "ar",
"content": "{{1}} is your verification code.",
"mediaUrl": null,
"mimeType": null,
"buttons": [
{
"type": "OTP",
"otp_type": "COPY_CODE",
"text": "COPY OTP"
}
],
"footer": "The code will expire in 1min",
"header": null,
"metadata": null,
"createdAt": "2024-08-26T08:38:04.000Z",
"updatedAt": "2024-08-26T08:38:04.000Z"
}
]
}
```
```json theme={null}
{
"data": [
{
"id": 10911,
"template_id": "a446bab9-9d2b-4144-8e3d-86940a4c99533",
"facebook_template_id": "107484765333667",
"type": "text",
"category": "MARKETING",
"name": "marketing_api_test",
"botId": "9a87df7c-0fcd-42fb-9a69-66c58ff66a92",
"status": "",
"language": "en_US",
"content": "From your account saving {{1}} received free {{2}}",
"mediaUrl": null,
"mimeType": null,
"buttons": [
{
"type": "PHONE_NUMBER",
"text": "number",
"phone_number": "255782270052"
}
],
"footer": "powered by us",
"header": "Hi {{1}}",
"metadata": [
{
"failed": false,
"pending": true,
"approved": true,
"rejected": false
}
],
"createdAt": "2024-09-05T06:48:49.000Z",
"updatedAt": "2024-09-05T10:49:53.000Z"
}
]
}
```
```json theme={null}
{
"data": [
{
"id": 1024,
"template_id": "uuid-here",
"facebook_template_id": "107484765349667",
"type": "IMAGE",
"category": "MARKETING",
"name": "apple_marketing",
"botId": "9a87df7c-0fcd-42fb-9a69-66c58ff66a92",
"status": "enabled",
"language": "en_US",
"content": "Check out our latest offer {{1}}",
"mediaUrl": "https://example.com/promo.jpg",
"mimeType": "image/jpeg",
"buttons": [],
"footer": null,
"header": "Special offer",
"createdAt": "2024-09-01T10:00:00.000Z",
"updatedAt": "2024-09-01T10:00:00.000Z"
}
]
}
```