> ## Documentation Index
> Fetch the complete documentation index at: https://docs.minimo.it/llms.txt
> Use this file to discover all available pages before exploring further.

# List WhatsApp Templates

> Retrieve all WhatsApp templates and their approval status

## Overview

Get a list of all WhatsApp templates in your Minimo account, including their approval status, category, and available components.

Use this endpoint to:

* Check which templates are approved and ready to send
* Display available templates in your application
* Monitor template approval status
* Verify template structure before sending messages

<Tip>
  Before sending messages, make sure to connect a WhatsApp Business Account by visiting the **Channels** section at
  [app.minimo.it/channels](https://app.minimo.it/channels).
</Tip>

## Response Structure

```json theme={null}
{
  "data": [
    {
      "id": "tmpl_whatsapp_123",
      "name": "order_confirmation",
      "language": "en",
      "status": "APPROVED",
      "category": "UTILITY",
      "namespace": "e33bca12_1234_4567_abcd_abcdef123456",
      "createdAt": "2025-10-01T10:00:00Z",
      "updatedAt": "2025-10-05T14:30:00Z",
      "qualityScore": {
        "score": "GREEN",
        "reasons": null
      },
      "components": [
        {
          "type": "HEADER",
          "format": "TEXT",
          "text": "Order Confirmation"
        },
        {
          "type": "BODY",
          "text": "Hello {{1}}, your order {{2}} has been confirmed!",
          "example": {
            "bodyText": [["John Doe", "ORD-12345"]]
          }
        },
        {
          "type": "FOOTER",
          "text": "Reply STOP to opt out"
        }
      ]
    }
  ]
}
```

## Template Status

WhatsApp templates can have different statuses:

| Status     | Description                | Can Send? |
| ---------- | -------------------------- | --------- |
| `APPROVED` | Template approved by Meta  | ✅ Yes     |
| `PENDING`  | Waiting for Meta approval  | ❌ No      |
| `REJECTED` | Meta rejected the template | ❌ No      |
| `DISABLED` | Disabled by you or Meta    | ❌ No      |

<Info>
  Only templates with `status: "APPROVED"` can be used to send messages. Check this field before attempting to send.
</Info>

## Template Categories

| Category         | Description           | Use Cases                                                  |
| ---------------- | --------------------- | ---------------------------------------------------------- |
| `UTILITY`        | Transactional updates | Order status, booking confirmations, account notifications |
| `AUTHENTICATION` | Security codes        | OTP, 2FA verification, password resets                     |
| `MARKETING`      | Promotional content   | Product launches, special offers, newsletters              |

## Quality Score

Meta assigns a quality score based on how users interact with your messages:

| Score     | Meaning        | Impact                 |
| --------- | -------------- | ---------------------- |
| `GREEN`   | High quality   | Full sending capacity  |
| `YELLOW`  | Medium quality | Monitoring required    |
| `RED`     | Low quality    | Reduced sending limits |
| `UNKNOWN` | Not yet rated  | New template           |

<Warning>
  Templates with `RED` quality scores may be paused or have limited sending capacity. Improve message quality to restore
  full access.
</Warning>

**Quality score can decline due to**:

* High block rates (users blocking your number)
* Low engagement (users not responding)
* Spam reports
* Irrelevant content

## Template Components

Templates consist of multiple components:

### Header

* **Optional** element at the top
* Can be: TEXT, IMAGE, VIDEO, or DOCUMENT
* Single variable allowed (for dynamic content)

### Body

* **Required** main message content
* Supports multiple variables (`{{1}}`, `{{2}}`, etc.)
* Maximum 1024 characters

### Footer

* **Optional** additional text at the bottom
* No variables allowed
* Often used for opt-out instructions

### Buttons

* **Optional** interactive elements
* Types: Call-to-action, Quick reply, URL
* Up to 3 buttons per template

## Use Cases

### Check Template Approval Status

Monitor when templates are approved:

```javascript theme={null}
async function waitForApproval(templateName) {
  const maxAttempts = 48; // Check for 48 hours
  const intervalHours = 1;

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch('https://api.minimo.it/public/v1/templates/whatsapp', {
      headers: {
        Authorization: `Bearer ${apiKey}`,
      },
    });

    const { data: templates } = await response.json();
    const template = templates.find((t) => t.name === templateName);

    if (template?.status === 'APPROVED') {
      console.log(`Template "${templateName}" is now approved!`);
      return true;
    } else if (template?.status === 'REJECTED') {
      console.error(`Template "${templateName}" was rejected`);
      return false;
    }

    // Wait 1 hour before checking again
    await new Promise((resolve) => setTimeout(resolve, intervalHours * 60 * 60 * 1000));
  }

  console.error('Template approval timeout');
  return false;
}
```

### Build Template Selector

Display only approved templates:

```javascript theme={null}
async function getApprovedTemplates() {
  const response = await fetch('https://api.minimo.it/public/v1/templates/whatsapp', {
    headers: {
      Authorization: `Bearer ${apiKey}`,
    },
  });

  const { data: templates } = await response.json();

  // Filter only approved templates
  return templates.filter((t) => t.status === 'APPROVED');
}

// Use in UI
const approvedTemplates = await getApprovedTemplates();
approvedTemplates.forEach((template) => {
  console.log(`${template.name} - ${template.category}`);
});
```

### Extract Template Variables

Parse template components to find required variables:

```javascript theme={null}
function getTemplateVariables(template) {
  const bodyComponent = template.components.find((c) => c.type === 'BODY');
  if (!bodyComponent) return [];

  // Extract {{1}}, {{2}}, etc.
  const matches = bodyComponent.text.match(/\{\{(\d+)\}\}/g);
  if (!matches) return [];

  return matches.map((m) => parseInt(m.match(/\d+/)[0]));
}

// Example usage
const template = templates.find((t) => t.name === 'order_confirmation');
const variables = getTemplateVariables(template);
console.log(`Template requires ${variables.length} variables:`, variables);
// Output: Template requires 2 variables: [1, 2]
```

## Filtering & Sorting (Coming Soon)

Future versions will support:

```bash theme={null}
# Filter by status
GET /api/templates/whatsapp?status=APPROVED

# Filter by category
GET /api/templates/whatsapp?category=UTILITY

# Sort by creation date
GET /api/templates/whatsapp?sort=-createdAt
```

## Template Languages

WhatsApp templates can be created in multiple languages:

```json theme={null}
{
  "name": "order_confirmation",
  "language": "en",
  "status": "APPROVED"
}
```

**Supported language codes**:

* `en` - English
* `it` - Italian
* `es` - Spanish
* `fr` - French
* `de` - German
* `pt` - Portuguese
* And 60+ more...

<Info>
  Create separate templates for each language you want to support. Use the same `name` with different `language` codes.
</Info>

## Common Errors

| Error                 | Cause                  | Solution                               |
| --------------------- | ---------------------- | -------------------------------------- |
| `unauthorized`        | Invalid API key        | Check Authorization header             |
| `no_whatsapp_account` | WhatsApp not connected | Connect WhatsApp in dashboard          |
| `rate_limit_exceeded` | Too many requests      | Implement caching, respect rate limits |

## Best Practices

<AccordionGroup>
  <Accordion title="Cache Template List">
    Templates don't change frequently. Cache the response:

    ```javascript theme={null}
    const CACHE_DURATION = 15 * 60 * 1000; // 15 minutes
    let templateCache = null;
    let cacheTime = 0;

    async function getTemplates() {
      if (templateCache && Date.now() - cacheTime < CACHE_DURATION) {
        return templateCache;
      }
      
      const response = await fetch('https://api.minimo.it/public/v1/templates/whatsapp', {
        headers: { 'Authorization': `Bearer ${apiKey}` },
      });
      
      templateCache = await response.json();
      cacheTime = Date.now();
      
      return templateCache;
    }
    ```
  </Accordion>

  <Accordion title="Monitor Quality Scores">
    Regularly check template quality to prevent issues:

    ```javascript theme={null}
    async function checkTemplateHealth() {
      const { data: templates } = await getTemplates();
      
      const unhealthy = templates.filter(t => 
        t.qualityScore.score === 'RED' || t.qualityScore.score === 'YELLOW'
      );
      
      if (unhealthy.length > 0) {
        console.warn('Templates need attention:', unhealthy.map(t => t.name));
        // Send alert to team
      }
    }
    ```
  </Accordion>

  <Accordion title="Validate Before Sending">
    Always verify template is approved before sending:

    ```javascript theme={null}
    async function canSendTemplate(templateName) {
      const { data: templates } = await getTemplates();
      const template = templates.find(t => t.name === templateName);
      
      return template && template.status === 'APPROVED';
    }
    ```
  </Accordion>
</AccordionGroup>

## Related Endpoints

* [Send WhatsApp Template](/api-reference/messaging-channels/whatsapp/send-template) - Send messages using templates


## OpenAPI

````yaml get /public/v1/templates/whatsapp
openapi: 3.1.0
info:
  title: API Documentation
  description: Documentation for transactional and subscribe APIs
  version: 1.0.0
servers:
  - url: https://app.minimo.it
security:
  - bearerAuth: []
paths:
  /public/v1/templates/whatsapp:
    servers:
      - url: https://api.minimo.it
    get:
      summary: List all WhatsApp templates
      operationId: listWhatsappTemplates
      responses:
        '200':
          description: Successful response with WhatsApp templates
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/WhatsappTemplate'
        '400':
          description: Invalid or missing authentication token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Missing API client ID or API key
        '404':
          description: Company not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Company not found
      security:
        - bearerAuth: []
components:
  schemas:
    WhatsappTemplate:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        language:
          type: string
        status:
          type: string
        category:
          type: string
          enum:
            - AUTHENTICATION
            - MARKETING
            - UTILITY
        namespace:
          type: string
        waba_account_id:
          type: string
        partner_id:
          type: string
        created_at:
          type: string
          format: date-time
        modified_at:
          type: string
          format: date-time
        updated_external:
          type: boolean
        rejected_reason:
          type: string
        external_id:
          type: string
        created_by:
          $ref: '#/components/schemas/WhatsappTemplateActor'
        modified_by:
          $ref: '#/components/schemas/WhatsappTemplateActor'
        quality_score:
          type: object
          properties:
            reasons:
              type: array
              nullable: true
              items:
                type: string
            score:
              type: string
              enum:
                - UNKNOWN
                - GREEN
                - YELLOW
                - RED
        components:
          type: array
          items:
            $ref: '#/components/schemas/WhatsappTemplateComponent'
      example:
        id: tmpl_82jh2asjda
        name: order_confirmation
        language: en
        status: APPROVED
        category: MARKETING
        namespace: e33bca12_1234_4567_abcd_abcdef123456
        waba_account_id: '1234567890'
        partner_id: '987654321'
        created_at: '2024-12-01T10:00:00Z'
        modified_at: '2024-12-03T15:30:00Z'
        updated_external: true
        rejected_reason: ''
        external_id: EXT123456789
        created_by:
          user_id: user_abc123
          user_name: jane.doe
        modified_by:
          user_id: user_xyz789
          user_name: john.smith
        quality_score:
          reasons:
            - LOW_ENGAGEMENT
          score: GREEN
        components:
          - type: BODY
            text: Hello {{1}}, your order {{2}} has been confirmed!
            example:
              body_text:
                - - Jane
                  - ORD-12345
    WhatsappTemplateActor:
      type: object
      properties:
        user_id:
          type: string
        user_name:
          type: string
      example:
        user_id: user_abc123
        user_name: jane.doe
    WhatsappTemplateComponent:
      type: object
      properties:
        type:
          type: string
          enum:
            - HEADER
            - BODY
            - FOOTER
            - BUTTONS
        text:
          type: string
        format:
          type: string
          enum:
            - IMAGE
            - VIDEO
            - DOCUMENT
        buttons:
          type: array
          items:
            $ref: '#/components/schemas/WhatsappTemplateButton'
        example:
          type: object
          properties:
            body_text:
              type: array
              items:
                type: array
                items:
                  type: string
      example:
        type: BODY
        text: Hi {{1}}, your verification code is {{2}}
        example:
          body_text:
            - - Alice
              - '123456'
    WhatsappTemplateButton:
      type: object
      properties:
        type:
          type: string
          enum:
            - QUICK_REPLY
            - URL
        text:
          type: string
        url:
          type: string
      example:
        type: URL
        text: Track your order
        url: https://yourdomain.com/track/{{1}}
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: mn-API_CLIENT_ID-API_KEY

````