Messages

A bot sends, edits and deletes its own messages, reacts, pins, and, with Manage Messages, deletes other people's messages.

Send a message

POST /channels/{target}/messages
{
  "content": "Hello!",
  "embeds": [{ "title": "Rules", "description": "Be kind.", "colour": "#E0195F" }],
  "replies": [{ "id": "01J…", "mention": false }],
  "attachments": ["<file id from the file server>"]
}

Limits: GET / lists them for each server (by default 2000 characters, 5 attachments, 10 embeds, 5 replies, 20 different reactions per message).
Idempotency: send an Idempotency-Key header with a unique value. If the request is retried with the same key, the message is not sent twice.
Silent messages: flags: 1 sends without push or desktop notifications.
Masquerade: masquerade: { name, avatar } shows another name and avatar on the message (needs Masquerade; a colour also needs Manage Roles).
Components: buttons, selects and layout blocks; only bots can send them. See Commands and interactions.
Mentions: <@user id> pings a user, <%role id> a role (needs Mention Roles), @everyone and @online need Mention Everyone. Without the permission the whole message is refused with MissingPermission, it is not sent without the ping. On a self-hosted server with mass_mentions_enabled = false, role, @everyone and @online mentions are sent without notifying anyone instead.
Channel links: <#channel id> shows a link to a channel or thread. It notifies nobody.

Reply

replies answers earlier messages, up to 5. id is the message, mention says whether its author gets a ping, and fail_if_not_exists: false still sends if that message is gone.

curl -X POST "https://api.zrzur.com/channels/CHANNEL_ID/messages" \
  -H "x-bot-token: YOUR_BOT_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "content": "Thanks!", "replies": [{ "id": "MESSAGE_ID", "mention": false }] }'

Edit and delete

PATCH /channels/{target}/messages/{msg} takes content, embeds and components. A bot edits only its own messages. DELETE /channels/{target}/messages/{msg} deletes the bot's own, or any message with Manage Messages. An edit never pings anyone again.

Embeds

An embed is a card under the message. Sending one needs Send Embeds.

Field	Meaning
`title`	Title
`description`	Text, with Markdown
`url`	Address the title links to
`colour`	A CSS colour, such as `#E0195F`
`icon_url`	Small image next to the title
`media`	Id of a file you uploaded, shown as an image
`image_url`	Address of a large image
`thumbnail_url`	Address of a small image at the side
`author`	`name`, `url`, `icon_url`
`fields`	Up to 25, each with `name`, `value`, `inline`
`footer`	`text`, `icon_url`
`timestamp`	A date, shown at the bottom

The exact fields and limits are in the reference below.

Attachments

A message refers to files by id. Upload first, then send. Each id can be used once: a second use answers 404 NotFound. Sending needs Upload Files. A file a person gave your bot through a command's Attachment option is already used by that command; see Slash commands.

curl -X POST "https://cdn.zrzur.com/attachments" \
  -H "x-bot-token: YOUR_BOT_TOKEN" \
  -F "[email protected];type=text/csv"
# answer: { "id": "FILE_ID" }

curl -X POST "https://api.zrzur.com/channels/CHANNEL_ID/messages" \
  -H "x-bot-token: YOUR_BOT_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "content": "Here it is", "attachments": ["FILE_ID"] }'

See Files for sizes and types.

Read messages

GET /channels/{target}/messages returns 50 messages, or up to 100 with limit. Reading needs View Channel and Read Message History.

Query	Meaning
`limit`	1 to 100. Default 50
`before`	A message id: only older messages
`after`	A message id: only newer messages
`sort`	`Latest` (the default, newest first) or `Oldest` (oldest first). `Relevance` answers `InvalidOperation`
`nearby`	A message id: messages around it, that message included. `before`, `after` and `sort` are ignored
`include_users`	`true` adds the authors

The answer is a list of messages. With include_users=true it is an object instead: { "messages": [...], "users": [...], "members": [...] }. members is there in server channels only.

To catch up after a reconnect, ask for after your last message with sort=Oldest: you get the next messages in order. With the default order you would get the newest ones, and a gap would stay in the middle. Repeat with the id of the last message you got until fewer than limit come back.

curl "https://api.zrzur.com/channels/CHANNEL_ID/messages?after=LAST_SEEN_ID&sort=Oldest&limit=100" \
  -H "x-bot-token: YOUR_BOT_TOKEN"

Text search is for people only; bots get IsBot, because it would let them read what their intents hide. Bots can list pinned messages (see Pins and reactions). The mentions inbox is for people only too.

Bulk delete

DELETE /channels/{target}/messages/bulk deletes up to 100 messages at once. Messages older than a week cannot be bulk deleted; delete them one by one.

Direct messages

GET /users/{target}/dm opens (or returns) the DM channel with a user. Whether the bot may write there depends on that person's privacy settings and blocks, see Users and members.

Reference

`PUT /channels/{target}/ack/{message}`

Acknowledge Message. Lets the server and all other clients know that we've seen this message id in this channel.

Not available to bots.

Permissions: Channel:ViewChannel · Rate limit: channels, 15 / 10 s

`GET /channels/{target}/messages`

Fetch Messages. Fetch multiple messages.

Permissions: Channel:ReadMessageHistory · Rate limit: channels, 15 / 10 s

`POST /channels/{target}/messages`

Send Message. Sends a message to the given channel.

Rate limit: messaging, 10 / 10 s

`DELETE /channels/{target}/messages/{msg}`

Delete Message. Delete a message you've sent or one you have permission to delete.

Permissions: Channel:ManageMessages · Rate limit: channels, 15 / 10 s

`GET /channels/{target}/messages/{msg}`

Fetch Message. Retrieves a message by its id.

Permissions: Channel:ViewChannel, Channel:ReadMessageHistory · Rate limit: channels, 15 / 10 s

`PATCH /channels/{target}/messages/{msg}`

Edit Message. Edits a message that you've previously sent.

Permissions: Channel:SendMessage, Channel:SendEmbeds · Rate limit: channels, 15 / 10 s

`DELETE /channels/{target}/messages/{msg}/pin`

Unpins a message. Unpins a message by its id.

Permissions: Channel:ViewChannel, Channel:ManageMessages · Rate limit: channels, 15 / 10 s

`POST /channels/{target}/messages/{msg}/pin`

Pins a message. Pins a message by its id.

Permissions: Channel:ViewChannel, Channel:ManageMessages · Rate limit: messaging, 10 / 10 s

`GET /channels/{target}/messages/{msg}/polls/answers/{answer}/voters`

Fetch Poll Voters. People who chose an answer, oldest vote first, a page at a time (up to 100, default 50; pass the last id as after for the next page). Anyone who can read the message can see them.

Rate limit: channels, 15 / 10 s

`DELETE /channels/{target}/messages/{msg}/polls/answers/{answer}/votes/@me`

Remove a Poll Vote. Take back your choice of an answer of the poll in this message. Returns the poll with the new counts and your choice.

Not available to bots.

Rate limit: channels, 15 / 10 s

`PUT /channels/{target}/messages/{msg}/polls/answers/{answer}/votes/@me`

Vote on a Poll. Choose an answer of the poll in this message. On a single-choice poll it replaces your earlier choice; on a multiple-choice poll it is added to it. Needs React. Returns the poll with the new counts and your choice.

Not available to bots.

Rate limit: channels, 15 / 10 s

`POST /channels/{target}/messages/{msg}/polls/end`

End a Poll. Close the poll in this message now: votes stop, the results are final and a "poll ended" reply is posted. The author can end their own poll; anyone else needs Manage Messages.

Permissions: Channel:ManageMessages · Rate limit: messaging, 10 / 10 s

`POST /channels/{target}/messages/forward`

Forward Message. Sends a copy of a message from another channel into this one, with its text, files and rich embeds, and a note of where it came from. You need to be able to read the original (view the channel and read its history) and to send here, with the same rules as any message you send (files need Upload Files, rich embeds need Send Embeds). A message from a mature channel goes only into another mature channel. A forwarded copy notifies nobody it mentions. A poll is forwarded as text: its question and answers, without votes.

Not available to bots.

Permissions: Channel:ViewChannel, Channel:ReadMessageHistory, Channel:SendMessage, Channel:UploadFiles, Channel:SendEmbeds · Rate limit: messaging, 10 / 10 s

`POST /channels/{target}/search`

Search for Messages. This route searches for messages within the given parameters: words, authors, a mentioned user, what a message has (link, file, image, video, embed, sound), a time window by id or date, and pinned. Every filter given must match. Bots may only list pinned messages (pinned: true): searching text would let a bot read messages its intents hide.

Permissions: Channel:ReadMessageHistory · Rate limit: channels, 15 / 10 s

`POST /channels/{target}/typing`

Start Typing. Show that you are typing in a channel. Clients hide it again after a few seconds or when your message arrives. For bots without a gateway connection; connected clients send BeginTyping instead.

Rate limit: channels, 15 / 10 s

`POST /servers/{target}/messages/search`

Search for Messages in a Server. Searches the server's channels that you may read: you need to view the channel and read its history, and mature channels are for declared adults only. Other channels are left out silently, never reported. Takes the same filters as a channel search, plus channels to search only some of them. Bots may only list pinned messages (pinned: true).

Permissions: Channel:ViewChannel, Channel:ReadMessageHistory · Rate limit: servers, 5 / 10 s

Pins and reactions

PUT /channels/{target}/messages/{msg}/reactions/{emoji} adds the bot's reaction, and DELETE on the same path removes it. The emoji is written in the path, URL-encoded (%F0%9F%91%8D for a thumbs up), or as the id of a custom emoji. POST /channels/{target}/messages/{msg}/pin pins a message. POST /channels/{target}/search with pinned: true lists pinned messages. Other search is for people only: bots get IsBot, because it would let them read what their intents hide.

Polls

A message can carry a poll (poll in the message you send: a question, 2 to 10 answers, a duration of 1, 4, 8, 24, 72, 168 or 336 hours, single or multiple choice). Posting one needs Send Messages and Send Embeds. Polls are switched on per server installation (features.polls in GET /); where they are off, sending one answers FeatureDisabled. A message's poll shows how many chose each answer; poll.me lists the answers the reader chose.

Who voted is never sent to everyone: poll events (MessagePollVoteAdd, MessagePollVoteRemove, MessagePollEnd) carry counts only. /channels/{target}/messages/{msg}/polls/answers/{answer}/voters (GET) lists the people who chose an answer, a page at a time, to anyone who can read the message (View Channel and Read Message History), so a voter is visible to everyone in the channel who asks. Bots cannot vote (IsBot); they can read voters and end their own polls (/channels/{target}/messages/{msg}/polls/end, POST). A vote on a poll that has ended answers PollEnded.