Send Message

Send a text message to a WhatsApp number.

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 (e.g., +966501234567)
message_type	string	Yes	Must be text
data	object	Yes	Message data object
data.text	string	Yes	Message text content (supports Unicode and Arabic)

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": "text",
    "data": {
      "text": "Hello! Your order #1234 has been shipped."
    }
  }'

PHP

$response = Http::withToken('YOUR_API_KEY')
    ->post('https://cubeconnect.io/api/v1/messages/send', [
        'phone' => '+966501234567',
        'message_type' => 'text',
        'data' => [
            'text' => 'Hello! Your order #1234 has been shipped.',
        ],
    ]);

JavaScript

const response = await fetch('https://cubeconnect.io/api/v1/messages/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  text: JSON.stringify({
    phone: '+966501234567',
    message_type: 'text',
    data: {
      text: 'Hello! Your order #1234 has been shipped.',
    },
  }),
})

const result = await response.json()

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': 'text',
        'data': {
            'text': 'Hello! Your order #1234 has been shipped.',
        },
    },
)

Response

Success 202 Accepted

The message has been queued for delivery. Use webhooks to track delivery status.

{
  "success": true,
  "data": {
    "status": "queued",
    "message_log_id": 4521,
    "conversation_category": "SERVICE",
    "cost": 0.0
  }
}

Field	Type	Description
data.status	string	Always queued on success
data.message_log_id	integer	Unique log ID for tracking
data.conversation_category	string	WhatsApp conversation category: SERVICE, MARKETING, UTILITY, AUTHENTICATION
data.cost	number	Message cost (reserved for future billing)

Error Responses

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key."
  }
}

422 Unprocessable Entity

{
  "success": false,
  "error": {
    "code": "NO_ACTIVE_ACCOUNT",
    "message": "No active WhatsApp account found."
  }
}

429 Too Many Requests

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded for your current plan."
  }
}

Phone Number Format

Phone numbers must include the country code without the + prefix or with it:

Format	Valid
+966501234567	Yes
966501234567	Yes
0501234567	No (missing country code)

Message Delivery Flow

Your API Request → CubeConnect Queue → WhatsApp Cloud API → Recipient
                         ↓
                   Message Log Created
                   (status: queued)
                         ↓
                   Webhook: status sent
                         ↓
                   Webhook: status delivered
                         ↓
                   Webhook: status read

24-Hour Messaging Window

Text messages can only be sent within 24 hours of the customer's last message. Outside this window, you must use a pre-approved template.