Send Your First Message

A complete guide to sending WhatsApp messages through the CubeConnect API.

Before You Start

Make sure you have:

• An active CubeConnect account
• A connected WhatsApp Business account
• An API key

Understanding the 24-Hour Window

WhatsApp enforces a 24-hour messaging window:

Scenario	Allowed Message Types
Customer messaged in last 24h	Text, Media, Interactive, Templates
No customer message in 24h	Templates only

Sending a Text Message

Text messages are the simplest message type:

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": {
      "body": "Your order has been confirmed. Thank you!"
    }
  }'

PHP

use Illuminate\Support\Facades\Http;

$response = Http::withToken(env('CUBECONNECT_API_KEY'))
    ->post('https://cubeconnect.io/api/v1/messages/send', [
        'phone' => '+966501234567',
        'message_type' => 'text',
        'data' => [
            'body' => 'Your order has been confirmed. Thank you!',
        ],
    ]);

if ($response->successful()) {
    $logId = $response->json('data.message_log_id');
    echo "Message queued with ID: {$logId}";
}

JavaScript

async function sendMessage(phone, text) {
  const response = await fetch('https://cubeconnect.io/api/v1/messages/send', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.CUBECONNECT_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      phone,
      message_type: 'text',
      data: { body: text },
    }),
  })

  const result = await response.json()
  console.log('Message queued:', result.data.message_log_id)
  return result
}

await sendMessage('+966501234567', 'Your order has been confirmed!')

Python

import os
import requests

def send_message(phone: str, text: str):
    response = requests.post(
        'https://cubeconnect.io/api/v1/messages/send',
        headers={
            'Authorization': f'Bearer {os.environ["CUBECONNECT_API_KEY"]}',
            'Content-Type': 'application/json',
        },
        json={
            'phone': phone,
            'message_type': 'text',
            'data': {'body': text},
        },
    )
    response.raise_for_status()
    result = response.json()
    print(f'Message queued: {result["data"]["message_log_id"]}')
    return result

send_message('+966501234567', 'Your order has been confirmed!')

Sending a Template Message

Templates are required for messages outside the 24-hour window:

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_update",
      "params": ["ORD-5678", "Shipped", "2-3 business days"]
    }
  }'

The params array maps to template placeholders 1, 2, 3 in order.

Understanding the Response

A successful response always returns 202 Accepted:

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

Field	Description
status	Always queued - message is in the delivery queue
message_log_id	Use this to track the message
conversation_category	Affects billing: SERVICE, MARKETING, UTILITY, AUTHENTICATION

Tracking Message Delivery

After sending, the message goes through these statuses:

queued → sent → delivered → read

You can track status changes through webhooks. CubeConnect will send status updates as the message progresses:

{
  "statuses": [
    {
      "id": "wamid.xxx",
      "status": "delivered",
      "timestamp": "1708905660"
    }
  ]
}

Error Handling

Always handle potential errors:

async function sendMessageSafe(phone, text) {
  try {
    const response = await fetch('https://cubeconnect.io/api/v1/messages/send', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.CUBECONNECT_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        phone,
        message_type: 'text',
        data: { body: text },
      }),
    })

    if (response.status === 429) {
      console.log('Rate limited. Retry after delay.')
      return null
    }

    if (!response.ok) {
      const error = await response.json()
      console.error('API Error:', error.error.message)
      return null
    }

    return await response.json()
  } catch (err) {
    console.error('Network error:', err.message)
    return null
  }
}

Next Steps

• Set Up Webhooks to receive delivery status and incoming messages
• API Reference: Send Message for the complete API spec
• API Reference: Send Template for template message details