Ελέγξτε την κατάσταση του μηνύματος

Παρακολουθήστε την κατάσταση παράδοσης των μηνυμάτων σας χρησιμοποιώντας το τελικό σημείο ελέγχου κατάστασης.

Τελικό σημείο

GET /bat/message/{messageId}

Αίτημα

Παράμετροι URL

Παράμετρος	Τύπος	Απαιτείται	Περιγραφή
MessageId	χορδή	Ναι	Μοναδικό αναγνωριστικό μηνύματος από απάντηση αποστολής

Έλεγχος ταυτότητας

Χρησιμοποιήστε οποιαδήποτε από τις τρεις μεθόδους ελέγχου ταυτότητας:

Κεφαλίδα κλειδιού APIHTTP Basic AuthΚλειδί API ως κωδικός πρόσβασης

curl -X GET https://restapi.smsbat.com/bat/message/abc123def456 \
  -H "X-Authorization-Key: your-api-key"

curl -X GET https://restapi.smsbat.com/bat/message/abc123def456 \
  -u "username:password"

curl -X GET https://restapi.smsbat.com/bat/message/abc123def456 \
  -u "@:your-api-key"

Απάντηση

Βασική απάντηση

{
  "messagelistId": 123456,
  "messageId": "abc123def456",
  "deliverystatus": "delivered",
  "partscount": 1,
  "cost": 0.05
}

Πεδία απόκρισης

Πεδίο	Τύπος	Περιγραφή
messagelistId	ακέραιος	Αναγνωριστικό παρτίδας
MessageId	χορδή	Μοναδικό αναγνωριστικό μηνύματος
«κατάσταση παράδοσης»	χορδή	Τρέχουσα κατάσταση παράδοσης
«partscount»	ακέραιος	Αριθμός τμημάτων μηνύματος
«κόστος»	αριθμός	Κόστος μηνύματος σε νομισματικές μονάδες

Εκτεταμένη απόκριση (με εναλλακτική)

Όταν διαμορφωθεί η εναλλακτική, η απάντηση περιλαμβάνει πρόσθετα πεδία:

{
  "messagelistId": 123456,
  "messageId": "abc123def456",
  "deliverystatus": "delivered",
  "partscount": 1,
  "cost": 0.05,
  "fallbacks": [
    {
      "type": "sms",
      "status": "not_used"
    }
  ],
  "extendedStatuses": {
    "viber": "delivered",
    "sms": "not_used"
  },
  "rate": 0.05,
  "rateAmount": 0.05,
  "rateCurrency": "USD",
  "billAmount": 0.05,
  "billCurrency": "USD"
}

Τιμές κατάστασης παράδοσης

Κατάσταση	Περιγραφή
"προγραμματισμένο"	Σε ουρά για αποστολή
«επεξεργασία»	Αποστέλλεται αυτήν τη στιγμή
«παραδόθηκε»	Παραδόθηκε με επιτυχία
«μη παραδοτέο»	Η παράδοση απέτυχε, το μήνυμα απορρίφθηκε
«μόνιμο σφάλμα»	Καταργήθηκε από την ουρά λόγω επίμονου σφάλματος

Κατάσταση κύκλου ζωής

graph LR
    A[scheduled] --> B[processing]
    B --> C[delivered]
    B --> D[undeliverable]
    B --> E[permanenterror]

Προγραμματισμένο

Το μήνυμα γίνεται δεκτό και βρίσκεται σε ουρά για παράδοση:

{
  "deliverystatus": "scheduled",
  "partscount": 1
}

Επεξεργασία

Το μήνυμα αποστέλλεται αυτήν τη στιγμή στον παραλήπτη:

{
  "deliverystatus": "processing",
  "partscount": 1
}

Παραδόθηκε

Το μήνυμα παραδόθηκε με επιτυχία στον παραλήπτη:

{
  "deliverystatus": "delivered",
  "partscount": 1,
  "cost": 0.05
}

Μη παράδοση

Δεν ήταν δυνατή η παράδοση του μηνύματος (μη έγκυρος αριθμός, σφάλμα δικτύου):

{
  "deliverystatus": "undeliverable",
  "partscount": 1,
  "cost": 0.00
}

Μόνιμο σφάλμα

Το μήνυμα καταργήθηκε από την ουρά λόγω επίμονων προβλημάτων παράδοσης:

{
  "deliverystatus": "permanenterror",
  "partscount": 1,
  "cost": 0.00
}

Ελέγξτε τα πολλαπλά μηνύματα

Ελέγξτε την κατάσταση για πολλά μηνύματα στην αίτησή σας:

// JavaScript example
async function checkMessageStatuses(messageIds) {
  const statuses = await Promise.all(
    messageIds.map(async (messageId) => {
      const response = await fetch(
        `https://restapi.smsbat.com/bat/message/${messageId}`,
        {
          headers: {
            'X-Authorization-Key': 'your-api-key'
          }
        }
      );
      return response.json();
    })
  );

  return statuses;
}

// Usage
const messageIds = ['abc123', 'def456', 'ghi789'];
const statuses = await checkMessageStatuses(messageIds);

statuses.forEach(status => {
  console.log(`Message ${status.messageId}: ${status.deliverystatus}`);
});

Δημοσκόπηση για ενημερώσεις κατάστασης

Δημοσκοπήστε το τελικό σημείο κατάστασης για να παρακολουθήσετε την παράδοση:

// Poll every 5 seconds until delivered
async function waitForDelivery(messageId, maxAttempts = 12) {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://restapi.smsbat.com/bat/message/${messageId}`,
      {
        headers: { 'X-Authorization-Key': 'your-api-key' }
      }
    );

    const status = await response.json();

    if (status.deliverystatus === 'delivered') {
      return { success: true, status };
    }

    if (status.deliverystatus === 'undeliverable' ||
        status.deliverystatus === 'permanenterror') {
      return { success: false, status };
    }

    // Wait 5 seconds before next check
    await new Promise(resolve => setTimeout(resolve, 5000));
  }

  // Timeout after 60 seconds
  return { success: false, timeout: true };
}

Εναλλακτική λύση Webhook

Αντί για δημοσκόπηση, χρησιμοποιήστε webhook για ενημερώσεις κατάστασης σε πραγματικό χρόνο:

POST https://your-server.com/webhook
{
  "messageId": "abc123def456",
  "deliverystatus": "delivered",
  "timestamp": "2025-01-23T10:30:00Z",
  "cost": 0.05
}

Επικοινωνήστε με τον διαχειριστή του λογαριασμού σας για να διαμορφώσετε τη διεύθυνση URL του webhook.

Παραδείγματα Εφαρμογής

Python

import requests
import time

def check_status(message_id, api_key):
    url = f"https://restapi.smsbat.com/bat/message/{message_id}"
    headers = {"X-Authorization-Key": api_key}

    response = requests.get(url, headers=headers)
    return response.json()

def wait_for_delivery(message_id, api_key, timeout=60):
    """Poll until delivered or timeout"""
    start_time = time.time()

    while time.time() - start_time < timeout:
        status = check_status(message_id, api_key)

        if status['deliverystatus'] == 'delivered':
            return {'success': True, 'status': status}

        if status['deliverystatus'] in ['undeliverable', 'permanenterror']:
            return {'success': False, 'status': status}

        time.sleep(5)

    return {'success': False, 'timeout': True}

# Usage
message_id = "abc123def456"
result = wait_for_delivery(message_id, "your-api-key")

if result['success']:
    print(f"Message delivered! Cost: {result['status']['cost']}")
else:
    print("Message delivery failed or timeout")

PHP

<?php

function checkStatus($messageId, $apiKey) {
    $url = "https://restapi.smsbat.com/bat/message/" . $messageId;

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "X-Authorization-Key: " . $apiKey
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

function waitForDelivery($messageId, $apiKey, $timeout = 60) {
    $startTime = time();

    while (time() - $startTime < $timeout) {
        $status = checkStatus($messageId, $apiKey);

        if ($status['deliverystatus'] === 'delivered') {
            return ['success' => true, 'status' => $status];
        }

        if (in_array($status['deliverystatus'],
                    ['undeliverable', 'permanenterror'])) {
            return ['success' => false, 'status' => $status];
        }

        sleep(5);
    }

    return ['success' => false, 'timeout' => true];
}

// Usage
$messageId = "abc123def456";
$result = waitForDelivery($messageId, "your-api-key");

if ($result['success']) {
    echo "Message delivered! Cost: " . $result['status']['cost'];
} else {
    echo "Message delivery failed or timeout";
}

Node.js

const axios = require('axios');

async function checkStatus(messageId, apiKey) {
  const response = await axios.get(
    `https://restapi.smsbat.com/bat/message/${messageId}`,
    {
      headers: { 'X-Authorization-Key': apiKey }
    }
  );

  return response.data;
}

async function waitForDelivery(messageId, apiKey, timeout = 60000) {
  const startTime = Date.now();

  while (Date.now() - startTime < timeout) {
    const status = await checkStatus(messageId, apiKey);

    if (status.deliverystatus === 'delivered') {
      return { success: true, status };
    }

    if (['undeliverable', 'permanenterror'].includes(
      status.deliverystatus
    )) {
      return { success: false, status };
    }

    // Wait 5 seconds
    await new Promise(resolve => setTimeout(resolve, 5000));
  }

  return { success: false, timeout: true };
}

// Usage
const messageId = 'abc123def456';
const result = await waitForDelivery(messageId, 'your-api-key');

if (result.success) {
  console.log(`Message delivered! Cost: ${result.status.cost}`);
} else {
  console.log('Message delivery failed or timeout');
}

Βέλτιστες πρακτικές

Συχνότητα ψηφοφορίας

• ✅ Δημοσκόπηση κάθε 5-10 δευτερόλεπτα
• ✅ Εφαρμογή εκθετικής υποχώρησης
• ✅ Ορίστε εύλογο χρονικό όριο (60-120 δευτερόλεπτα)
• ❌ Μην κάνετε δημοσκόπηση περισσότερο από μία φορά το δευτερόλεπτο
• ❌ Μην κάνετε δημοσκόπηση επ' αόριστον

Χειρισμός σφαλμάτων

async function checkStatusWithRetry(messageId, apiKey, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(
        `https://restapi.smsbat.com/bat/message/${messageId}`,
        {
          headers: { 'X-Authorization-Key': apiKey }
        }
      );

      if (!response.ok) {
        throw new Error(`HTTP ${response.status}`);
      }

      return await response.json();
    } catch (error) {
      if (i === retries - 1) throw error;

      // Wait before retry (exponential backoff)
      await new Promise(resolve =>
        setTimeout(resolve, Math.pow(2, i) * 1000)
      );
    }
  }
}

Προσωρινή αποθήκευση

Αποτελέσματα κατάστασης προσωρινής αποθήκευσης για μείωση των κλήσεων API:

const statusCache = new Map();

async function getCachedStatus(messageId, apiKey, cacheTTL = 30000) {
  const cached = statusCache.get(messageId);

  if (cached && Date.now() - cached.timestamp < cacheTTL) {
    return cached.status;
  }

  const status = await checkStatus(messageId, apiKey);

  statusCache.set(messageId, {
    status,
    timestamp: Date.now()
  });

  return status;
}

Επεξεργασία παρτίδας

Όταν ελέγχετε πολλά μηνύματα, ομαδικά αιτήματα:

async function checkBatchStatus(messageIds, apiKey, batchSize = 10) {
  const results = [];

  for (let i = 0; i < messageIds.length; i += batchSize) {
    const batch = messageIds.slice(i, i + batchSize);
    const batchResults = await Promise.all(
      batch.map(id => checkStatus(id, apiKey))
    );
    results.push(...batchResults);

    // Rate limiting
    if (i + batchSize < messageIds.length) {
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }

  return results;
}

Περιπτώσεις χρήσης

Επιβεβαίωση παραγγελίας

Παρακολουθήστε την παράδοση των μηνυμάτων επιβεβαίωσης παραγγελίας:

const orderMessage = await sendMessage({
  to: customer.phone,
  text: `Order #${orderId} confirmed`
});

// Wait for delivery
const result = await waitForDelivery(orderMessage.messageId, apiKey);

if (result.success) {
  await updateOrder(orderId, { notificationSent: true });
} else {
  await scheduleRetry(orderId);
}

Έλεγχος ταυτότητας δύο παραγόντων

Επαληθεύστε την παράδοση OTP πριν από το χρονικό όριο:

const otpMessage = await sendOTP(userPhone, otpCode);

// Poll for delivery
const delivered = await waitForDelivery(
  otpMessage.messageId,
  apiKey,
  30 // 30 second timeout
);

if (!delivered.success) {
  // Send via alternative channel
  await sendEmailOTP(userEmail, otpCode);
}

Καμπάνιες μάρκετινγκ

Παρακολούθηση ποσοστών παράδοσης μηνυμάτων καμπάνιας:

const messageIds = await sendCampaign(recipientList);

// Check all statuses after 5 minutes
setTimeout(async () => {
  const statuses = await checkBatchStatus(messageIds, apiKey);

  const delivered = statuses.filter(s =>
    s.deliverystatus === 'delivered'
  ).length;

  console.log(`Delivery rate: ${delivered / statuses.length * 100}%`);
}, 5 * 60 * 1000);

Επόμενα βήματα

• Αποστολή μηνύματος - Μάθετε πώς να στέλνετε μηνύματα
• Οδηγός κατάστασης παράδοσης - Κατανοήστε τις καταστάσεις παράδοσης
• Fallback Strategies - Διαμόρφωση εναλλακτικών παραμέτρων