WhatsApp Templates API

The WhatsApp Templates API allows you to search, retrieve, and create WhatsApp Business message templates within your DMLY workspace.

Templates follow the official Meta WhatsApp Business API template structure and are used for:

• Transactional notifications

• Marketing campaigns

• Authentication messages

• Broadcast messaging

• Automated workflows

VIDEO GUIDE:

🔗 Base URL

https://api.dmly.io/rest

🔐 Authentication

All endpoints require the x-api-key header:

x-api-key: YOUR_API_KEY

📌 Endpoints

1⃣ List WhatsApp Templates

GET /v1/whatsapp-templates

Search and list WhatsApp templates in a workspace with pagination support.

🔎 Query Parameters

📥 Example Request

curl -X GET "https://api.dmly.io/rest/v1/whatsapp-templates?workspaceId=abc123xyz&page=1&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

✅ Success Response 200 OK

[
  {
    "id": "template_001",
    "template": {
      "category": "UTILITY",
      "language": "en",
      "name": "order_confirmation",
      "components": [
        {
          "type": "BODY",
          "text": "Hello {{1}}, this is a test message from {{2}}.\nYour reference number is {{3}}.",
          "example": {
            "body_text": [
              ["John", "MyCompany", "123456"]
            ]
          }
        },
        {
          "type": "FOOTER",
          "text": "Reply STOP to unsubscribe from our updates."
        },
        {
          "type": "BUTTONS",
          "buttons": [
            {
              "type": "URL",
              "text": "Learn more",
              "url": "https://example.com"
            }
          ]
        }
      ]
    },
    "workspace": {
      "id": "abc123xyz",
      "title": "My Workspace"
    },
    "createdAt": "2026-02-18T11:36:58.308Z",
    "updatedAt": "2026-02-18T11:36:58.308Z"
  }
]

2⃣ Get WhatsApp Template by ID

GET /v1/whatsapp-templates/{templateId}

Retrieve a specific WhatsApp template by its ID.

🔎 Path Parameters

📥 Example Request

curl -X GET https://api.dmly.io/rest/v1/whatsapp-templates/template_001 \
  -H "x-api-key: YOUR_API_KEY"

✅ Success Response 200 OK

{
  "id": "template_001",
  "template": {
    "category": "MARKETING",
    "language": "en",
    "name": "welcome_message",
    "components": [
      {
        "type": "HEADER",
        "format": "IMAGE",
        "example": {
          "header_handle": ["media_id_123"]
        }
      },
      {
        "type": "BODY",
        "text": "Ready to transform your customer conversations? 🚀"
      },
      {
        "type": "FOOTER",
        "text": "Reply STOP to unsubscribe."
      },
      {
        "type": "BUTTONS",
        "buttons": [
          {
            "type": "URL",
            "text": "Learn more",
            "url": "https://example.com"
          }
        ]
      }
    ]
  },
  "workspace": {
    "id": "abc123xyz",
    "title": "My Workspace"
  },
  "createdAt": "2026-02-18T05:25:45.378Z",
  "updatedAt": "2026-02-18T07:59:10.478Z"
}

3⃣ Create WhatsApp Template

POST /v1/whatsapp-template

Create a new WhatsApp template in a workspace.

📦 Request Body

Content-Type: application/json

Required Fields

📥 Example Request

curl -X POST https://api.dmly.io/rest/v1/whatsapp-template \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
        "template": {
          "category": "UTILITY",
          "language": "en",
          "name": "order_notification",
          "components": [
            {
              "type": "BODY",
              "text": "Hello {{1}}, this is a system notification from {{2}}. Your temporary code is {{3}}.",
              "example": {
                "body_text": [
                  ["John", "MyCompany", "789012"]
                ]
              }
            },
            {
              "type": "FOOTER",
              "text": "This is an automated message."
            },
            {
              "type": "BUTTONS",
              "buttons": [
                {
                  "type": "URL",
                  "text": "View Details",
                  "url": "https://example.com"
                }
              ]
            }
          ]
        },
        "workspace": {
          "id": "abc123xyz"
        }
      }'

✅ Success Response 201 Created

{
  "id": "template_002",
  "status": "PENDING",
  "createdAt": "2026-02-20T09:00:00.000Z"
}

📦 Schemas

TemplateResponse Schema

{
  "id": "string",
  "template": {
    "category": "UTILITY | MARKETING | AUTHENTICATION",
    "language": "string",
    "name": "string",
    "status": "APPROVED | PENDING | REJECTED",
    "components": [
      {
        "type": "HEADER | BODY | FOOTER | BUTTONS",
        "format": "TEXT | IMAGE | VIDEO | DOCUMENT",
        "text": "string",
        "example": {
          "header_handle": ["string"],
          "body_text": [["string"]]
        },
        "buttons": [
          {
            "type": "URL | QUICK_REPLY | PHONE_NUMBER",
            "text": "string",
            "url": "string"
          }
        ]
      }
    ]
  },
  "workspace": {
    "id": "string",
    "title": "string"
  },
  "createdAt": "string (ISO 8601)",
  "updatedAt": "string (ISO 8601)"
}

CreateTemplateRequest Schema

{
  "template": {
    "category": "UTILITY | MARKETING | AUTHENTICATION",
    "language": "string",
    "name": "string",
    "components": [
      {
        "type": "HEADER | BODY | FOOTER | BUTTONS",
        "format": "TEXT | IMAGE | VIDEO | DOCUMENT",
        "text": "string",
        "example": {
          "header_handle": ["string"],
          "body_text": [["string"]]
        },
        "buttons": [
          {
            "type": "URL | QUICK_REPLY | PHONE_NUMBER",
            "text": "string",
            "url": "string"
          }
        ]
      }
    ]
  },
  "workspace": {
    "id": "string"
  }
}

Templates follow the official Meta WhatsApp Business API template structure.

📖 Template Structure Reference

The template object follows the Meta WhatsApp Business API template structure.

Key Points:

• Category: Templates can be UTILITY, MARKETING, or AUTHENTICATION

• Components: Templates consist of optional HEADER, required BODY, optional FOOTER, and optional BUTTONS

• Variables: Use {{1}}, {{2}}, etc. for dynamic content in the BODY text

• Examples: Provide example values for all variables in the example field

• Buttons: Support URL buttons, quick reply buttons, and phone number buttons

Component Types:

• HEADER: Optional, can be text, image, video, or document

• BODY: Required, contains the main message text with optional variables

• FOOTER: Optional, small text at the bottom of the message

• BUTTONS: Optional, up to 3 call-to-action or quick reply buttons

🔹 Components

A template may contain:

• HEADER (optional)

  • TEXT, IMAGE, VIDEO, DOCUMENT

• BODY (required)

  • Main message content

  • Supports dynamic variables: {{1}}, {{2}}, etc.

• FOOTER (optional)

• BUTTONS (optional)

  • URL

  • QUICK_REPLY

  • PHONE_NUMBER

  • Maximum of 3 buttons

🔹 Variables

Dynamic placeholders must follow:

{{1}}, {{2}}, {{3}}

Examples must be provided inside the example field.

📝 Important Notes

• Template names must be unique within a workspace.

• Templates require Meta approval before they can be used.

• Marketing templates typically require opt-out language.

• All variables must have corresponding example values.

• Buttons are limited to 3 per template.

• Changes to approved templates require re-approval.

🔐 Security Best Practices

• Never expose x-api-key on frontend applications.

• Use server-side integrations only.

• Monitor template approval status before sending.

• Log template creation attempts.

• Validate workspace ownership before template creation.