Help Center Controlla lo stato del messaggio

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

ParametroDigitareObbligatorioDescrizione
messaggioIdstringaSìIdentificatore univoco del messaggio dalla risposta all’invio

Autenticazione

Utilizza uno dei tre metodi di autenticazione:

=== “Intestazione chiave API”

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

=== “Autenticazione HTTP di base”

__CODICE_BLOCCO_2__

=== “Chiave API come password”

```bash
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

CampoDigitareDescrizione
messagelistIdinteroIdentificatore del lotto
messaggioIdstringaIdentificatore univoco del messaggio
stato di consegnastringaStato di consegna attuale
contapezziinteroNumero di parti del messaggio
costonumeroCosto 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

StatoDescrizione
programmatoIn coda per l’invio
”elaborazione”Attualmente in fase di invio
consegnatoConsegnato con successo
non consegnabileConsegna fallita, messaggio rifiutato
errorepermanenteRimosso 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