Templates

Overview

WhatsApp Message Templates are pre-approved message formats required for sending business-initiated messages. Templates must be approved by Meta before use.

List Templates

Retrieve all templates for your account.

GET /api/templates

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20)
`account`	string	Filter by WhatsApp account name
`status`	string	Filter by status (APPROVED, PENDING, REJECTED, DRAFT, etc.)
`category`	string	Filter by category (MARKETING, UTILITY, AUTHENTICATION)
`search`	string	Search template name or display name (case-insensitive)

Response

{
  "status": "success",
  "data": {
    "templates": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "whatsapp_account": "default_account",
        "meta_template_id": "123456789012345",
        "name": "order_confirmation",
        "display_name": "Order Confirmation",
        "language": "en",
        "category": "UTILITY",
        "status": "APPROVED",
        "header_type": "IMAGE",
        "header_content": "440e8400-e29b-41d4-a716-446655440000",
        "body_content": "Hi {{1}}, your order #{{2}} has been confirmed!",
        "footer_content": "Thank you for shopping with us",
        "buttons": [
          {
            "type": "URL",
            "text": "Track Order",
            "url": "https://example.com/track/{{1}}"
          }
        ],
        "sample_values": [
          "John",
          "12345"
        ],
        "add_security_recommendation": false,
        "code_expiration_minutes": 0,
        "quality_rating": "GREEN",
        "created_by_name": "Admin User",
        "updated_by_name": "Admin User",
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 50,
    "page": 1,
    "limit": 20
  }
}

Get Template

Retrieve a single template by ID.

GET /api/templates/{id}

Response

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "whatsapp_account": "default_account",
    "meta_template_id": "123456789012345",
    "name": "order_confirmation",
    "display_name": "Order Confirmation",
    "language": "en",
    "category": "UTILITY",
    "status": "APPROVED",
    "header_type": "IMAGE",
    "header_content": "440e8400-e29b-41d4-a716-446655440000",
    "body_content": "Hi {{1}}, your order #{{2}} has been confirmed!",
    "footer_content": "Thank you for shopping with us",
    "buttons": [
      {
        "type": "URL",
        "text": "Track Order",
        "url": "https://example.com/track/{{1}}"
      }
    ],
    "sample_values": [
      "John",
      "12345"
    ],
    "add_security_recommendation": false,
    "code_expiration_minutes": 0,
    "quality_rating": "GREEN",
    "created_by_name": "Admin User",
    "updated_by_name": "Admin User",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Create Template

Create a new local draft template. Note that fields are flat rather than nested under components.

POST /api/templates

Request Body

Field	Type	Required	Description
`whatsapp_account`	string	Yes	WhatsApp account name
`name`	string	Yes	Template API name (lowercase, alphanumeric, and underscores only)
`display_name`	string	No	User-friendly template name (defaults to `name`)
`language`	string	Yes	Language code (e.g. `en`, `es`)
`category`	string	Yes	MARKETING, UTILITY, or AUTHENTICATION
`header_type`	string	No	TEXT, IMAGE, VIDEO, DOCUMENT, or NONE (default: NONE)
`header_content`	string	No	Header text, or media handle (from the upload-media API)
`body_content`	string	Yes*	Message body. Supports variables (`{{1}}`, `{{2}}`). Required unless AUTHENTICATION.
`footer_content`	string	No	Footer text
`buttons`	array	No	Template buttons array
`sample_values`	array	No	Sample values for body and header variables
`add_security_recommendation`	boolean	No	AUTHENTICATION category only: appends Meta security disclaimer
`code_expiration_minutes`	integer	No	AUTHENTICATION category only: expiration time in minutes (1-90)

{
  "whatsapp_account": "default_account",
  "name": "welcome_message",
  "display_name": "Welcome Message",
  "language": "en",
  "category": "MARKETING",
  "header_type": "TEXT",
  "header_content": "Welcome to {{1}}!",
  "body_content": "Welcome to our store, {{1}}! Use code {{2}} for 10% off your first order.",
  "footer_content": "Reply STOP to unsubscribe",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "Unsubscribe"
    }
  ],
  "sample_values": [
    "CloudWA",
    "John",
    "WELCOME10"
  ]
}

Response

Returns the fully created TemplateResponse object with status DRAFT.

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "whatsapp_account": "default_account",
    "meta_template_id": "",
    "name": "welcome_message",
    "display_name": "Welcome Message",
    "language": "en",
    "category": "MARKETING",
    "status": "DRAFT",
    "header_type": "TEXT",
    "header_content": "Welcome to {{1}}!",
    "body_content": "Welcome to our store, {{1}}! Use code {{2}} for 10% off your first order.",
    "footer_content": "Reply STOP to unsubscribe",
    "buttons": [
      {
        "type": "QUICK_REPLY",
        "text": "Unsubscribe"
      }
    ],
    "sample_values": [
      "CloudWA",
      "John",
      "WELCOME10"
    ],
    "add_security_recommendation": false,
    "code_expiration_minutes": 0,
    "quality_rating": "UNKNOWN",
    "created_at": "2024-01-01T12:00:00Z",
    "updated_at": "2024-01-01T12:00:00Z"
  }
}

Update Template

Update an existing draft template.

PUT /api/templates/{id}

Request Body

Same structure as template creation.

Delete Template

Delete a template locally and request deletion from Meta if already published.

DELETE /api/templates/{id}

Response

{
  "status": "success",
  "data": {
    "message": "Template deleted successfully"
  }
}

Upload Template Media

Upload a media file (image, video, document) for use as a template header sample value. This endpoint returns a handle string that you must pass into header_content during template creation.

This endpoint accepts multipart/form-data.

POST /api/templates/upload-media

Request Parameters

Parameter	Type	Required	Description
`file`	file binary	Yes	The sample media file to upload
`account`	string	Yes	WhatsApp account name (can be passed as a query param or form value)

Response

{
  "status": "success",
  "data": {
    "handle": "440e8400-e29b-41d4-a716-446655440000",
    "filename": "sample_invoice.pdf",
    "mime_type": "application/pdf",
    "size": 12345
  }
}

Submit Template

Submit a local DRAFT template to Meta for approval, or publish update revisions to Meta.

POST /api/templates/{id}/publish

Response

{
  "status": "success",
  "data": {
    "message": "Template submitted to Meta for approval",
    "meta_template_id": "123456789012345",
    "status": "PENDING",
    "template": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "whatsapp_account": "default_account",
      "meta_template_id": "123456789012345",
      "name": "welcome_message",
      "status": "PENDING",
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-01T12:05:00Z"
    }
  }
}

Sync Templates

Sync templates from Meta’s API to your local CloudWA database.

POST /api/templates/sync

Request Body

{
  "whatsapp_account": "default_account"
}

Response

{
  "status": "success",
  "data": {
    "message": "Synced 25 templates",
    "count": 25
  }
}