Send a message

POST /v1/messages/send · requires messages:send

Body parameters

At least one of content or embeds must be present. List channels gives you each channel's channelId.

Returns

Example

curl -X POST https://ceejay.communitystudios.xyz/api/v1/messages/send \
  -H "Authorization: Bearer $CEEJAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "718230049827100384",
    "content": "Tournament results are in. Congratulations to everyone who played."
  }'

The TypeScript example uses ceejay.messages.send from the TypeScript SDK. It returns the data of the response below.

{
  "success": true,
  "data": {
    "messageId": "1178230049827100384",
    "channelId": "718230049827100384",
    "duplicate": false
  }
}

How it works

CEEJAY first checks that the channel belongs to your server, then posts the message as the bot. A channel in another server, a channel that does not exist and a channel the bot cannot see all return the same 404.

The text of a message is not filtered or changed, so read the next section before you pass on text written by players. CEEJAY does not store a copy of the message.

Embeds

embeds must be a list of Discord embed objects, and only the first 10 are sent.

• With no content, the embeds are the whole message: a value that is not a list returns 400 with the message embeds must be a list.
• With content, a value that is not a list is left out and the text is posted.

Embeds go to Discord unchanged, so Discord decides whether they are valid. An embed Discord does not accept is returned with Discord's own status and the code discord_error.

Mentions

Every message is sent so that only mentions of members notify anyone.

To ping a role, name it in allowedRoleIds and mention it in content:

{
  "channelId": "718230049827100384",
  "content": "Sign-ups are open, <@&718230049827100399>.",
  "allowedRoleIds": ["718230049827100399"]
}

A role in allowedRoleIds that content does not mention pings nobody. Discord's own rules still apply: the bot can only ping a role that is set to be mentionable, unless the bot has the Mention @everyone, @here, and All Roles permission.

Your server's own ID is also the ID of its @everyone role, so allowedRoleIds cannot contain it. A list that does is rejected with 400.

Retrying safely

Send an idempotencyKey with every call you might need to retry, such as after a timeout. It is a string of 1 to 128 characters that you choose, sent in the JSON body: an Idempotency-Key header is not read.

• Retrying with the same key returns the original response. When the same request is sent again with its key, CEEJAY returns the original response, with duplicate: true and the header Idempotent-Replayed: true.
• Each key is tied to one request payload. The same request means the same channel, text, embeds and allowedRoleIds, as they would be posted. Two requests for one event need two keys, for example match-9:coins and match-9:xp. A key that was used for a different request, here or on any other request of the API, returns 409 with the code idempotency_key_reused, and nothing is changed.
• A rejected request does not use up the key. A call that was rejected can be retried with the same key once the cause is fixed.
• A key belongs to the API key that sent it. Another API key of your community can send the same text, and it is a different key.
• Keys are retained for 30 days. Use a value you can regenerate after a crash, such as an order ID or a match ID.
• On an instance that does not support idempotency keys yet, a call that sends one returns 503 with the code idempotency_unavailable, and nothing is changed. Community details reports whether keys are supported, under features.retryKeys. idempotency_key is not accepted on this endpoint; use idempotencyKey.
• Without a key, a retried call is a new call.

CEEJAY cannot undo a posted message, so it never posts twice with one key:

• A rejection from Discord (any 4xx, its rate limit included) does not use up the key. The same key can be reused.
• After a timeout, a dropped connection or a 5xx from Discord, the message may or may not have been posted. The same key then returns 409 with the code idempotency_in_progress for a minute, and idempotency_outcome_unknown after that. Check the channel, then use a new key if the message has to be sent again.
• With a key, embeds nested more than 32 levels deep are rejected with 400.

Without a key, sending the same request twice posts the message twice.

Errors

Discord's own rate limit returns 429 with the code discord_rate_limited. A limit Discord sets for one channel stops calls for that channel only, and the response does not mean your key's own limit is used up: X-RateLimit-Remaining still shows what the key has left.

Every error body also includes requestId, and a 400 with the code bad_request identifies the invalid field in field. Match on code; message text can change.

The errors every request shares (401, 403, 405, 429, 500) are on the Errors page.