Skip to main content

Template Management API

Beta

The Template Management API is currently in beta. If you would like to join the beta, please contact us.

The Template Management API allows you to create, list, retrieve, update, and delete WhatsApp message templates in your workspace programmatically.

See Also

Looking to send templates to contacts? See the Templates API for sending pre-approved templates via the Messages API.

See the authentication page for how to obtain a bearer token. All endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <token>

JSON Field Casing​

All request and response bodies use snake_case field names exclusively.

Error Responses​

All endpoints return errors in a consistent envelope format:

{
  "error": {
    "message": "422 UNPROCESSABLE ENTITY",
    "details": "Template content failed validation",
    "violations": [
      {
        "field": "content.body.text",
        "rule": "REQUIRED",
        "message": "Body text is required"
      }
    ]
  }
}

The violations array is present on validation errors (422) and provides field-level detail about what failed. Each violation contains:

FieldTypeDescription
fieldstringDot-notation path to the invalid field
rulestringViolation rule code (e.g. REQUIRED, IMMUTABLE, INVALID_FORMAT)
messagestringHuman-readable description of the violation

Common error status codes:

StatusMeaning
400Bad request -- malformed input
401Unauthorized -- invalid or missing token
403Forbidden -- insufficient permissions
404Not found -- template does not exist in your workspace
409Conflict -- duplicate template name/locale combination
422Unprocessable entity -- validation error with violations
429Too many requests -- rate limit exceeded (check Retry-After header)
500Internal server error

Pagination​

The list endpoint uses offset-based pagination:

ParameterTypeDefaultMinMax
limitinteger501100
offsetinteger00--
{
  "templates": [...],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 142
  }
}

Create Template​

POST https://api.cuedesk.com/v1/templates

Creates a new WhatsApp message template. The template will be submitted to Meta for approval.

Headers:

HeaderRequiredDescription
AuthorizationYesBearer token
Idempotency-KeyNoUnique key to prevent duplicate template creation
{
  "name": "order_confirmation",
  "locale": "en",
  "category": "UTILITY",
  "template_type": "STANDARD",
  "content": {
    "header": {
      "format": "TEXT",
      "text": "Order Confirmed"
    },
    "body": {
      "text": "Hi {{1}}, your order #{{2}} has been confirmed and will be delivered by {{3}}.",
      "example": ["John", "12345", "25 Jan 2025"]
    },
    "footer": {
      "text": "Thank you for your purchase"
    },
    "buttons": [
      {
        "type": "URL",
        "text": "Track Order",
        "url": "https://example.com/track/{{1}}",
        "example": ["12345"]
      }
    ]
  },
  "enabled_in_livechat": true,
  "continue_session": false
}
FieldTypeRequiredDescription
namestringYesTemplate name. Alphanumeric, underscores, and spaces. Max 500 chars.
localestringYesLanguage code, e.g. en, es_ES. Format: xx or xx_XX.
categorystringYesOne of: MARKETING, UTILITY, AUTHENTICATION
template_typestringYesOne of: STANDARD, CAROUSEL, AUTHENTICATION
contentobjectYesTemplate content structure (see Content Object)
enabled_in_livechatbooleanYesWhether agents can send this template from the live chat UI
continue_sessionbooleanYesWhether sending this template continues an existing conversation session

List Templates​

GET https://api.cuedesk.com/v1/templates

Returns a paginated list of templates in your workspace with optional filtering.

Query parameters:

ParameterTypeRequiredDescription
limitintegerNoResults per page (1–100, default 50)
offsetintegerNoOffset for pagination (default 0)
statusstringNoFilter by status (see TemplateStatus)
categorystringNoFilter by category: MARKETING, UTILITY, AUTHENTICATION
searchstringNoSearch by template name (1–200 chars)
GET https://api.cuedesk.com/v1/templates?status=APPROVED&category=UTILITY&limit=10
Authorization: Bearer <token>

Get Template​

GET https://api.cuedesk.com/v1/templates/{template_uuid}

Retrieves a single template by its UUID.

GET https://api.cuedesk.com/v1/templates/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Bearer <token>

Delete Template​

DELETE https://api.cuedesk.com/v1/templates/{template_uuid}

Deletes a template. This operation is asynchronous — a 202 Accepted response indicates the deletion has been initiated.

DELETE https://api.cuedesk.com/v1/templates/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Authorization: Bearer <token>

Template Object​

The full template object returned by Create, Get, and List endpoints:

FieldTypeDescription
uuidstringUnique template identifier (UUID v4)
workspace_uuidstringWorkspace the template belongs to
namestringTemplate display name
canonical_namestringNormalized template name (lowercase, underscored)
localestringLanguage code (e.g. en, pt_BR)
categorystringTemplate category (see TemplateCategory)
template_typestringTemplate type (see TemplateType)
statusstringCurrent approval status (see TemplateStatus)
rejection_reasonstringReason for rejection, if applicable
contentobjectTemplate content structure (see Content Object)
enabled_in_livechatbooleanWhether the template is available in the live chat UI
continue_sessionbooleanWhether sending this template continues a session
created_atstringISO 8601 timestamp
updated_atstringISO 8601 timestamp

Content Object​

The content field contains the template's structural components:

FieldTypeDescription
headerobjectHeader component (format, text, example)
bodyobjectBody component (text, example)
footerobjectFooter component (text)
buttonsarrayList of button components
cardsarrayCarousel cards (only for CAROUSEL type)
authobjectAuthentication config (only for AUTHENTICATION type)

Header formats​

FormatDescription
TEXTText header with optional parameter placeholders
IMAGEImage media header
VIDEOVideo media header
DOCUMENTDocument media header

Button types​

TypeDescription
QUICK_REPLYQuick reply button
URLURL button (can contain a parameter)
PHONE_NUMBERCall button
COPY_CODECopy code button
OTPOne-time password button

Enums Reference​

TemplateCategory​

ValueDescription
MARKETINGPromotional and marketing messages
UTILITYTransactional and utility messages
AUTHENTICATIONOne-time password and verification messages

TemplateType​

ValueDescription
STANDARDStandard template with header, body, footer, and buttons
CAROUSELCarousel template with scrollable cards
AUTHENTICATIONAuthentication template with OTP configuration

TemplateStatus​

ValueDescription
PREPARINGTemplate is being prepared for submission
PENDINGSubmitted and awaiting Meta approval
APPROVEDApproved and ready to use
REJECTEDRejected by Meta (see rejection_reason)
PAUSEDTemporarily paused by Meta
FLAGGEDFlagged for quality issues
DISABLEDDisabled by Meta
IN_APPEALRejection is being appealed
PENDING_DELETIONDeletion in progress
LOCKEDLocked and cannot be modified
IN_REVIEWUnder review after an update
DELETEDSuccessfully deleted
CREATE_FAILEDTemplate creation failed
UPDATE_FAILEDTemplate update failed
DELETE_FAILEDTemplate deletion failed