Retrieve templates

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.

Filtering

Search and filter templates by supported query parameters such as category, language or approval status.

Pagination

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 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. 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

Paginated list
Authentication template
Marketing / Utility (text)
Marketing / Utility (image)

{
  "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
  }
}

{
  "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"
    }
  ]
}

{
  "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"
    }
  ]
}

{
  "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"
    }
  ]
}

Getting Started

APIs

Retrieve templates

Retrieve WhatsApp templates

What you can do

Filtering

Pagination

Template statuses

Template categories

Query parameters

Response fields

Sample responses

​Retrieve WhatsApp templates

​What you can do

Filtering

Pagination

​Template statuses

​Template categories

​Query parameters

​Response fields

​Sample responses

Retrieve WhatsApp templates

What you can do

Template statuses

Template categories

Query parameters

Response fields

Sample responses