Skip to main content

WhatsApp Templates API

Manage WhatsApp message templates with the Templates API endpoints. Search, retrieve, and create templates for your workspace.

Endpoints​

1. List WhatsApp Templates​

GET /v1/whatsapp-templates

  • Description: Search and list all WhatsApp templates in a workspace with pagination support.
  • Authentication: Requires x-api-key header.

Query Parameters:

  • workspaceId (required): The workspace ID
  • searchText (optional): Search term to filter templates by name
  • page (optional): Page number for pagination (default: 1)
  • limit (optional): Number of results per page (default: 10)

Example Request:

GET /v1/whatsapp-templates?searchText=&page=1&limit=10&workspaceId=abc123xyz

Response: [200 OK] - Array of TemplateResponse

Example Response:

[
  {
    "id": "template_001",
    "template": {
      "category": "UTILITY",
      "language": "en",
      "name": "order_confirmation",
      "components": [
        {
          "type": "BODY",
          "text": "Hello {{1}},\n\nThis is a test message from {{2}}.\n\nYour reference number is {{3}}.\n\nIf you have any questions, please reply to this message.\n\nThank you.",
          "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-13T11:36:58.300Z",
    "updatedAt": "2026-02-13T11:36:58.300Z"
  }
]

2. Get WhatsApp Template by ID​

GET /v1/whatsapp-templates/{templateId}

  • Description: Retrieve a specific WhatsApp template by its ID.
  • Authentication: Requires x-api-key header.

Path Parameters:

  • templateId (required): The unique template ID

Example Request:

GET /v1/whatsapp-templates/template_001

Response: [200 OK] - TemplateResponse

Example Response:

{
  "id": "template_001",
  "template": {
    "category": "MARKETING",
    "language": "en",
    "name": "welcome_message",
    "components": [
      {
        "type": "HEADER",
        "format": "IMAGE",
        "example": {
          "header_handle": [
            "4:V2VsY29tZS5qcGc=:aW1hZ2UvanBlZw==:ARZLkrL7Ssy5UFMgS3oClXp0c6_xc_17pdxuPEK2YUxAw_BYsS7rzgGyoqRRfqin-eB5yW4hOe5UwvH164BXcF1ZlXD1aSog13EKIsj8d5UL_g:e:1748582745:1265290724938605:61576698358790:ARauyxiEani78JOFKh0"
          ]
        }
      },
      {
        "type": "BODY",
        "text": "✨ Ready to Transform Your Customer Conversations? ✨\n\nHi 👋, we're excited to introduce MyCompany — your all-in-one customer engagement platform!\n\n✅ Centralize Instagram, Messenger, and WhatsApp chats in one team inbox\n✅ Automate replies with smart chatbots\n✅ Send personalized broadcasts & campaigns\n✅ Boost sales and support with a custom AI chatbot that understands your business"
      },
      {
        "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": "2025-05-26T05:25:45.378Z",
  "updatedAt": "2026-02-13T07:59:10.470Z"
}

3. Create WhatsApp Template​

POST /v1/whatsapp-template

  • Description: Create a new WhatsApp template in a workspace.
  • Authentication: Requires x-api-key header.

Request Body: CreateTemplateRequest (application/json)

Required Fields:

Response: [201 Created] - TemplateResponse

Example Request:

{
  "template": {
    "category": "UTILITY",
    "language": "en",
    "name": "order_notification",
    "components": [
      {
        "type": "BODY",
        "text": "Hi {{1}},\n\nThis is a system generated test notification from {{2}}.\n\nYour temporary code is {{3}}.\n\nPlease keep this for your reference. No action is required.",
        "example": {
          "body_text": [
            [
              "Jane",
              "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"
  }
}

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

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

Notes​

  • Template names must be unique within a workspace
  • Templates require Meta approval before they can be used
  • Variable placeholders in templates use the format {{1}}, {{2}}, etc.
  • All variables must have corresponding example values provided
  • Marketing templates require an opt-out mechanism (typically in the footer)