message.unsend

POST /v1/commands/message.unsend

Takes back a message this line sent. The person sees it gone from the thread, marked Unsent. An unsend is allowed within 2 minutes of the message being sent.

Honours Idempotency-Key. The message this platform stores is not deleted: it stays in the thread with the text that was sent.

Target

The same as message.edit: name the message at target.messageId by the messageId its send's command frame carried, in the conversation at target.conversationId.

Payload

None. Send {} or leave payload out. Any key is 422 validation_failed at payload.<key>, a payload.text included: new text is an edit.

What is refused before anything is sent

Each is 422 validation_failed at target.messageId, and nothing reaches the line:

The line checks the window again from the message's own time, so an unsend let through seconds before the window closes may still settle failed with stale_target. While the line's sending is paused an unsend is refused at once, 503 upstream_unavailable with reason: outbound_paused, rather than held past its window.

Request

curl https://api.mapier.ai/v1/commands/message.unsend \
  -H "Authorization: Bearer $MAPIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unsend-0192a7c4" \
  -d '{
    "target": {
      "conversationId": "a0000000-0000-4000-8000-000000000001",
      "messageId": "0192a7c4-5a31-7bd2-8e6f-1d0c9b8a7f65"
    }
  }'

Response

{ "commandId": "cmd-12", "status": "queued", "disposition": "queued" }

Then a command frame, type: "message.unsend":

• succeeded once the line read the change back.
• failed with stale_target when the line no longer finds the message inside its window. An unsend that already worked, sent again under a new key, settles this way too: the message is no longer there to take back.
• failed with invalid_target.
• ambiguous with errorCode: "moderation_unverified" when the line could not prove what happened.

In test

The test line rehearses an unsend on the relay's own executor, against the sandbox phone, and settles it as a live line does. The refusals above are the same in test.

Errors

A command answers the one set of HTTP refusals POST /v1/commands/{type} publishes, so that table is the one to handle. What is particular to this type:

• 422 validation_failed at target.messageId or payload.<key>, above.
• 404 unsupported_command with reason: not_on_channel on a line of any other channel.
• 503 upstream_unavailable with reason: outbound_paused while the line's sending is paused.

Settlement codes you will see for this command: stale_target, invalid_target, moderation_unverified. See Error codes.

Related