メッセージングAPI

メッセージのステータスAPI

API経由で送信したメッセージが、まだキューにあるのか、送信済みなのか、失敗したのかを確認します。重要なメッセージが送信されたことの確認や、送信されなかった理由の調査に利用できます。

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

リクエストボディ: JSONまたはフォームフィールド

メッセージIDはURLに含めます。{msg_id}を、メッセージ送信、グループに送信、複数の番号に送信、メッセージの予約で返されたmsg_idに置き換えてください。例：https://wbiztool.com/api/v1/message/status/9817263/

クイック例#

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'];
}

12345とYOUR_API_KEYはご自身の値に置き換えてください。値の確認場所は認証をご覧ください。

リクエストパラメータ#

URL

msg_idinteger必須: メッセージIDで、URLパスの一部として指定します。整数で、APIキーのワークスペースに属している必要があります。

ボディ

client_idinteger必須: 設定 → APIキーに表示されるAPIクライアントIDです。
api_keystring必須: 同じページにあるAPIキーです。

公式クライアントを使う#

Pythonクライアントは、このエンドポイントを代わりに呼び出します。

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

クライアントはAPIと同じフィールドを返すため、result["status"]は成功フラグではなくメッセージの状態です。認証エラーではrequests.HTTPErrorが発生します。理由はe.response.json()["message"]で確認してください。

レスポンス#

このエンドポイントは、メッセージの現在の状態をHTTP 200で返します。

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

失敗したメッセージの場合：

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

フィールド	型	説明
`status`	integer	メッセージのステータスコード。下の表を参照してください。
`status_text`	string	ステータス名：`Created`、`Sent`、`Failed`、`Cancelled`、`Expired`のいずれか。
`message`	string	`status_text`と同じ値。
`error`	string or null	メッセージが失敗した理由。常に含まれ、エラーがない場合は空（`""`または`null`）です。

ステータスの値#

`status`	`status_text`	意味
`0`	`Created`	キューに登録済みまたは予約済みで、送信待ちです。
`1`	`Sent`	あなたのWhatsApp番号から送信されました。
`2`	`Failed`	送信できなかったか、送信が中断されました。理由は`error`に記載されます。`error`が`Sending was interrupted and may have been delivered. Check WhatsApp before resending.`の場合、受信者はすでにメッセージを受け取っている可能性があるため、自動で再送しないでください。
`3`	`Cancelled`	送信前にキャンセルされました（例：メッセージのキャンセルを使用）。
`4`	`Expired`	`expire_after_seconds`の期限までに送信されませんでした。

Sentが成功の最終状態です。このエンドポイントは、メッセージが相手の端末に配信されたか、既読になったかは返しません。

失敗したメッセージのerrorの値の例：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.。

エラー#

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

メッセージ	対処方法
`Unknown message id`	そのIDのメッセージがAPIキーのワークスペースに存在しません。IDと、同じワークスペースのキーを使っていることを確認してください。
`Auth Error`	`client_id`と`api_key`の両方を送信してください。無効なJSONボディ（末尾のカンマなど）でも`Auth Error`が返されます。
`Invalid Client Id`	`client_id`を数値で送信してください。HTTP `403`で返ります。
`Auth Error: invalid api key`	キーが存在し、削除されておらず、この`client_id`に属していることを確認してください。HTTP `400`で返ります。

ヒント#

リアルタイムの更新にはWebhookを使う：メッセージの送信時にwebhookを指定すると、送信されたとき、または失敗したときにWbiztoolから通知されるため、ポーリングの必要がありません。キャンセルされたメッセージや期限切れのメッセージではWebhookは送信されないため、それらはこのエンドポイントで確認してください。
ポーリング：ポーリングする場合は、statusが0でなくなった時点で止めてください。確認の間隔は数秒空けてください。
多数のメッセージをまとめて確認：1日分のメッセージを確認するには、IDごとにこのエンドポイントを呼び出す代わりに、メッセージ履歴を使用してください。
古いメッセージは削除される：送信済み、失敗、キャンセル済み、期限切れのメッセージで約90日間変更のないものは、Unknown message idを返します。切断または削除された番号で、作成または予約から90日経ってもキューに残っているメッセージも同様です。
古い連携：ボディにmsg_idを含めるPOST /api/v1/msg_status/は非推奨です。同じフィールドを返します。また、クエリ文字列にclient_id、api_key、msg_idを含めるGETも受け付けますが、APIキーがURLやログに露出します。このエンドポイントに切り替えてください。