ceejay.messages

Post a message, embeds or both to a channel in your Discord server, as the CEEJAY bot.

The function takes the same last argument as every other, options: signal, timeoutMs and maxRetries, for that one call, and idempotencyKey, as every write does. It can also raise the errors any request can raise, such as a bad key or the rate limit. See Errors and retries.

To find the channel to post to, see ceejay.channels.list on Channels.

ceejay.messages.send

Posts to one channel. The channel must be in your server, and the bot needs View Channel and Send Messages in it, and Embed Links for embeds to show.

POST /v1/messages/send · requires messages:send · API reference: Send a message

Retried by the SDK: Only with idempotencyKey. Without one, a retried message would be posted twice

Parameters: one object, then options. Send content, embeds or both. TypeScript rejects an object with neither.

Prop

Type

Options

Prop

Type

An embed can hold title, description, url, timestamp, color, footer, image, thumbnail, author and fields. Embeds go to Discord unchanged, so Discord decides whether they are valid.

embeds must be a list. With content, a value that is not a list is left out and the text is posted. Without content, the request is rejected.

Mentions. A mention of a member notifies that member. A mention of a role notifies the role only when you list the role in allowedRoleIds. @everyone and @here never notify anyone through the API.

Returns Schemas['SendMessageResult'].

Prop

Type

Errors

Status	`code`	When
`400`	`bad_request`	A field is not valid, neither `content` nor `embeds` was sent, or `embeds` is not a list and there is no `content`
`403`	`bot_missing_permission`	The bot cannot send messages in this channel
`404`	`channel_not_found`	The channel does not exist, is in another server, or the bot cannot see it
`429`	`discord_rate_limited`	Discord is limiting the bot. `retryAfter` is the number of seconds Discord asked you to wait, if it provided one
`500`	`discord_not_configured`	Discord is not configured on this instance
`503`	`discord_unavailable`	Discord did not respond in time. If the channel check timed out, nothing was posted. If the post itself timed out, the message may or may not be in the channel, so check before you retry without a key

Any other status that Discord returns is passed on with the code discord_error. The message is then Discord API error: followed by that status, and error.body includes Discord's own response in details.

When the outcome is unknown. A posted message cannot be unsent through the API. With a key, CEEJAY does not post a second time when it cannot tell whether the first attempt was posted: the call fails with status 409 and the code idempotency_outcome_unknown. Check the channel, then send the message with a new key if it is not there. Idempotency errors are covered in Errors and retries.

Example

ceejay.messages.send

const message = await ceejay.messages.send(
  {
    channelId: '720000000000000001',
    content: 'The weekend cup is over. Well played, <@409876543210987654>!',
    embeds: [
      {
        title: 'Weekend cup',
        description: 'Final standings',
        color: 0xf94801,
        fields: [
          { name: 'First', value: 'nova', inline: true },
          { name: 'Second', value: 'ember', inline: true },
        ],
      },
    ],
  },
  { idempotencyKey: 'weekend-cup-41:results' },
)

console.log(message.messageId, message.duplicate)

To ping a role, name it in the text and list it:

ceejay.messages.send, ping a role

await ceejay.messages.send({
  channelId: '720000000000000001',
  content: 'Sign-ups are open, <@&718230049827100399>.',
  allowedRoleIds: ['718230049827100399'],
})

ceejay.messages.send

On this page