Send Template Message

Send a pre-approved WhatsApp message template. Templates can be sent outside the 24-hour messaging window.

POST /api/v1/messages/send

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer YOUR_API_KEY
Content-Type	Yes	application/json
X-TENANT-ID	No	Tenant ID (if multi-tenant)

Body Parameters

Parameter	Type	Required	Description
phone	string	Yes	Recipient phone number with country code
message_type	string	Yes	Must be template
data	object	Yes	Template data object
data.name	string	Yes	Template name (e.g., order_confirmation)
data.language_code	string	No	Template language code (default: en_US)
data.components	array	No	Meta components array with template parameters

Example Request

cURL

curl -X POST https://cubeconnect.io/api/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+966501234567",
    "message_type": "template",
    "data": {
      "name": "order_confirmation",
      "language_code": "en_US",
      "components": [
        {
          "type": "body",
          "parameters": [
            {"type": "text", "text": "ORD-1234"},
            {"type": "text", "text": "500 SAR"}
          ]
        }
      ]
    }
  }'

PHP

$response = Http::withToken('YOUR_API_KEY')
    ->post('https://cubeconnect.io/api/v1/messages/send', [
        'phone' => '+966501234567',
        'message_type' => 'template',
        'data' => [
            'name' => 'order_confirmation',
            'language_code' => 'en_US',
            'components' => [
                [
                    'type' => 'body',
                    'parameters' => [
                        ['type' => 'text', 'text' => 'ORD-1234'],
                        ['type' => 'text', 'text' => '500 SAR'],
                    ],
                ],
            ],
        ],
    ]);

JavaScript

const response = await fetch('https://cubeconnect.io/api/v1/messages/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone: '+966501234567',
    message_type: 'template',
    data: {
      name: 'order_confirmation',
      language_code: 'en_US',
      components: [
        {
          type: 'body',
          parameters: [
            { type: 'text', text: 'ORD-1234' },
            { type: 'text', text: '500 SAR' },
          ],
        },
      ],
    },
  }),
})

Python

import requests

response = requests.post(
    'https://cubeconnect.io/api/v1/messages/send',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
    },
    json={
        'phone': '+966501234567',
        'message_type': 'template',
        'data': {
            'name': 'order_confirmation',
            'language_code': 'en_US',
            'components': [
                {
                    'type': 'body',
                    'parameters': [
                        {'type': 'text', 'text': 'ORD-1234'},
                        {'type': 'text', 'text': '500 SAR'},
                    ],
                },
            ],
        },
    },
)

Response

Success 202 Accepted

{
  "success": true,
  "data": {
    "status": "queued",
    "message_log_id": 4522,
    "conversation_category": "MARKETING",
    "cost": 0.0
  }
}

The conversation_category is determined automatically based on the template's category in Meta Business Manager.

Template Parameters

Templates use positional placeholders like 1, 2, etc. The components array follows the Meta WhatsApp API format.

Example Template

Template name: order_confirmationTemplate body:

Your order {{1}} has been confirmed.
Total amount: {{2}}.
Thank you for your purchase!

API call components:

{
  "components": [
    {
      "type": "body",
      "parameters": [
        {"type": "text", "text": "ORD-1234"},
        {"type": "text", "text": "500 SAR"}
      ]
    }
  ]
}

Result sent to customer:

Your order ORD-1234 has been confirmed.
Total amount: 500 SAR.
Thank you for your purchase!

Template Categories

Category	Description	When to Use
MARKETING	Promotional content	Sales, offers, product announcements
UTILITY	Transactional updates	Order confirmations, shipping updates, account alerts
AUTHENTICATION	OTP and verification	Login codes, 2FA, verification

Template Without Parameters

If the template has no dynamic parameters, omit the components field:

{
  "phone": "+966501234567",
  "message_type": "template",
  "data": {
    "name": "welcome_message",
    "language_code": "en_US"
  }
}

Common Errors

Error	Cause
Template not found	The template name doesn't exist or hasn't been approved
Parameter count mismatch	The number of parameters in components doesn't match the template's placeholders
Template paused	Meta has paused the template due to quality issues

Template Approval

Templates must be approved by Meta before they can be sent. Create and manage templates from the CubeConnect dashboard under Templates.