> ## Documentation Index > Fetch the complete documentation index at: https://developers.workchats.com/llms.txt > Use this file to discover all available pages before exploring further. # Edit a message > Replaces the text and blocks of a message the bot sent. `blocks` left out clears the old ones. `metadata`, when given, is merged into the stored metadata. `to`, `thread_id` and `unfurl_links` are ignored. Needs `messages:write`. Limited to 60 requests a minute per installation. ## OpenAPI ````yaml /openapi/staging.json patch /v1/messages/{id} openapi: 3.0.0 info: contact: email: support@workchats.com name: Workchats API Support description: > Post messages into Workchats as an installed App's bot user, and read the people and conversations it can reach. Authenticate with the bot token from the OAuth install, in the Authorization header as `Bearer wc_bot_…`. Every error response has the shape `{"ok": false, "error": {"code", "message"}, "request_id"}`. Lists are cursor-paginated: pass `limit` (default 200, at most 1000) and the previous page's `next_cursor` as `cursor`. `next_cursor` is null on the last page. ## Callbacks Workchats POSTs events to the App's registered callback URL, over HTTPS only. Answer with any 2xx within 3 seconds. Anything else, including a redirect, which is never followed, is retried after 1, 5 and 30 minutes with the same event `id`, so ignore an `id` you have already handled. `X-Workchats-Attempt` counts the attempts from 1. Every event has the shape `{"id", "type", "workspace_id", "created_at", "data"}`: - `app.uninstalled`: `data` is `{"removed_by": {"id": "usr_…"} | null, "reason": "admin" | "app_disabled"}`. A company admin uninstalled the App, or Workchats disabled it (`removed_by` is null). The token has already stopped working. Revoking the token yourself through `POST /oauth/revoke` sends nothing. - `directory.changed`: `data` is `{"kind", "id"}`. Re-read the user with `GET /v1/users/{id}` or the conversation with `GET /v1/conversations/{id}`. Kinds: `user.created`, `user.updated` (name, email or title), `user.deactivated` (deactivated or removed), `conversation.created` (the bot was added), `conversation.renamed`, `conversation.archived` (groups), `conversation.deleted`, `app.removed_from_conversation`. User kinds need `users:read`; conversation kinds name only conversations the bot is, or was just, in. Ignore kinds you don't know. **Verifying a callback.** `X-Workchats-Signature` is `v1=` and the lower-case hex HMAC-SHA256 of `.`, keyed with the App's signing secret. Compare in constant time, and refuse a timestamp more than 5 minutes old. For 24 hours after the secret is rotated the header carries two signatures, `v1=,v1=`: accept the request if any one matches. Worked example: - Signing secret: `whsec_docs_example` - X-Workchats-Timestamp: 1790593600 - Body: `{"id":"evt_5f0c7a52-6d1e-4c1b-9a8e-2f4b7c3d1e90","type":"directory.changed","workspace_id":"cmp_0b7e4c1a-2d3f-4a5b-8c6d-7e8f9a0b1c2d","created_at":"2026-09-28T11:06:40Z","data":{"kind":"user.deactivated","id":"usr_9a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"}}` - X-Workchats-Signature: v1=42ec825e4ad44370ea02385d30a001c349640cff974ed895361b3c7a080e5339 title: Workchats Public API version: '1.0' servers: - url: https://public-api.staging.workchats.com variables: {} security: - bearerAuth: [] tags: - description: Token checks name: Auth - description: Groups and channels the bot is a member of, and their messages name: Conversations - description: Files attached to messages the bot can read name: Files - description: Send, edit and delete the bot's messages name: Messages - description: Code exchange and token revocation name: OAuth - description: The workspace's people name: Users paths: /v1/messages/{id}: patch: tags: - Messages summary: Edit a message description: >- Replaces the text and blocks of a message the bot sent. `blocks` left out clears the old ones. `metadata`, when given, is merged into the stored metadata. `to`, `thread_id` and `unfurl_links` are ignored. Needs `messages:write`. Limited to 60 requests a minute per installation. operationId: WorkchatsApiServerWeb.PublicApi.MessageController.update parameters: - description: >- Message id, `gmsg_` or `dmsg_` prefixed, as `POST /v1/messages` returned it in: path name: id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/PublicApiMessageUpdateRequest' description: The new content required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/PublicApiMessageResponse' description: The edited message '400': content: application/json: schema: $ref: '#/components/schemas/PublicApiError' description: >- `invalid_blocks`, `invalid_request` (a missing or bad field, or `metadata` over 4 KB after the merge) or `token_in_query` '401': content: application/json: schema: $ref: '#/components/schemas/PublicApiError' description: '`not_authed`, `invalid_auth` or `token_revoked`' '403': content: application/json: schema: $ref: '#/components/schemas/PublicApiError' description: >- `missing_scope` (the token lacks `messages:write`) or `not_in_conversation` (the App was removed from the conversation) '404': content: application/json: schema: $ref: '#/components/schemas/PublicApiError' description: >- `message_not_found`: no such message, it was deleted, or the App did not send it '406': content: application/json: schema: $ref: '#/components/schemas/PublicApiError' description: '`not_acceptable`: the Accept header does not allow application/json' '413': content: application/json: schema: $ref: '#/components/schemas/PublicApiError' description: '`payload_too_large`: the request body is too large' '415': content: application/json: schema: $ref: '#/components/schemas/PublicApiError' description: '`unsupported_media_type`: the body is not `application/json`' '429': content: application/json: schema: $ref: '#/components/schemas/PublicApiError' description: '`rate_limited`: retry after the Retry-After header''s seconds' '500': content: application/json: schema: $ref: '#/components/schemas/PublicApiError' description: '`internal_error`: something went wrong on our side' callbacks: {} security: - bearerAuth: [] components: schemas: PublicApiMessageUpdateRequest: example: text: Claimed by Connor properties: blocks: description: Replaces the old blocks. Leave it out to remove them. items: $ref: '#/components/schemas/PublicApiBlock' maxItems: 50 type: array metadata: additionalProperties: true description: >- Merged into the stored metadata, key by key. At most 4 KB after the merge. type: object text: maxLength: 4000 minLength: 1 type: string required: - text title: PublicApiMessageUpdateRequest type: object PublicApiMessageResponse: example: message: conversation_id: dm_77a1b2c3-d4e5-4f60-8a7b-9c0d1e2f3a4b created_at: '2026-09-28T11:05:12Z' id: dmsg_4e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b thread_id: null ok: true properties: message: properties: conversation_id: description: >- `grp_` or `chn_` for a group or channel, `dm_` for a direct message type: string created_at: format: date-time type: string id: description: '`gmsg_` in a group or channel, `dmsg_` in a direct message' type: string thread_id: description: The message this one replies to nullable: true type: string required: - id - conversation_id - thread_id - created_at type: object ok: enum: - true type: boolean required: - ok - message title: PublicApiMessageResponse type: object PublicApiError: description: Every non-2xx response from the public API. example: error: code: token_revoked message: The token has been revoked. ok: false request_id: F7p0mJcXk3tq2x0AAAAB properties: error: properties: code: description: >- Stable, machine-readable error code. Each code always comes with the same HTTP status, except `client_error` and `server_error`, which carry the response's own 4xx or 5xx status. New codes may be added; treat an unknown one as a generic failure. type: string x-extensible-enum: - cannot_dm_user - client_error - conversation_archived - conversation_not_found - file_not_found - idempotency_key_reused - internal_error - invalid_auth - invalid_blocks - invalid_client - invalid_cursor - invalid_grant - invalid_request - message_not_found - missing_idempotency_key - missing_scope - not_acceptable - not_allowed_in_conversation - not_authed - not_found - not_in_conversation - payload_too_large - rate_limited - server_error - token_in_query - token_revoked - unsupported_grant_type - unsupported_media_type - user_deactivated - user_not_found message: description: Human-readable explanation type: string required: - code - message type: object ok: enum: - false type: boolean request_id: description: Also sent as the X-Request-Id header. Quote it to support. type: string required: - ok - error - request_id title: PublicApiError type: object PublicApiBlock: description: >- One block of a rich message layout. `header`, `section` and `context` take `text`; `fields` takes 1 to 10 `fields`; `actions` takes 1 to 5 button `elements`; `divider` takes nothing. Any other field is `invalid_blocks`. properties: elements: items: $ref: '#/components/schemas/PublicApiButton' maxItems: 5 minItems: 1 type: array fields: items: properties: label: minLength: 1 type: string value: type: string required: - label - value type: object maxItems: 10 minItems: 1 type: array text: description: >- For `section`: Markdown with `**bold**`, `_italic_`, `[label](url)` and line breaks minLength: 1 type: string type: enum: - header - section - fields - actions - context - divider type: string required: - type title: PublicApiBlock type: object PublicApiButton: description: >- A link button (`url`) or an action button (`action_id`, optional `value`), never both. Action buttons are not shown until a later release. properties: action_id: minLength: 1 type: string style: enum: - primary - danger type: string text: minLength: 1 type: string type: enum: - button type: string url: description: An http or https link format: uri type: string value: type: string required: - type - text title: PublicApiButton type: object securitySchemes: bearerAuth: description: Bot token (`wc_bot_live_…` or `wc_bot_test_…`) from the OAuth install scheme: bearer type: http ````