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
`whatsapp_account_id`	string	Yes	WhatsApp account ID to send from — Dashboard → WhatsApp Numbers → API ID:
`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)
`scheduled_at`	string	No	ISO 8601 datetime to schedule delivery (e.g., `2026-05-01T10:00:00`). Must be in the future.
`timezone`	string	No	IANA timezone for interpreting `scheduled_at` (e.g., `Asia/Riyadh`). Defaults to UTC if omitted.

Example Request

cURLPHPJavaScriptPython

bash

curl -X POST https://cubeconnect.io/api/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_account_id": "YOUR_WHATSAPP_ACCOUNT_ID",
    "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', [
        'whatsapp_account_id' => env('CUBECONNECT_WHATSAPP_ACCOUNT_ID'),
        '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',
  },
  body: JSON.stringify({
    whatsapp_account_id: process.env.CUBECONNECT_WHATSAPP_ACCOUNT_ID,
    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={
        'whatsapp_account_id': 'YOUR_WHATSAPP_ACCOUNT_ID',
        'phone': '+966501234567',
        'message_type': 'text',
        'data': {
            'text': 'Hello! Your order #1234 has been shipped.',
        },
    },
)

Scheduled Message Example

cURLPHPJavaScript

bash

curl -X POST https://cubeconnect.io/api/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_account_id": "YOUR_WHATSAPP_ACCOUNT_ID",
    "phone": "+966501234567",
    "message_type": "text",
    "data": {
      "text": "Your appointment is tomorrow at 10:00 AM."
    },
    "scheduled_at": "2026-05-01T10:00:00",
    "timezone": "Asia/Riyadh"
  }'

php

$response = Http::withToken('YOUR_API_KEY')
    ->post('https://cubeconnect.io/api/v1/messages/send', [
        'whatsapp_account_id' => env('CUBECONNECT_WHATSAPP_ACCOUNT_ID'),
        'phone'               => '+966501234567',
        'message_type'        => 'text',
        'data'                => ['text' => 'Your appointment is tomorrow at 10:00 AM.'],
        'scheduled_at'        => '2026-05-01T10:00:00',
        'timezone'            => 'Asia/Riyadh',
    ]);

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({
    whatsapp_account_id: process.env.CUBECONNECT_WHATSAPP_ACCOUNT_ID,
    phone: '+966501234567',
    message_type: 'text',
    data: { text: 'Your appointment is tomorrow at 10:00 AM.' },
    scheduled_at: '2026-05-01T10:00:00',
    timezone: 'Asia/Riyadh',
  }),
})

Response

Immediate Delivery 202 Accepted

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

json

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

Scheduled Delivery 202 Accepted

json

{
  "success": true,
  "data": {
    "status": "scheduled",
    "message_log_id": 4521,
    "conversation_category": "SERVICE",
    "cost": 0.0,
    "scheduled_at": "2026-05-01T07:00:00Z"
  }
}

Field	Type	Description
`data.status`	string	`queued` for immediate, `scheduled` for deferred delivery
`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)
`data.scheduled_at`	string\|null	UTC datetime of scheduled delivery, or `null`

Error Responses

401 Unauthorized

json

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

422 Unprocessable Entity

json

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

429 Too Many Requests

json

{
  "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.

Get Message Status

Retrieve the current delivery status of a previously sent message.

GET /api/v1/messages/{id}

The {id} is the message_log_id returned when you sent the message.

Request

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer YOUR_API_KEY`

Path Parameters

Parameter	Type	Description
`id`	integer	The `message_log_id` returned by `POST /api/v1/messages/send`

Example Request

cURLPHPJavaScript

bash

curl -X GET https://cubeconnect.io/api/v1/messages/4521 \
  -H "Authorization: Bearer YOUR_API_KEY"

php

$response = Http::withToken('YOUR_API_KEY')
    ->get('https://cubeconnect.io/api/v1/messages/4521');

javascript

const response = await fetch('https://cubeconnect.io/api/v1/messages/4521', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
})
const result = await response.json()

Response

200 OK

json

{
  "success": true,
  "data": {
    "message_log_id": 4521,
    "status": "delivered",
    "to_phone": "966501234567",
    "message_type": "text",
    "meta_message_id": "wamid.HBgN...",
    "sent_at": "2026-05-01T07:05:00Z",
    "scheduled_at": null,
    "cost_amount": 0.0,
    "cost_currency": "SAR",
    "error_message": null,
    "created_at": "2026-05-01T07:00:00Z"
  }
}

Field	Type	Description
`message_log_id`	integer	Unique message ID
`status`	string	Current delivery status (see table below)
`to_phone`	string	Recipient phone number
`message_type`	string	`text` or `template`
`meta_message_id`	string\|null	WhatsApp message ID (set after sending)
`sent_at`	string\|null	UTC datetime when sent to WhatsApp
`scheduled_at`	string\|null	UTC datetime of scheduled delivery
`cost_amount`	number	Message cost
`cost_currency`	string	Currency code (e.g., `SAR`)
`error_message`	string\|null	Error details if status is `failed`
`created_at`	string	UTC datetime when the log was created

Message Status Values

Status	Description
`queued`	Waiting in queue to be sent
`scheduled`	Scheduled for future delivery
`sent`	Accepted by WhatsApp Cloud API
`delivered`	Delivered to the recipient's device
`read`	Read by the recipient
`failed`	Delivery failed — see `error_message`

Polling vs. Webhooks

Polling GET /api/v1/messages/{id} is useful for checking a specific message after the fact. For real-time updates, configure a webhook to receive message.status_updated events automatically.

Send Message ​

Request ​

Headers ​

Body Parameters ​

Example Request ​

Scheduled Message Example ​

Response ​

Immediate Delivery 202 Accepted ​

Scheduled Delivery 202 Accepted ​

Error Responses ​

Phone Number Format ​

Message Delivery Flow ​

Get Message Status ​

Request ​

Headers ​

Path Parameters ​

Example Request ​

Response ​

Message Status Values ​

Send Message

Request

Headers

Body Parameters

Example Request

Scheduled Message Example

Response

Immediate Delivery 202 Accepted

Scheduled Delivery 202 Accepted

Error Responses

Phone Number Format

Message Delivery Flow

Get Message Status

Request

Headers

Path Parameters

Example Request

Response

Message Status Values