Skip to main content
Auth. HMAC v1 or bearer token — see Authentication. Availability. Line-enabled. The newer native-edit path requires a stable idempotency_key and acknowledges with 202 edit_requested. Existing edit-enabled lines can retain 200 edited; do not assume identical retry semantics.
Replaces the text of a previously-sent outbound message. Eligible recipients can show the bubble updated in place with an “Edited” marker. A successful response does not confirm recipient receipt; older recipient software can show a follow-up message. Apple enforces a 15-minute window from send time — edits attempted after the window return an error.

Which id goes in the URL

This is a message-scoped route: {id} is a message_id, not a chat_id. Prefer the Chert-issued message_id returned by POST /api/v1/send, or the message.id returned by POST /api/v1/chats and POST /api/v1/chats/{id}/messages. Chert resolves that id to the underlying iMessage identifier internally before applying the edit.
For outbound messages surfaced by GET /api/v1/chats/{id}/messages, the listed message id is also accepted.

Eligible messages

On native-edit-enabled lines, use the original Chert send receipt for one outbound, single-text-part iMessage in an existing phone-addressed direct chat. Only part 0 is supported. Groups, email recipients, SMS/RCS, media, replies, effects, and multipart originals are outside this rollout. The original sender must still be authorized. Other edit-enabled lines retain their existing scope.

Request

POST /api/v1/messages/{id}/edit

Response

202 edit_requested confirms acceptance of the edit operation, not the recipient’s updated bubble. 200 edited describes the existing path’s local result and also does not confirm recipient receipt. Branch on the actual status and response; do not require fields from the other response variant.

Path parameters

string
required
The Chert message_id returned by a send endpoint, or the outbound message id surfaced on chat-message listings.

Body

string
required
The replacement bubble text. Empty strings are rejected.
integer
default:"0"
Zero-based text-part index. Native-edit-enabled lines require 0 and a single original text part; other lines retain their existing part support.
string
Required for native-edit-enabled lines: a nonempty key up to 128 characters. Keep it for this exact message, part, and replacement text. Different content under the same key conflicts. Other edit paths do not gain idempotency merely because you include this field.
Native-edit replacement text is limited to 16,384 UTF-8 bytes.

Response fields

string
"edit_requested" acknowledges the native operation. "edited" is the existing local-result variant. Neither is recipient delivery.
string
Echoed-back message_id of the edited bubble.
string
Present on the edited variant: the replacement text requested.
string
Present on the edited variant: reported local edit time, not recipient delivery time.
array | null
Optional on the edited variant. An edit_requested response does not include recipient edit history.

Errors

See the full error code reference.

Notes

See also

A new key represents a new edit and can consume another edit attempt. Never change keys to work around an uncertain result. An error with retryable: false must not trigger an automatic edit retry. Preserve the original request and reconcile its outcome before submitting another edit. Customer edit webhooks are not currently provided.