> ## 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.

# Delete a message

> Deletes a message the bot sent, for everyone, and erases its text, blocks, metadata and edit history. Works after the App was removed from the conversation. A message that is already deleted is `404 message_not_found`; treat both as success. Needs `messages:write`. Limited to 60 requests a minute per installation.



## OpenAPI

````yaml /openapi/staging.json delete /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 `<X-Workchats-Timestamp>.<raw body>`,

    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=<new>,v1=<old>`: 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}:
    delete:
      tags:
        - Messages
      summary: Delete a message
      description: >-
        Deletes a message the bot sent, for everyone, and erases its text,
        blocks, metadata and edit history. Works after the App was removed from
        the conversation. A message that is already deleted is `404
        message_not_found`; treat both as success. Needs `messages:write`.
        Limited to 60 requests a minute per installation.
      operationId: WorkchatsApiServerWeb.PublicApi.MessageController.delete
      parameters:
        - description: >-
            Message id, `gmsg_` or `dmsg_` prefixed, as `POST /v1/messages`
            returned it
          in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiOkResponse'
          description: Deleted
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
          description: '`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`'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiError'
          description: >-
            `message_not_found`: no such message, it was already 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'
        '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:
    PublicApiOkResponse:
      properties:
        ok:
          enum:
            - true
          type: boolean
      required:
        - ok
      title: PublicApiOkResponse
      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
  securitySchemes:
    bearerAuth:
      description: Bot token (`wc_bot_live_…` or `wc_bot_test_…`) from the OAuth install
      scheme: bearer
      type: http

````