Skip to main content
POST
Create a template

Overview

Create a new WhatsApp message template. Templates must be approved by Meta before they can be used to send messages.
Templates typically take 5-30 minutes for approval. Use the Sync endpoint to check approval status.

Request Body Schema


Complete Examples

Example 1: Marketing Template with Image Header

Example 2: Authentication (OTP) Template

Authentication templates are auto-generated by Meta with standard security messaging. You only need to specify the three parameters above.

Example 3: Utility Template with Multiple Buttons

Example 4: Simple Text Template

Example 5: URL Button with Variable

Example 6: Video Header Template

Example 7: Document Header Template


Validation Rules

  • Must be unique in workspace
  • Only lowercase letters and underscores
  • Examples: ✅ welcome_message, order_confirmation_v2
  • Invalid: ❌ WelcomeMessage, order-confirmation, template 1
Must be valid ISO language code:
  • English: en
  • Spanish: es
  • French: fr
  • German: de
  • Portuguese: pt
  • Arabic: ar
  • And more…
Text Header:
  • Max 60 characters
  • Max 1 variable: {{1}}
  • Cannot start/end with variable
  • Example: ✅ Welcome {{1}}
  • Invalid: ❌ {{1}} Welcome
Media Header:
  • Image: JPG/PNG, max 5MB (5120KB)
  • Video: MP4, max 10MB (10240KB)
  • Document: PDF, max 30MB (30720KB)
  • Required field
  • Max 1024 characters
  • Cannot start or end with variable
  • Max 2 consecutive newlines (\n\n allowed, \n\n\n not allowed)
  • Variables must match: if text has {{1}} and {{2}}, variables array must have exactly 2 items
  • Variables are numbered sequentially: {{1}}, {{2}}, {{3}}, etc.
  • Max 3 buttons total (unsubscribe/block don’t count toward limit)
  • URL Button:
    • Requires text and url
    • Can have 1 variable at end: https://example.com/page?id={{1}}
    • Variable must be in variables array
  • PHONE_NUMBER Button:
    • Requires text and phone_number
    • Phone must include country code: +1234567890
  • QUICK_REPLY Button:
    • Requires text only
    • Max 3 quick replies per template
  • Button Order: URL → Phone → Quick Reply
  • Only 3 fields required: addSecurityRecommendation, codeExpirationMinutes, copyCodeButton
  • No custom header, body, footer, or buttons
  • Meta auto-generates the template content
  • codeExpirationMinutes range: 1-1440 (1 min to 24 hours)

Response

Success (201 Created)

Validation Error (422)


Template Status Flow

After creation, templates go through this lifecycle:
Use Sync Templates to update the status.

Common Validation Errors


Best Practices

Test Variables

Always test with actual variable values before submission

Keep It Simple

Start with basic templates, add complexity gradually

Follow Meta Guidelines

Avoid promotional language in UTILITY templates

Use Descriptive Names

Use clear names like order_confirmation not template_1

Optimize Media

Compress images/videos before upload

Plan Variables

Map out all dynamic values before creating template

Category Guidelines

Purpose: Promotional messages, offers, announcementsCharacteristics:
  • Can include unsubscribe/block buttons
  • Subject to stricter Meta review
  • Rate limits may apply
Examples:
  • Sales and promotions
  • New product launches
  • Event invitations
  • Newsletter updates

Example cURL Request


Need More Examples?Check out TEMPLATE_PAYLOADS.md for 15+ comprehensive template examples covering all use cases.
Meta Review Time: Templates typically take 5-30 minutes for approval. Use the Sync endpoint to check status updates.

Next Steps

After creating a template:
  1. Wait for Review: Meta reviews templates within 5-30 minutes
  2. Sync Status: Use POST /templates/sync
  3. Check Approval: Use GET /templates to verify status
  4. Send Messages: Once approved, use Send Template Message

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspace
string<uuid>
required

ID of the workspace.

Body

application/json
name
string
required
Example:

"login_otp_template"

language
string
required
Example:

"en"

category
enum<string>
required
Available options:
MARKETING,
UTILITY,
AUTHENTICATION
body
object
required
header
object

Option 2: Text Header

Maximum string length: 60
buttons
object[]
unsubscribeButton
boolean
blockButton
boolean

Response

Template created successfully