DELETE/v1/messages/{id}

Cancel a message

Cancels a message that has not been sent yet — one still waiting, queued or pending. A message already handed to WhatsApp cannot be recalled and answers 409.

AuthenticationDevice token

Request

shell

curl -X DELETE https://api.sapa.tokoaplikasi.id/v1/messages/01JQ8T4Z2KX9V6WQ0N3B7C5D2E \
  -H "Authorization: Bearer $WA_TOKEN"

Path parameters

Field	Type	Description
idrequired	string	The message id, from the `id` array POST /v1/send returned.

Response

200 — The cancelled message, now in a terminal state.

json

{
  "status": true,
  "message": {
    "id": "",
    "deviceId": "",
    "requestId": "",
    "direction": "out",
    "targetInput": "",
    "jid": "",
    "lid": "",
    "kind": "text",
    "content": {
      "kind": "text",
      "text": ""
    },
    "status": "waiting",
    "waMessageId": "",
    "error": "",
    "scheduledAt": "2026-09-04T09:12:03Z",
    "queuedAt": "2026-09-04T09:12:03Z",
    "sentAt": "2026-09-04T09:12:03Z",
    "deliveredAt": "2026-09-04T09:12:03Z",
    "readAt": "2026-09-04T09:12:03Z",
    "senderJid": "",
    "senderLid": "",
    "pushName": "",
    "participant": "",
    "createdAt": "2026-09-04T09:12:03Z"
  }
}

Field	Type	Description
status	true	Always true on a successful request.
message	object	The message, with its current status and timestamps.
message.id	string	The message id, as returned in the `id` array of POST /v1/send.
message.deviceId	string	The device that sent or received this message.
message.requestId	string \| null	The `requestid` of the send that created it. Null on a received message.
message.direction	string	`out` for a message this device sent, `in` for one it received. One of out · in.
message.targetInput	string \| null	The recipient exactly as you wrote it, before normalization.
message.jid	string \| null	The chat address in phone-number form, e.g. `628123456789@s.whatsapp.net`.
message.lid	string \| null	The chat's WhatsApp linked identity. This, not `jid`, is the stable identifier — treat both as opaque strings and never split them on `@`.
message.kind	string	What kind of content the message carries. Inferred from the fields you sent. One of text · image · video · audio · document · location · poll.
message.content	object	The message content, discriminated by `kind`.
message.status	string	Where the message is in its lifecycle. It only ever moves forward: `waiting` (scheduled) → `queued` → `processing` → `sent` → `delivered` → `read` → `played`. `pending` is the accepted-but-not-yet-queued moment, and `invalid`, `failed` and `expired` are terminal. One of waiting · queued · processing · sent · delivered · read · played · pending · invalid · failed · expired.
message.waMessageId	string \| null	WhatsApp's own id for the message. Null until it has been sent.
message.error	string \| null	Why a `failed` or `invalid` message did not go out. Null otherwise.
message.scheduledAt	string \| null	When a scheduled message is due to send. Null for an immediate one.
message.queuedAt	string \| null	When the message was handed to the sender.
message.sentAt	string \| null	When WhatsApp accepted it — one tick on the sender's screen.
message.deliveredAt	string \| null	When it reached the recipient device — two ticks.
message.readAt	string \| null	When the recipient opened it — blue ticks, if they share receipts.
message.senderJid	string \| null	Who wrote a received message, in phone-number form. Null on a sent message.
message.senderLid	string \| null	The author's linked identity. Null on a sent message.
message.pushName	string \| null	The display name the author has set. Null on a sent message.
message.participant	string \| null	The individual sender inside a group chat. Null outside groups.
message.createdAt	string	When the gateway first recorded the message, ISO 8601.

content when kind is "text"

Field	Type	Description
kind	"text"	Discriminator — always `text` for this variant.
text	string	The message body, after template substitution.

content when kind is "image"

Field	Type	Description
kind	"image"	Discriminator — always `image` for this variant.
mediaId	string	Opaque id of the stored object the gateway sent. Absent on a received message.
mimetype	string	The media type, e.g. `image/jpeg`.
url	string	The `url` you asked the gateway to fetch. An echo — it is never fetched again.
caption	string	Text shown alongside the media.
filename	string	The file name the recipient sees.

content when kind is "video"

Field	Type	Description
kind	"video"	Discriminator — always `video` for this variant.
mediaId	string	Opaque id of the stored object the gateway sent. Absent on a received message.
mimetype	string	The media type, e.g. `image/jpeg`.
url	string	The `url` you asked the gateway to fetch. An echo — it is never fetched again.
caption	string	Text shown alongside the media.
filename	string	The file name the recipient sees.

content when kind is "audio"

Field	Type	Description
kind	"audio"	Discriminator — always `audio` for this variant.
mediaId	string	Opaque id of the stored object the gateway sent. Absent on a received message.
mimetype	string	The media type, e.g. `image/jpeg`.
url	string	The `url` you asked the gateway to fetch. An echo — it is never fetched again.
caption	string	Text shown alongside the media.
filename	string	The file name the recipient sees.

content when kind is "document"

Field	Type	Description
kind	"document"	Discriminator — always `document` for this variant.
mediaId	string	Opaque id of the stored object the gateway sent. Absent on a received message.
mimetype	string	The media type, e.g. `image/jpeg`.
url	string	The `url` you asked the gateway to fetch. An echo — it is never fetched again.
caption	string	Text shown alongside the media.
filename	string	The file name the recipient sees.

content when kind is "location"

Field	Type	Description
kind	"location"	Discriminator — always `location` for this variant.
latitude	number	Decimal degrees, −90 to 90.
longitude	number	Decimal degrees, −180 to 180.

content when kind is "poll"

Field	Type	Description
kind	"poll"	Discriminator — always `poll` for this variant.
name	string	The poll question.
choices	string[]	The options offered, 2 to 12 of them.
selectableCount	integer	How many options a voter may pick. 1 for a single-answer poll.

Failure modes

Every failure answers with the same envelope: { "status": false, "reason": "…" }. Match on reason, never on the status alone — the full vocabulary is on the Errors page.

Field	Type	Description
401	error	The token is missing, malformed or revoked.
403	error	An account token was used; these need the device token.
404	error	No message with that id belongs to this device. A message that is somebody else's answers the same way — the id is never confirmed to exist.
409	error	The message has moved past the state this call needs — it has already been handed to WhatsApp.
429	error	Too many requests for this token. Wait the seconds in `retryAfter`.