post
/channels/{channel_id}/messages/scheduleSchedule a message to send later
Schedules a message to be sent at a specified time. Only available for regular user accounts. Requires permission to send messages in the target channel. Message is sent automatically at the scheduled time. Returns the scheduled message object with delivery time.
schedule_message
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| channel_id* | path | SnowflakeType | The ID of the channel |
Request body
application/json
json
{
"type": "object",
"properties": {
"content": {
"anyOf": [
{
"$ref": "#/components/schemas/MessageContentRequest"
},
{
"type": "null"
}
]
},
"embeds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RichEmbedRequest"
},
"description": "Array of embed objects to include in the message"
},
"attachments": {
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/ClientUploadedAttachmentRequest"
},
{
"$ref": "#/components/schemas/ClientAttachmentRequest"
}
]
},
"description": "Array of attachment objects"
},
"message_reference": {
"anyOf": [
{
"$ref": "#/components/schemas/MessageReferenceRequest"
},
{
"type": "null"
}
],
"description": "Reference to another message (for replies or forwards)"
},
"allowed_mentions": {
"anyOf": [
{
"$ref": "#/components/schemas/AllowedMentionsRequest"
},
{
"type": "null"
}
],
"description": "Controls which mentions trigger notifications"
},
"flags": {
"$ref": "#/components/schemas/MessageFlags"
},
"nonce": {
"$ref": "#/components/schemas/MessageNonceRequest"
},
"favorite_meme_id": {
"anyOf": [
{
"$ref": "#/components/schemas/SnowflakeType"
},
{
"type": "null"
}
],
"description": "ID of a favorite meme to attach"
},
"sticker_ids": {
"anyOf": [
{
"type": "array",
"items": {
"$ref": "#/components/schemas/SnowflakeType"
},
"maxItems": 3
},
{
"type": "null"
}
],
"description": "Array of sticker IDs to include (max 3)"
},
"tts": {
"type": "boolean",
"description": "Whether this is a text-to-speech message"
},
"scheduled_local_at": {
"type": "string",
"description": "ISO 8601 timestamp expressed in the user local timezone for when the message should be delivered"
},
"timezone": {
"type": "string",
"description": "IANA timezone identifier the schedule_local_at value is anchored to"
}
},
"required": [
"scheduled_local_at",
"timezone"
]
}Responses
201
Success
json
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$",
"description": "The unique identifier for this scheduled message"
},
"channel_id": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$",
"description": "The ID of the channel this message will be sent to"
},
"scheduled_at": {
"type": "string",
"description": "The ISO 8601 UTC timestamp when the message is scheduled to be sent"
},
"scheduled_local_at": {
"type": "string",
"description": "The ISO 8601 timestamp in the user local timezone"
},
"timezone": {
"type": "string",
"description": "The IANA timezone identifier used for scheduling"
},
"status": {
"type": "string",
"enum": [
"pending",
"invalid",
"scheduled",
"sent",
"failed",
"cancelled"
],
"description": "The current status of the scheduled message"
},
"status_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "A human-readable reason for the current status, if applicable"
},
"payload": {
"type": "object",
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The text content of the scheduled message"
},
"tts": {
"type": "boolean",
"description": "Whether this is a text-to-speech message"
},
"embeds": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MessageEmbedResponse"
},
"description": "Array of embed objects attached to the message"
},
"attachments": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MessageAttachmentResponse"
},
"description": "Array of attachment objects for the message"
},
"stickers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/MessageStickerResponse"
},
"description": "Array of sticker objects attached to the message"
},
"sticker_ids": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SnowflakeType"
},
"description": "Array of sticker IDs to include in the message"
},
"allowed_mentions": {
"type": "object",
"properties": {
"parse": {
"type": "array",
"items": {
"type": "string",
"enum": [
"users",
"roles",
"everyone"
],
"x-enumNames": [
"USERS",
"ROLES",
"EVERYONE"
],
"x-enumDescriptions": [
"Parse user mentions from the message content",
"Parse role mentions from the message content",
"Parse @everyone and @here mentions from the message content"
],
"description": "Types of mentions to parse from content"
},
"description": "Types of mentions to parse from content"
},
"users": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SnowflakeType"
},
"description": "Array of user IDs to mention"
},
"roles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SnowflakeType"
},
"description": "Array of role IDs to mention"
},
"replied_user": {
"type": "boolean",
"description": "Whether to mention the author of the replied message"
}
},
"description": "Controls which mentions trigger notifications"
},
"message_reference": {
"type": "object",
"properties": {
"message_id": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$",
"description": "ID of the message being referenced"
},
"channel_id": {
"$ref": "#/components/schemas/SnowflakeType"
},
"guild_id": {
"$ref": "#/components/schemas/SnowflakeType"
},
"type": {
"$ref": "#/components/schemas/MessageReferenceType",
"description": "The type of message reference"
}
},
"required": [
"message_id"
],
"description": "Reference to another message (for replies or forwards)"
},
"flags": {
"$ref": "#/components/schemas/MessageFlags"
},
"nonce": {
"$ref": "#/components/schemas/MessageNonceRequest"
},
"favorite_meme_id": {
"$ref": "#/components/schemas/SnowflakeType"
}
},
"description": "The message content and metadata to be sent"
},
"created_at": {
"type": "string",
"description": "The ISO 8601 timestamp when this scheduled message was created"
},
"invalidated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The ISO 8601 timestamp when the message was marked invalid"
}
},
"required": [
"id",
"channel_id",
"scheduled_at",
"scheduled_local_at",
"timezone",
"status",
"status_reason",
"payload",
"created_at",
"invalidated_at"
]
}400
Bad Request - The request was malformed or contained invalid data
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}401
Unauthorized - Authentication is required or the token is invalid
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}403
Forbidden - You do not have permission to perform this action
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}429
Too Many Requests - You are being rate limited
json
{
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"RATE_LIMITED"
]
},
"message": {
"type": "string"
},
"retry_after": {
"type": "number",
"description": "Seconds to wait before retrying"
},
"global": {
"type": "boolean",
"description": "Whether this is a global rate limit"
}
},
"required": [
"code",
"message",
"retry_after"
]
}500
Internal Server Error - An unexpected error occurred
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}