Vai al contenuto

Controlla lo stato del messaggio

Tieni traccia dello stato di consegna dei tuoi messaggi utilizzando l'endpoint di controllo dello stato.

Punto finale

GET /bat/message/{messageId}

Richiesta

Parametri URL

Parametro Digitare Obbligatorio Descrizione
messaggioId stringa Sì Identificatore univoco del messaggio dalla risposta all'invio

Autenticazione

Utilizza uno dei tre metodi di autenticazione:

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

CODICE_BLOCCO_2

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

Risposta

Risposta di base

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

Campi di risposta

Campo Digitare Descrizione
messagelistId intero Identificatore del lotto
messaggioId stringa Identificatore univoco del messaggio
stato di consegna stringa Stato di consegna attuale
contapezzi intero Numero di parti del messaggio
costo numero Costo del messaggio in unità monetarie

Risposta estesa (con fallback)

Quando è configurato il fallback, la risposta include campi aggiuntivi:

CODICE_BLOCCO_5

Valori dello stato di consegna

Stato Descrizione
programmato In coda per l'invio
"elaborazione" Attualmente in fase di invio
consegnato Consegnato con successo
non consegnabile Consegna fallita, messaggio rifiutato
errorepermanente Rimosso dalla coda a causa di un errore persistente

Ciclo di vita dello stato

CODICE_BLOCCO_6

Programmato

Il messaggio viene accettato e messo in coda per la consegna:

CODICE_BLOCCO_7

Elaborazione

Il messaggio è attualmente inviato al destinatario:

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

Consegnato

Messaggio consegnato con successo al destinatario:

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

Non consegnabile

Impossibile consegnare il messaggio (numero non valido, errore di rete):

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

Errore permanente

Messaggio rimosso dalla coda a causa di problemi di consegna persistenti:

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

Controlla più messaggi

Controlla lo stato di più messaggi nella tua applicazione:

CODICE_BLOCCO_12

Interrogazione per aggiornamenti di stato

Interrogare l'endpoint di stato per monitorare la consegna:

// 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 };
}

Alternativa al webhook

Invece del polling, utilizza i webhook per gli aggiornamenti di stato in tempo reale:

CODICE_BLOCCO_14

Contatta il tuo account manager per configurare l'URL del webhook.

Esempi di implementazione

Pitone

CODICE_BLOCCO_15

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

CODICE_BLOCCO_17

Migliori pratiche

Frequenza di polling

  • ✅ Sondaggio ogni 5-10 secondi
  • ✅ Implementa il backoff esponenziale
  • ✅ Imposta un timeout ragionevole (60-120 secondi)
  • ❌Non effettuare sondaggi più di una volta al secondo
  • ❌Non fare sondaggi a tempo indeterminato

Gestione degli errori

CODICE_BLOCCO_18

Memorizzazione nella cache

Risultati dello stato della cache per ridurre le chiamate API:

CODICE_BLOCCO_19

Elaborazione batch

Quando si controllano molti messaggi, le richieste batch:

CODICE_BLOCCO_20

Casi d'uso

Conferma dell'ordine

Tieni traccia della consegna dei messaggi di conferma dell'ordine:

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

Autenticazione a due fattori

Verifica la consegna OTP prima del timeout:

CODICE_BLOCCO_22

Campagne di marketing

Tieni traccia delle tariffe di consegna dei messaggi della campagna:

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

Passaggi successivi