API di messaggistica

API Stato del messaggio

Verifica se un messaggio inviato tramite l'API è ancora in coda, è stato inviato o non è riuscito. Usala per confermare che i messaggi importanti sono partiti e per scoprire perché uno non è partito.

POSThttps://wbiztool.com/api/v1/message/status/{msg_id}/

Corpo: JSON o campi di un modulo

Inserisci l'ID del messaggio nell'URL, sostituendo {msg_id} con il msg_id restituito da Invia messaggio, Invia a un gruppo, Invia a più numeri o Pianifica messaggio. Ad esempio: https://wbiztool.com/api/v1/message/status/9817263/.

Esempio rapido#

curl -X POST https://wbiztool.com/api/v1/message/status/9817263/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY"
  }'

import requests

msg_id = 9817263
response = requests.post(
    f"https://wbiztool.com/api/v1/message/status/{msg_id}/",
    json={
        "client_id": 12345,
        "api_key": "YOUR_API_KEY",
    },
    timeout=60,
)
result = response.json()  # read the body even when the HTTP code is 400

if result.get("message") == "Unknown message id":
    print("No message with this ID in your workspace")
elif "status_text" not in result:
    print("Request failed:", result.get("message", "no message in response"))
elif result["status"] == 1:
    print("Sent")
elif result["status"] == 2:
    print("Failed:", result["error"])
else:
    print("Status:", result["status_text"])

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const msgId = 9817263;
const response = await fetch(`https://wbiztool.com/api/v1/message/status/${msgId}/`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    client_id: 12345,
    api_key: "YOUR_API_KEY",
  }),
});
const result = await response.json(); // read the body even when the HTTP code is 400

if (result.message === "Unknown message id") {
  console.log("No message with this ID in your workspace");
} else if (!("status_text" in result)) {
  console.error("Request failed:", result.message ?? "no message in response");
} else if (result.status === 1) {
  console.log("Sent");
} else if (result.status === 2) {
  console.log("Failed:", result.error);
} else {
  console.log("Status:", result.status_text);
}

<?php
$msgId = 9817263;
$payload = [
    'client_id' => 12345,
    'api_key'   => 'YOUR_API_KEY',
];

$ch = curl_init("https://wbiztool.com/api/v1/message/status/{$msgId}/");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($result['message'] ?? '') === 'Unknown message id') {
    echo 'No message with this ID in your workspace';
} elseif (!isset($result['status_text'])) {
    echo 'Request failed: ' . ($result['message'] ?? 'no message in response');
} elseif ($result['status'] === 1) {
    echo 'Sent';
} elseif ($result['status'] === 2) {
    echo 'Failed: ' . $result['error'];
} else {
    echo 'Status: ' . $result['status_text'];
}

Sostituisci 12345 e YOUR_API_KEY con i tuoi valori. Consulta Autenticazione per sapere dove trovarli.

Parametri della richiesta#

URL

msg_idintegerobbligatorio: L'ID del messaggio, come parte del percorso dell'URL. Deve essere un numero intero e appartenere allo spazio di lavoro della tua chiave API.

Corpo

client_idintegerobbligatorio: Il tuo ID Client API, da Impostazioni → Chiavi API.
api_keystringobbligatorio: La tua chiave API, dalla stessa pagina.

Usare il client ufficiale#

Il client Python chiama questo endpoint per te.

Python

from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)

result = client.get_message_status(msg_id=9817263)
print(result.get("status_text"), result.get("error"))

Il client restituisce gli stessi campi dell'API, quindi result["status"] è lo stato del messaggio, non un indicatore di successo. Gli errori di autenticazione sollevano requests.HTTPError; leggi il motivo con e.response.json()["message"].

Risposta#

L'endpoint restituisce HTTP 200 con lo stato attuale del messaggio:

{
  "message": "Sent",
  "status": 1,
  "status_text": "Sent",
  "error": ""
}

Un messaggio non riuscito:

{
  "message": "Failed",
  "status": 2,
  "status_text": "Failed",
  "error": "Phone number invalid"
}

Campo	Tipo	Descrizione
`status`	integer	Il codice di stato del messaggio. Vedi la tabella sotto.
`status_text`	string	Nome dello stato: `Created`, `Sent`, `Failed`, `Cancelled` o `Expired`.
`message`	string	Stesso valore di `status_text`.
`error`	string or null	Il motivo per cui il messaggio non è riuscito. Sempre presente; vuoto (`""` o `null`) quando non c'è alcun errore.

Valori di stato#

`status`	`status_text`	Significato
`0`	`Created`	In coda o pianificato, in attesa di essere inviato.
`1`	`Sent`	Inviato dal tuo numero WhatsApp.
`2`	`Failed`	Non è stato possibile inviarlo, oppure l'invio è stato interrotto. `error` ne indica il motivo. Se `error` è `Sending was interrupted and may have been delivered. Check WhatsApp before resending.`, il destinatario potrebbe avere già il messaggio, quindi non inviarlo di nuovo automaticamente.
`3`	`Cancelled`	Annullato prima dell'invio, ad esempio con Annulla messaggio.
`4`	`Expired`	Non inviato prima della scadenza `expire_after_seconds`.

Sent è lo stato finale di successo. Questo endpoint non indica se il messaggio è stato consegnato al telefono o letto.

Esempi di valori di error per i messaggi non riusciti: Phone number invalid, Group not found, Image Url Error, File Url Error, Blocked Contact, File exceeds WhatsApp size limit (…), File type not supported, Sending was interrupted and may have been delivered. Check WhatsApp before resending.

Errori#

{
  "message": "Unknown message id",
  "status": 0,
  "status_text": "pending",
  "error": "Invalid message id"
}

Messaggio	Come risolvere
`Unknown message id`	Non esiste alcun messaggio con quell'ID nello spazio di lavoro della tua chiave API. Controlla l'ID e verifica di usare una chiave dello stesso spazio di lavoro.
`Auth Error`	Invia sia `client_id` sia `api_key`. Anche un corpo JSON non valido (ad esempio con una virgola finale) restituisce `Auth Error`.
`Invalid Client Id`	Invia `client_id` come numero. Restituito con HTTP `403`.
`Auth Error: invalid api key`	Verifica che la chiave esista, non sia stata eliminata e appartenga a questo `client_id`. Restituito con HTTP `400`.

Suggerimenti#

Preferisci i webhook per gli aggiornamenti in tempo reale: passa webhook quando invii il messaggio e Wbiztool ti avvisa quando viene inviato o non riesce, così non devi interrogare l'API periodicamente. I messaggi annullati e scaduti non attivano un webhook, quindi verificali qui.
Polling: se interroghi periodicamente l'API, fermati quando status non è più 0. Lascia qualche secondo tra un controllo e l'altro.
Molti messaggi insieme: per controllare i messaggi di un'intera giornata, usa Cronologia messaggi invece di chiamare questo endpoint per ogni ID.
I messaggi vecchi vengono eliminati: i messaggi inviati, non riusciti, annullati e scaduti che non vengono modificati per circa 90 giorni restituiscono Unknown message id. Lo stesso vale per i messaggi ancora in coda 90 giorni dopo la creazione o la pianificazione, su un numero disconnesso o eliminato.
Vecchie integrazioni: POST /api/v1/msg_status/ con msg_id nel corpo è deprecato. Restituisce gli stessi campi. Accetta anche GET con client_id, api_key e msg_id nella query string, il che espone la tua chiave API negli URL e nei log. Passa a questo endpoint.