Skip to main content

​
Overview

Schedule messages to be sent at a specific date and time. Scheduled messages remain in a pending state until their scheduled time, when they are queued for delivery.

​
Create Scheduled Message

cURL
curl -X POST https://api-message.nativehub.live/api/v1/scheduled-messages \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+8801712345678",
    "to": "+8801812345679",
    "body": "Your appointment is tomorrow at 10 AM",
    "scheduled_at": "2026-02-15T10:00:00Z"
  }'
Node.js
const response = await fetch('https://api-message.nativehub.live/api/v1/scheduled-messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: '+8801712345678',
    to: '+8801812345679',
    body: 'Your appointment is tomorrow at 10 AM',
    scheduled_at: '2026-02-15T10:00:00Z'
  })
});

const scheduled = await response.json();
console.log(scheduled);
Python
from datetime import datetime, timezone

response = requests.post(
    'https://api-message.nativehub.live/api/v1/scheduled-messages',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'from': '+8801712345678',
        'to': '+8801812345679',
        'body': 'Your appointment is tomorrow at 10 AM',
        'scheduled_at': '2026-02-15T10:00:00Z'
    }
)

scheduled = response.json()
print(scheduled)
Response: 
{
  "id": "sched_abc123",
  "from": "+8801712345678",
  "to": "+8801812345679",
  "body": "Your appointment is tomorrow at 10 AM",
  "scheduled_at": "2026-02-15T10:00:00Z",
  "status": "pending",
  "created_at": "2026-02-14T15:30:00Z"
}

​
Scheduled Time Format

The scheduled_at field must be in ISO 8601 format with timezone information. Always use UTC (Z suffix) for consistency.
Valid formats:
  • 2026-02-15T10:00:00Z (UTC)
  • 2026-02-15T10:00:00+00:00 (UTC with offset)
  • 2026-02-15T15:00:00+05:00 (Local time with offset)
Invalid:
  • 2026-02-15 10:00:00 (missing timezone)
  • 2026-02-15 (date only)
The server automatically converts all scheduled times to UTC for processing.

​
List Scheduled Messages

cURL
curl -X GET https://api-message.nativehub.live/api/v1/scheduled-messages \
  -H "Authorization: Bearer YOUR_API_TOKEN"
Node.js
const response = await fetch('https://api-message.nativehub.live/api/v1/scheduled-messages', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN'
  }
});

const scheduled = await response.json();
Python
response = requests.get(
    'https://api-message.nativehub.live/api/v1/scheduled-messages',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)

scheduled = response.json()

​
Cancel Scheduled Message

Only messages with pending status can be cancelled.
cURL
curl -X POST https://api-message.nativehub.live/api/v1/scheduled-messages/sched_abc123/cancel \
  -H "Authorization: Bearer YOUR_API_TOKEN"
Node.js
const response = await fetch(
  'https://api-message.nativehub.live/api/v1/scheduled-messages/sched_abc123/cancel',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_TOKEN'
    }
  }
);

const result = await response.json();
Python
response = requests.post(
    'https://api-message.nativehub.live/api/v1/scheduled-messages/sched_abc123/cancel',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)

result = response.json()
Messages transition from pending to queued approximately 1 minute before their scheduled time. Once queued, they cannot be cancelled.

​
Status Lifecycle

StatusDescription
pendingWaiting for scheduled time (can be cancelled)
queuedProcessing started, waiting for carrier delivery
deliveredSuccessfully delivered to recipient
failedDelivery failed (see error codes)
cancelledCancelled by user before sending

​
Timezone Handling

The API accepts scheduled times in any timezone but converts them to UTC internally. When retrieving scheduled messages, all times are returned in UTC. Example: Schedule for 3 PM Bangladesh time (UTC+6)
Node.js
// Local time: 2026-02-15 15:00:00 in Dhaka (UTC+6)
// Converts to: 2026-02-15 09:00:00 UTC

const scheduledAt = new Date('2026-02-15T15:00:00+06:00').toISOString();
// Result: "2026-02-15T09:00:00.000Z"

await fetch('https://api-message.nativehub.live/api/v1/scheduled-messages', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: '+8801712345678',
    to: '+8801812345679',
    body: 'Reminder: Event at 3 PM today',
    scheduled_at: scheduledAt
  })
});
Python
from datetime import datetime
from zoneinfo import ZoneInfo

# Local time: 2026-02-15 15:00:00 in Dhaka (UTC+6)
local_time = datetime(2026, 2, 15, 15, 0, 0, tzinfo=ZoneInfo('Asia/Dhaka'))
scheduled_at = local_time.isoformat()
# Result: "2026-02-15T15:00:00+06:00"

response = requests.post(
    'https://api-message.nativehub.live/api/v1/scheduled-messages',
    headers={
        'Authorization': 'Bearer YOUR_API_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'from': '+8801712345678',
        'to': '+8801812345679',
        'body': 'Reminder: Event at 3 PM today',
        'scheduled_at': scheduled_at
    }
)