Messaging API
Cancel Message API
Cancel a WhatsApp message that hasn't been sent yet. Use it to stop a scheduled reminder after an appointment is cancelled, or to pull back a queued message sent by mistake.
https://wbiztool.com/api/v1/cancel_msg/Body: JSON or form fields
You can cancel any message that's still waiting to be sent (status 0, Created): scheduled messages, and messages queued by Send message, Send to group or Send to multiple numbers. A message that has already been sent can't be recalled. If a bot is already sending the message at that moment, it may still go out, so for critical cancellations confirm with Message status.
Quick example#
curl -X POST https://wbiztool.com/api/v1/cancel_msg/ \
-H "Content-Type: application/json" \
-d '{
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"msg_id": 9817263
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/cancel_msg/",
json={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"msg_id": 9817263,
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("status") == 1:
print("Message cancelled")
else:
print("Not cancelled:", result.get("message", "no message in response"))// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/cancel_msg/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: 12345,
api_key: "YOUR_API_KEY",
msg_id: 9817263,
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.status === 1) {
console.log("Message cancelled");
} else {
console.error("Not cancelled:", result.message ?? "no message in response");
}<?php
$payload = [
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'msg_id' => 9817263,
];
$ch = curl_init('https://wbiztool.com/api/v1/cancel_msg/');
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['status'] ?? 0) === 1) {
echo 'Message cancelled';
} else {
echo 'Not cancelled: ' . ($result['message'] ?? 'no message in response');
}Replace 12345 and YOUR_API_KEY with your own values, and 9817263 with the msg_id you got when you sent or scheduled the message.
Request parameters#
client_idintegerrequiredYour API Client ID from Settings → API keys.
api_keystringrequiredYour API key from the same page.
msg_idintegerrequiredThe
msg_idreturned by the send or schedule request. It must belong to the workspace of your API key.
This endpoint doesn't need whatsapp_client.
Using the official clients#
The Python and Node.js clients call this endpoint for you.
from wbiztool_client import WbizToolClient
client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)
result = client.cancel_message(msg_id=9817263)
print(result)const { WbizToolClient } = require("wbiztool-client");
const client = new WbizToolClient({
clientId: 12345,
apiKey: "YOUR_API_KEY",
whatsappClient: 678, // required by the client's constructor, not used by this endpoint
});
(async () => {
const result = await client.cancelMessage(9817263);
console.log(result);
})().catch(console.error);Both clients throw on authentication errors (HTTP 400/403): Python raises requests.HTTPError, and Node.js throws API error: 400 - {…}. A Msg has been … reply comes back as a normal result with status: 0.
Response#
A successful request returns HTTP 200:
{
"message": "Cancelled",
"status": 1
}
| Field | Type | Description |
|---|---|---|
status | integer | 1 if the message was cancelled, 0 if it wasn't. |
message | string | Cancelled on success, otherwise the reason. |
After cancelling, Message status reports the message as 3 (Cancelled). A cancelled message isn't sent, doesn't trigger its webhook and no longer counts against your remaining credits.
Errors#
Most errors return HTTP 200 with status set to 0, so always check status in the body:
{ "message": "Msg has been Sent", "status": 0 }
| Message | How to fix it |
|---|---|
Msg has been Sent | The message was already sent. It can't be cancelled. |
Msg has been Failed | The message already failed, so there's nothing to cancel. |
Msg has been Cancelled | The message was cancelled earlier. |
Msg has been Expired | The message expired before it was sent, so there's nothing to cancel. |
No msg found for given msg_id | Check the msg_id. It must be a number and belong to the same workspace as your API key. |
Msg_id cant be null | Add msg_id. |
Auth Error | Send both client_id and api_key. |
Invalid Client Id | Send client_id as a number. Returned with HTTP 403. |
Auth Error: invalid api key | Check the key exists, hasn't been deleted and belongs to this client_id. Returned with HTTP 400. |
Invalid JSON format: … | The JSON body isn't valid, often because of a trailing comma, or you sent form fields without client_id. |
Empty object {} | A JSON body was sent with a method other than POST. |
Tips#
- Save every
msg_id: you need it to cancel. For Send to multiple numbers, cancel eachmsg_idin the response separately. - Cancel early: once a message has been sent it stays sent, so cancel scheduled messages as soon as you know they're no longer needed.
- Rescheduling: there's no endpoint to change a scheduled time. Cancel the message and schedule a new one.
- Treat already-final messages as done: a
Msg has been …reply means the message is no longer in the queue, so you don't need to retry.
