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.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 part0 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
The Chert
message_id returned by a send endpoint, or the outbound message id surfaced on chat-message listings.Body
Zero-based text-part index. Native-edit-enabled lines require
0 and a single original text part; other lines retain their existing part support.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.
Response fields
"edit_requested" acknowledges the native operation. "edited" is the existing local-result variant. Neither is recipient delivery.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 withretryable: 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.
