---
title: "Delete a scheduled message"
method: DELETE
path: "/scheduled_messages/{id}"
tags: ["product:chat"]
---

# Delete a scheduled message

`DELETE /scheduled_messages/{id}`

## Request

- Base URL: `https://chat.stream-io-api.com`
- URL: `https://chat.stream-io-api.com/scheduled_messages/{id}`
- Auth: one of:
  - API key in header `Authorization` and API key in query parameter `api_key` and API key in header `Stream-Auth-Type`
  - API key in query parameter `api_key` and API key in header `Stream-Auth-Type`

Cancels a scheduled message so it is never sent, or removes a failed one. Returns 409 while the message is being sent

Sends events:
- scheduled_message.deleted

## Path parameters

- `id` string, required: ID of the scheduled message

## Response `200`

Successful response

- DeleteScheduledMessageResponse, nullable
  - `duration` string, required: Duration of the request in milliseconds
  - `scheduled_message` ScheduledMessageResponse, required: A message scheduled to be sent later
    - `channel` ScheduledMessageChannelResponse: The channel of a scheduled message
      - `cid` string, required: Channel CID (<type>:<id>)
      - `id` string, required: Channel ID
      - `image` string: Channel image, from its custom data
      - `name` string: Channel name, from its custom data
      - `type` string, required: Channel type
    - `cid` string, required: The CID of the channel the message will be sent to
    - `created_at` string, date-time, required: Date/time of creation
    - `failure_reason` string: Why sending the message failed. Only set when status is failed. One of: banned, no_permission, channel_frozen, channel_deleted, user_deleted, moderation_blocked, hook_rejected, expired, internal_error, invalid_message, pending_not_supported
    - `id` string, required: Unique identifier of the scheduled message
    - `message` ScheduledMessageContentResponse, required: The message a scheduled message will send
      - `attachments` Attachment[]: Array of message attachments
        - `actions` Action[]
          - `name` string, required
          - `style` string
          - `text` string, required
          - `type` string, required
          - `value` string
        - `asset_url` string
        - `author_icon` string
        - `author_link` string
        - `author_name` string
        - `color` string
        - `custom` object, required
        - `fallback` string
        - `fields` Field[]
          - `short` boolean, required
          - `title` string, required
          - `value` string, required
        - `footer` string
        - `footer_icon` string
        - `giphy` Images
          - `fixed_height` ImageData, required
            - `frames` string, required
            - `height` string, required
            - `size` string, required
            - `url` string, required
            - `width` string, required
          - `fixed_height_downsampled` ImageData, required
            - `frames` string, required
            - `height` string, required
            - `size` string, required
            - `url` string, required
            - `width` string, required
          - `fixed_height_still` ImageData, required
            - `frames` string, required
            - `height` string, required
            - `size` string, required
            - `url` string, required
            - `width` string, required
          - `fixed_width` ImageData, required
            - `frames` string, required
            - `height` string, required
            - `size` string, required
            - `url` string, required
            - `width` string, required
          - `fixed_width_downsampled` ImageData, required
            - `frames` string, required
            - `height` string, required
            - `size` string, required
            - `url` string, required
            - `width` string, required
          - `fixed_width_still` ImageData, required
            - `frames` string, required
            - `height` string, required
            - `size` string, required
            - `url` string, required
            - `width` string, required
          - `original` ImageData, required
            - `frames` string, required
            - `height` string, required
            - `size` string, required
            - `url` string, required
            - `width` string, required
        - `image_url` string
        - `og_scrape_url` string
        - `original_height` integer
        - `original_width` integer
        - `pretext` string
        - `text` string
        - `thumb_url` string
        - `title` string
        - `title_link` string
        - `type` string: Attachment type (e.g. image, video, url)
      - `custom` object, required
      - `html` string: Contains HTML markup of the message
      - `mentioned_channel` boolean: Whether the message mentions the whole channel
      - `mentioned_group_ids` string[]: IDs of the user groups mentioned in the message
      - `mentioned_here` boolean: Whether the message mentions the online channel members
      - `mentioned_roles` string[]: Roles mentioned in the message
      - `mentioned_users` string[]: IDs of the users mentioned in the message
      - `mml` string: MML content of the message
      - `parent_id` string: ID of parent message (thread)
      - `pin_expires` string, date-time: Date/time the pin expires
      - `pinned` boolean: Whether the message will be pinned when sent
      - `poll_id` string: Identifier of the poll to include in the message
      - `quoted_message_id` string
      - `restricted_visibility` string[]: IDs of the users the message will be visible to
      - `shared_location` ScheduledMessageLocation: The location a scheduled message will share
        - `created_by_device_id` string, required: The ID of the device that created the location.
        - `end_at` string, date-time: The date when the location sharing ends. If it's empty, it means the location sharing is static instead of live.
        - `latitude` number, double: The latitude of the location.
        - `longitude` number, double: The longitude of the location.
      - `show_in_channel` boolean: Whether thread reply should be shown in the channel as well
      - `silent` boolean: Whether message is silent or not
      - `text` string, required: Text of the message
      - `type` string: Contains type of the message. One of: regular, system
    - `scheduled_at` string, date-time, required: Date/time the message is scheduled to be sent
    - `status` string, required: Status of the scheduled message. One of: scheduled, sending, failed, canceled, sent. A message is sending from its first send attempt until it is sent or fails, including while it waits to retry a failed attempt; it cannot be edited, canceled or sent now while sending
    - `updated_at` string, date-time, required: Date/time of the last update
    - `user` UserResponse, required: User response object
      - `avg_response_time` integer
      - `ban_expires` string, date-time: Date when ban expires
      - `banned` boolean, required: Whether a user is banned or not
      - `blocked_user_ids` string[], required
      - `bypass_moderation` boolean
      - `created_at` string, date-time, required: Date/time of creation
      - `custom` object, required: Custom data for this object
      - `deactivated_at` string, date-time: Date of deactivation
      - `deleted_at` string, date-time: Date/time of deletion
      - `devices` DeviceResponse[]: List of devices user is using
        - `created_at` string, date-time, required: The date when the device was created.
        - `disabled` boolean: Whether device is disabled or not
        - `disabled_reason` string: Reason explaining why device had been disabled
        - `hardware_id` string: Stable physical device identifier used to deduplicate pushes across push providers
        - `id` string, required: The device identifier.
        - `push_provider` string, required: Push provider
        - `push_provider_name` string: Push provider name
        - `user_id` string, required: User ID
        - `voip` boolean: When true the token is for Apple VoIP push notifications
      - `id` string, required: Unique user identifier
      - `image` string
      - `invisible` boolean, required
      - `language` string, required: Preferred language of a user
      - `last_active` string, date-time: Date of last activity
      - `name` string: Optional name of user
      - `online` boolean, required: Whether a user online or not
      - `privacy_settings` PrivacySettingsResponse: The privacy settings of the user.
        - `delivery_receipts` DeliveryReceiptsResponse: The settings for the delivery receipt events.
          - `enabled` boolean
        - `read_receipts` ReadReceiptsResponse: The settings for the read receipt events.
          - `enabled` boolean
        - `typing_indicators` TypingIndicatorsResponse: The settings for typing indicator events.
          - `enabled` boolean
      - `push_notifications` PushNotificationSettingsResponse
        - `disabled` boolean
        - `disabled_until` string, date-time
      - `revoke_tokens_issued_before` string, date-time: Revocation date for tokens
      - `role` string, required: Determines the set of user permissions
      - `shadow_banned` boolean, required: Whether a user is shadow banned
      - `teams` string[], required: List of teams user is a part of
      - `teams_role` object
      - `updated_at` string, date-time, required: Date/time of the last update

## Other responses

- `400`: Bad request
- `429`: Too many requests

## Changes

> 574 revisions in range; 3 not diffed.

- **2026-10-15** `ddeb57744df3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/getstream/apis/stream-api/changes/scheduled_messages/:id/delete.md)

---

[API](https://skmtc.dev/getstream/apis/stream-api.md) - [All operations](https://skmtc.dev/getstream/apis/stream-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getstream/apis/stream-api/revisions/1fda44d40b27?raw)