Template Management API - Lovi AI Documentation

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

[
  {
    "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.

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

{
  "status": "OK",
  "components": ["header_image", "body_text_0", "body_text_1"]
}

Template with only body variables (no media):

{
  "status": "OK",
  "components": ["body_text_0", "body_text_1"]
}

Template with static content only (no dynamic components):

{
  "status": "OK",
  "components": []
}

Template with video header:

{
  "status": "OK",
  "components": ["header_video"]
}

Template with PDF document:

{
  "status": "OK",
  "components": ["header_document"]
}

Template with dynamic URL button:

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

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

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)

text: Footer text (static only, no variables)

BUTTONS

Array of button objects: URL Button:

{
  "type": "URL",
  "text": "Button Text",
  "url": "https://example.com/{1}"
}

Quick Reply Button:

{
  "type": "QUICK_REPLY",
  "text": "Button Text"
}

Response

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

Submission: Template is sent to Meta for review
Review: Meta reviews template (usually 24-48 hours)
Approval/Rejection: Template is approved or rejected with feedback
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

​Introduction

​📋 Get Available Templates

​Endpoint

​Query Parameters

​Response

​🔍 Get Template Components

​Endpoint

​Query Parameters

​Response

​🆕 Create New Template

​Endpoint

​Headers

​Body Request

​Required Parameters

​Template Categories

​Component Types

​HEADER

​BODY

​FOOTER

​BUTTONS

​Response

​Template Approval Process

​Template Status Values

​📝 Template Best Practices

​Naming Conventions

​Content Guidelines

​Common Rejection Reasons

​Approval Tips

​🔧 Development Tips

Introduction

📋 Get Available Templates

Endpoint

Query Parameters

Response

🔍 Get Template Components

Endpoint

Query Parameters

Response

🆕 Create New Template

Endpoint

Headers

Body Request

Required Parameters

Template Categories

Component Types

HEADER

BODY

FOOTER

BUTTONS

Response

Template Approval Process

Template Status Values

📝 Template Best Practices

Naming Conventions

Content Guidelines

Common Rejection Reasons

Approval Tips

🔧 Development Tips