בדוק את סטטוס ההודעה

עקוב אחר מצב המסירה של ההודעות שלך באמצעות נקודת הקצה של בדיקת המצב.

נקודת קצה

GET /bat/message/{messageId}

בקשה

פרמטרים של כתובת אתר

פרמטר	הקלד	חובה	תיאור
messageId	מחרוזת	כן	מזהה הודעה ייחודי מתגובת השליחה

אימות

השתמש בכל אחת משלוש שיטות האימות:

כותרת מפתח APIאימות בסיסי HTTPמפתח 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	מחרוזת	מזהה הודעה ייחודי
סטטוס משלוח	מחרוזת	מצב מסירה נוכחי
חלקים ספירת	מספר שלם	מספר חלקי ההודעה
עלות	מספר	עלות הודעה ביחידות מטבע

תגובה מורחבת (עם סתירה)

כאשר מוגדרת החזרה, התגובה כוללת שדות נוספים:

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

במקום סקר, השתמש ב-webhooks לעדכוני סטטוס בזמן אמת:

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

צור קשר עם מנהל החשבון שלך כדי להגדיר את כתובת האתר של webhook.

דוגמאות ליישום

פייתון

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);

השלבים הבאים

• שלח הודעה - למד כיצד לשלוח הודעות
• מדריך סטטוס משלוח - הבן סטטוסי משלוח
• אסטרטגיות מיתון - הגדר ניתוק