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

# Template Management API

> Official documentation for managing WhatsApp message templates

## Introduction

Template management endpoints allow you to retrieve, inspect, and create WhatsApp message templates. Templates are pre-approved message formats required by WhatsApp for business communications.

***

## 📋 Get Available Templates

Retrieve all templates available for your company and phone number.

### Endpoint

```
GET https://cloud.lovi.ai/functions/v1/notify/templates?access_key={YOUR_ACCESS_KEY}&phone_number={PHONE_NUMBER}
```

### Query Parameters

| Parameter      | Required | Description                                          |
| -------------- | -------- | ---------------------------------------------------- |
| `access_key`   | Yes      | Your unique API access key.                          |
| `phone_number` | Yes      | Phone number to filter templates (without '+' sign). |

**Example Request:**

```
GET https://cloud.lovi.ai/functions/v1/notify/templates?access_key=your-api-key&phone_number=34666033135
```

### Response

The API returns an **array** of template objects (not wrapped in an object).

```json theme={null}
[
  {
    "id": "696796403510039",
    "name": "welcome_message",
    "status": "APPROVED",
    "category": "MARKETING",
    "language": "en",
    "components": [
      {
        "text": "Welcome! This is a test message.",
        "type": "BODY"
      }
    ],
    "parameter_format": "POSITIONAL"
  },
  {
    "id": "1269099831552940",
    "name": "order_confirmation",
    "status": "APPROVED",
    "category": "MARKETING",
    "language": "es",
    "components": [
      {
        "text": "Hello `{"{1}"}`, your order `{"{2}"}` is ready!",
        "type": "BODY",
        "example": {
          "body_text": [["John", "Premium Package"]]
        }
      }
    ],
    "parameter_format": "POSITIONAL"
  },
  {
    "id": "2616178978766893",
    "name": "promo_with_image",
    "status": "APPROVED",
    "category": "MARKETING",
    "language": "es",
    "components": [
      {
        "type": "HEADER",
        "format": "IMAGE",
        "example": {
          "header_handle": ["https://example.com/image.jpg"]
        }
      },
      {
        "text": "Check out our special offer!",
        "type": "BODY"
      },
      {
        "text": "Thank you for choosing us!",
        "type": "FOOTER"
      }
    ],
    "parameter_format": "POSITIONAL"
  }
]
```

**Important Notes:**

* Response is a **direct array**, not an object with a "templates" key
* `status` values are in **UPPERCASE**: `"APPROVED"`, `"PENDING"`, `"REJECTED"`
* `category` values are in **UPPERCASE**: `"MARKETING"`, `"UTILITY"`, `"AUTHENTICATION"`
* Each template includes `parameter_format` (typically `"POSITIONAL"`)
* `components` array shows the template structure but NOT which components are dynamic

***

## 🔍 Get Template Components

Retrieve detailed information about a specific template's components and structure.

### Endpoint

```
GET https://cloud.lovi.ai/functions/v1/notify/template/components?access_key={YOUR_ACCESS_KEY}&template={TEMPLATE_ID}
```

### Query Parameters

| Parameter    | Required | Description                          |
| ------------ | -------- | ------------------------------------ |
| `access_key` | Yes      | Your unique API access key.          |
| `template`   | Yes      | ID or name of the template to query. |

**Example Request:**

```
GET https://cloud.lovi.ai/functions/v1/notify/template/components?access_key=your-api-key&template=template_001
```

### Response

This endpoint returns ONLY the **dynamic components** that you need to provide when sending a notification.

```json theme={null}
{
  "status": "OK",
  "components": ["header_image", "body_text_0", "body_text_1"]
}
```

**Response Structure:**

* `status`: Always `"OK"` if successful
* `components`: **Array of strings** listing the dynamic component names you must provide

**Example Responses:**

**Template with image header and 2 body variables:**

```json theme={null}
{
  "status": "OK",
  "components": ["header_image", "body_text_0", "body_text_1"]
}
```

**Template with only body variables (no media):**

```json theme={null}
{
  "status": "OK",
  "components": ["body_text_0", "body_text_1"]
}
```

**Template with static content only (no dynamic components):**

```json theme={null}
{
  "status": "OK",
  "components": []
}
```

**Template with video header:**

```json theme={null}
{
  "status": "OK",
  "components": ["header_video"]
}
```

**Template with PDF document:**

```json theme={null}
{
  "status": "OK",
  "components": ["header_document"]
}
```

**Template with dynamic URL button:**

```json theme={null}
{
  "status": "OK",
  "components": ["buttons_url_0"]
}
```

**Important Notes:**

* This endpoint does NOT return the full template structure
* It only returns the **names** of components you need to provide when sending the notification
* Footer and static buttons are NOT included (they're static in the template)
* Component names follow the pattern:
  * Headers: `header_image`, `header_video`, `header_document` (no suffix number)
  * Body variables: `body_text_0`, `body_text_1`, `body_text_N` (with index)
  * Button URLs: `buttons_url_0`, `buttons_url_1` (with index)

***

## 🆕 Create New Template

Create a new WhatsApp message template for approval by Meta.

### Endpoint

```
POST https://cloud.lovi.ai/functions/v1/admin/whatsapp/create/template
```

### Headers

| Key          | Value            | Required | Description                                        |
| ------------ | ---------------- | -------- | -------------------------------------------------- |
| Content-Type | application/json | Yes      | Indicates that the request body is in JSON format. |

### Body Request

```json theme={null}
{
  "company_id": "uuid-company",
  "waba_id": "whatsapp-business-account-id",
  "name_template": "nuevo_template",
  "language_template": "es_ES",
  "category_template": "MARKETING",
  "components_template": {
    "HEADER": {
      "format": "TEXT",
      "text": "Important: {1}"
    },
    "BODY": {
      "text": "Hello {1}, we inform you that {2}. For more information visit {3}."
    },
    "FOOTER": {
      "text": "Support Team"
    },
    "BUTTONS": [
      {
        "type": "URL",
        "text": "View Details",
        "url": "https://example.com/details/{1}"
      },
      {
        "type": "QUICK_REPLY",
        "text": "Contact Support"
      }
    ]
  }
}
```

### Required Parameters

| Parameter             | Type   | Description                                 | Example                    |
| --------------------- | ------ | ------------------------------------------- | -------------------------- |
| `company_id`          | String | Unique company identifier                   | `"uuid-company"`           |
| `waba_id`             | String | WhatsApp Business Account ID                | `"123456789"`              |
| `name_template`       | String | Template name (lowercase, underscores only) | `"order_confirmation"`     |
| `language_template`   | String | Language code                               | `"es_ES"`, `"en_US"`       |
| `category_template`   | String | Template category                           | `"MARKETING"`, `"UTILITY"` |
| `components_template` | Object | Template components structure               | See example above          |

### Template Categories

| Category         | Description                        | Use Case                 |
| ---------------- | ---------------------------------- | ------------------------ |
| `MARKETING`      | Promotional messages               | Offers, announcements    |
| `UTILITY`        | Transactional, functional messages | Order updates, alerts    |
| `AUTHENTICATION` | Security and verification messages | OTP codes, confirmations |

### Component Types

#### HEADER

* **format**: `"TEXT"`, `"IMAGE"`, `"VIDEO"`, `"DOCUMENT"`
* **text**: Text content (only for TEXT format)
* **example**: Example for variables

#### BODY

* **text**: Main message content
* **Variables**: Use `{1}`, `{2}`, etc. for dynamic content (single braces in template creation)

#### FOOTER

* **text**: Footer text (static only, no variables)

#### BUTTONS

Array of button objects:

**URL Button:**

```json theme={null}
{
  "type": "URL",
  "text": "Button Text",
  "url": "https://example.com/{1}"
}
```

**Quick Reply Button:**

```json theme={null}
{
  "type": "QUICK_REPLY",
  "text": "Button Text"
}
```

### Response

```json theme={null}
{
  "success": true,
  "message": "Template created successfully",
  "template": {
    "id": "new_template_id",
    "name": "nuevo_template",
    "status": "pending",
    "submitted_at": "2024-12-25T10:00:00Z"
  }
}
```

### Template Approval Process

1. **Submission**: Template is sent to Meta for review
2. **Review**: Meta reviews template (usually 24-48 hours)
3. **Approval/Rejection**: Template is approved or rejected with feedback
4. **Usage**: Approved templates can be used in notifications

### Template Status Values

| Status     | Description                           |
| ---------- | ------------------------------------- |
| `pending`  | Submitted for review                  |
| `approved` | Approved and ready to use             |
| `rejected` | Rejected (check feedback for reasons) |
| `disabled` | Temporarily disabled                  |

***

## 📝 Template Best Practices

### Naming Conventions

* Use lowercase letters only
* Use underscores for spaces
* Be descriptive: `welcome_new_user` vs `template1`
* Include language if multiple: `welcome_es`, `welcome_en`

### Content Guidelines

* **Be Clear**: Templates should be easily understood
* **Variables**: Use numbered placeholders `{1}`, `{2}`, `{3}` (WhatsApp uses positional variables)
* **Compliance**: Follow WhatsApp commerce policies
* **Testing**: Test with real data before submission

### Common Rejection Reasons

* ❌ Generic greetings ("Hello", "Hi there")
* ❌ Promotional language in UTILITY templates
* ❌ Missing context or unclear purpose
* ❌ Incorrect variable usage
* ❌ Policy violations (spam, inappropriate content)

### Approval Tips

* ✅ Include specific business context
* ✅ Use clear, professional language
* ✅ Provide meaningful examples
* ✅ Follow WhatsApp template guidelines
* ✅ Test variable substitution thoroughly

***

## 🔧 Development Tips

* Cache template information to reduce API calls
* Monitor template status changes
* Have fallback templates for rejected ones
* Use consistent naming across your organization
* Document templates for team reference