Withdraw a message we sent from the customer's device

POST 
/api/conversations/:conversationId/messages/:messageId/retract

Take back one of OUR messages — Telegram only, and only inside the 48 hours its deleteMessage allows. Read Conversation.capabilities.unsend before drawing the affordance: outbound says the channel can do it at all, window_hours says for how long, and both must be applied per message against its created_at.

The row is KEPT, with its body blanked and meta.retracted: true — the identical shape a customer's own withdrawal produces, so the thread renders one thing rather than two. meta.retracted_by (agent here, contact for theirs) and meta.retracted_by_user_id record who did it.

NOT a delete of our copy — that is DELETE /api/conversations/\{conversationId\}/messages/\{messageId\}, which does the opposite: removes our record and leaves the customer's.

Our speech only. Telegram would also let a bot erase the customer's own message from a private chat, silently and with no Update to say it happened; this product does not, and asking for it here returns reason: not_ours.

Idempotent: retracting an already-retracted message returns it unchanged. Authorized through the conversation reply ability.

Request

Responses

200

Withdrawn. The message, with an empty body and meta.retracted.

401

Not authenticated. code: account_disabled means the member's seat was deactivated in this workspace: the session is over even though the token was not revoked (clients sign out and clean up).

403

Authenticated but not allowed.

404

Resource not found (or not visible to the current tenant).

422

Refused, with a stable reason a client turns into its own wording rather than showing a raw sentence:

• unsupported_channel — this channel cannot withdraw at all.
• not_ours — the message is the customer's, not ours.
• window_expired — past the channel's unsend.window_hours.
• not_sent — it never reached the customer (a failure, a draft).
• parts_unknown — it went out as several platform messages and not all of their ids were recorded, so a withdrawal would be partial while reading as total.
• channel_unconfigured — no usable token or chat id.
• partially_withdrawn — some parts of a multi-part message were removed and one refused, so the customer is holding half of it. Its own answer rather than provider_refused, because the two leave the agent with opposite problems.
• provider_refused — the platform itself said no and nothing was removed; message carries its words.