Templates

WhatsApp message templates are pre-approved message formats that can be sent outside the 24-hour messaging window. Templates must be approved by Meta before use.

Template Model

Field	Type	Description
id	integer	Unique template ID
name	string	Template name (lowercase, underscores)
language	string	Language code (ar, en_US, etc.)
category	string	MARKETING, UTILITY, AUTHENTICATION
status	string	Approval status
body_json	object	Template body and parameters

Template Statuses

Status	Description
PENDING	Submitted, awaiting Meta review
APPROVED	Approved and ready to send
REJECTED	Rejected by Meta
PAUSED	Temporarily paused due to quality
DISABLED	Disabled by Meta

Creating Templates

Templates are created and managed from the CubeConnect dashboard under Templates. The dashboard provides a visual editor for:

• Template name and category selection
• Body text with parameter placeholders (1, 2, etc.)
• Header (text, image, video, or document)
• Footer text
• Quick reply buttons or CTA buttons

List Templates via API

GET /api/v1/templates

Retrieve all templates for a WhatsApp account — useful for discovering available template names before sending a campaign.

Query Parameters

Parameter	Required	Description
whatsapp_account_id	Yes	Your WhatsApp account API ID
status	No	Filter by status (e.g., APPROVED)

Example Request

cURL

curl "https://cubeconnect.io/api/v1/templates?whatsapp_account_id=01JX...&status=APPROVED" \
  -H "Authorization: Bearer YOUR_API_KEY"

PHP

$templates = CubeConnect::getTemplates('APPROVED');

foreach ($templates as $t) {
    echo "{$t->name} ({$t->language}) — {$t->paramsCount} params\n";
}

JavaScript

const templates = await cube.getTemplates({ status: 'APPROVED' })

templates.forEach(t => {
  console.log(`${t.name} (${t.language}) — ${t.paramsCount} params`)
})

Response 200 OK

{
  "success": true,
  "data": [
    {
      "name": "order_confirmation",
      "language": "ar",
      "category": "UTILITY",
      "status": "APPROVED",
      "params_count": 3,
      "body": "مرحباً {{1}}، طلبك رقم {{2}} تم شحنه. الوقت المتوقع للوصول: {{3}}.",
      "header_type": "none",
      "header": null,
      "header_sample_media_url": null,
      "footer": null
    },
    {
      "name": "eid_promo",
      "language": "ar",
      "category": "MARKETING",
      "status": "APPROVED",
      "params_count": 0,
      "body": "عيد مبارك! خصم 20% على جميع منتجاتنا.",
      "header_type": "image",
      "header": null,
      "header_sample_media_url": "https://cdn.example.com/eid-banner.jpg",
      "footer": "ينتهي العرض في 2026-06-30"
    },
    {
      "name": "welcome",
      "language": "ar",
      "category": "MARKETING",
      "status": "APPROVED",
      "params_count": 0,
      "body": "أهلاً بك في متجرنا!",
      "header_type": "text",
      "header": "مرحباً بك",
      "header_sample_media_url": null,
      "footer": null
    }
  ]
}

Field	Type	Description
name	string	Template name — use this in sendTemplate and campaigns
language	string	Language code (ar, en_US, etc.)
category	string	MARKETING, UTILITY, or AUTHENTICATION
status	string	Approval status (see table below)
params_count	integer	Number of 1, 2 placeholders in the body
body	string|null	Template body text with placeholders
header_type	string	Always present. One of none, text, image, video, document. Use this to decide whether to attach a header component on send.
header	string|null	Header text content. Populated only when header_type === 'text'; null otherwise.
header_sample_media_url	string|null	Sample media URL Meta has on file (uploaded when the template was created). Populated only when header_type is image/video/document. You can pass this URL as the link in the header component on send, or upload your own media.
footer	string|null	Footer text, or null if no footer

Media-header templates

When header_type is image, video, or document, every send MUST include a header component with the actual media link or id. If you forget, the API returns TEMPLATE_HEADER_MEDIA_REQUIRED (422) — no send goes to Meta and no message is charged. See Send Template → Header media on send.

---

Using Templates via API

Send templates using the Send Template endpoint:

{
  "phone": "+966501234567",
  "message_type": "template",
  "data": {
    "name": "order_confirmation",
    "params": ["ORD-1234", "500 SAR"]
  }
}

Template Categories

Marketing

• Promotional offers and discounts
• Product announcements
• Event invitations
• Newsletter updates

Utility

• Order confirmations and updates
• Shipping notifications
• Appointment reminders
• Account alerts

Authentication

• Login verification codes (OTP)
• Two-factor authentication
• Email/phone verification

Template Parameters

Parameters are positional placeholders in the template body:

Hello {{1}}, your order {{2}} has been shipped.
Estimated delivery: {{3}}.

• Parameters are numbered starting from 1
• Each parameter maps to the corresponding index in the params array
• Parameters must be provided in order when sending

Template Quality

Meta monitors template quality based on:

• Read rate - Percentage of recipients who read the message
• Block rate - Percentage of recipients who block your number
• Report rate - Percentage of recipients who report the message

Low-quality templates may be paused or disabled. CubeConnect tracks these metrics and updates template statuses via webhook events.

WARNING

Keep your template quality high by:

• Sending templates only to customers who have opted in
• Keeping content relevant and valuable
• Avoiding excessive promotional messaging