Nachrichten

Ein Bot sendet, bearbeitet und löscht eigene Nachrichten, reagiert, heftet an und löscht mit Nachrichten verwalten auch die anderer.

Eine Nachricht senden

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 / listet sie für jeden Server (standardmäßig 2000 Zeichen, 5 Anhänge, 10 Embeds, 5 Antworten, 20 verschiedene Reaktionen pro Nachricht).
Idempotenz: Sende einen Header Idempotency-Key mit eindeutigem Wert. Wird die Anfrage mit demselben Schlüssel wiederholt, geht die Nachricht nicht zweimal hinaus.
Stille Nachrichten: flags: 1 sendet ohne Benachrichtigungen.
Maskerade: masquerade: { name, avatar } zeigt einen anderen Namen und Avatar auf der Nachricht (braucht Masquerade; colour braucht auch „Rollen verwalten“).
Komponenten: Schaltflächen, Menüs und Layoutblöcke; nur Bots können sie senden. Siehe Schaltflächen, Menüs und Formulare.
Erwähnungen: <@user id> erwähnt einen Benutzer, <%role id> eine Rolle (braucht Mention Roles), @everyone und @online brauchen Mention Everyone. Ohne die Berechtigung wird die ganze Nachricht mit MissingPermission abgelehnt; sie geht nicht ohne die Erwähnung raus. Auf einem selbst gehosteten Server mit mass_mentions_enabled = false gehen Rollen-, @everyone- und @online-Erwähnungen stattdessen ohne Benachrichtigung raus.
Kanal-Links: <#channel id> zeigt einen Link auf einen Kanal oder Thread. Er benachrichtigt niemanden.

Antworten

replies antwortet auf frühere Nachrichten, bis zu 5. id ist die Nachricht, mention sagt, ob ihr Autor erwähnt wird, und fail_if_not_exists: false sendet auch dann, wenn die Nachricht weg ist.

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 }] }'

Bearbeiten und löschen

PATCH /channels/{target}/messages/{msg} nimmt content, embeds und components. Ein Bot bearbeitet nur eigene Nachrichten. DELETE /channels/{target}/messages/{msg} löscht eigene, oder jede mit „Nachrichten verwalten“. Eine Bearbeitung benachrichtigt nie erneut.

Embeds

Ein Embed ist eine Karte unter der Nachricht. Senden braucht Send Embeds.

Feld	Bedeutung
`title`	Titel
`description`	Text, mit Markdown
`url`	Adresse, auf die der Titel zeigt
`colour`	Eine CSS-Farbe, etwa `#E0195F`
`icon_url`	Kleines Bild neben dem Titel
`media`	ID einer hochgeladenen Datei, als Bild gezeigt
`image_url`	Adresse eines großen Bildes
`thumbnail_url`	Adresse eines kleinen Bildes an der Seite
`author`	`name`, `url`, `icon_url`
`fields`	Bis zu 25, je mit `name`, `value`, `inline`
`footer`	`text`, `icon_url`
`timestamp`	Ein Datum, unten gezeigt

Die genauen Felder und Limits stehen in der Referenz unten.

Anhänge

Eine Nachricht verweist per ID auf Dateien. Erst hochladen, dann senden. Jede ID geht einmal: Eine zweite Nutzung antwortet 404 NotFound. Senden braucht Upload Files. Eine Datei, die eine Person deinem Bot über die Option Attachment eines Befehls gegeben hat, ist von diesem Befehl schon verwendet; siehe Slash-Befehle.

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"] }'

Größen und Typen stehen unter Dateien.

Nachrichten lesen

GET /channels/{target}/messages liefert 50 Nachrichten, mit limit bis zu 100. Lesen braucht „Kanal sehen“ und „Ältere Nachrichten lesen“.

Query-Parameter	Bedeutung
`limit`	1 bis 100. Standard 50
`before`	Eine Nachrichten-ID: nur ältere Nachrichten
`after`	Eine Nachrichten-ID: nur neuere Nachrichten
`sort`	`Latest` (Standard, neueste zuerst) oder `Oldest` (älteste zuerst). `Relevance` antwortet `InvalidOperation`
`nearby`	Eine Nachrichten-ID: Nachrichten um sie herum, sie selbst eingeschlossen. `before`, `after` und `sort` werden ignoriert
`include_users`	`true` fügt die Autoren hinzu

Die Antwort ist eine Liste von Nachrichten. Mit include_users=true ist sie stattdessen ein Objekt: { "messages": [...], "users": [...], "members": [...] }. members gibt es nur in Serverkanälen.

Um nach einem Neuverbinden aufzuholen, frage nach after deiner letzten Nachricht mit sort=Oldest: Du bekommst die nächsten Nachrichten der Reihe nach. Mit der Standardreihenfolge kämen die neuesten, und in der Mitte bliebe eine Lücke. Wiederhole mit der ID der letzten erhaltenen Nachricht, bis weniger als limit zurückkommen.

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

Textsuche ist nur für Menschen; Bots bekommen IsBot, denn sonst könnten sie lesen, was ihre Intents verbergen. Bots können angeheftete Nachrichten listen (siehe Anheften und Reaktionen). Auch der Erwähnungseingang ist nur für Menschen.

Massenlöschung

DELETE /channels/{target}/messages/bulk löscht bis zu 100 Nachrichten auf einmal. Nachrichten, die älter als eine Woche sind, gehen nicht in Masse; lösche sie einzeln.

Direktnachrichten

GET /users/{target}/dm öffnet den DM-Kanal mit einem Benutzer oder liefert ihn. Ob der Bot dort schreiben darf, hängt von Privatsphäre-Einstellungen und Blockierungen ab, siehe Benutzer und Mitglieder.

Referenz

`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.

Für Bots nicht verfügbar.

Berechtigungen: Channel:ViewChannel · Ratenlimit: channels, 15 / 10 s

`GET /channels/{target}/messages`

Fetch Messages. Fetch multiple messages.

Berechtigungen: Channel:ReadMessageHistory · Ratenlimit: channels, 15 / 10 s

`POST /channels/{target}/messages`

Send Message. Sends a message to the given channel.

Ratenlimit: messaging, 10 / 10 s

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

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

Berechtigungen: Channel:ManageMessages · Ratenlimit: channels, 15 / 10 s

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

Fetch Message. Retrieves a message by its id.

Berechtigungen: Channel:ViewChannel, Channel:ReadMessageHistory · Ratenlimit: channels, 15 / 10 s

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

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

Berechtigungen: Channel:SendMessage, Channel:SendEmbeds · Ratenlimit: channels, 15 / 10 s

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

Unpins a message. Unpins a message by its id.

Berechtigungen: Channel:ViewChannel, Channel:ManageMessages · Ratenlimit: channels, 15 / 10 s

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

Pins a message. Pins a message by its id.

Berechtigungen: Channel:ViewChannel, Channel:ManageMessages · Ratenlimit: 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.

Ratenlimit: 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.

Für Bots nicht verfügbar.

Ratenlimit: 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.

Für Bots nicht verfügbar.

Ratenlimit: 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.

Berechtigungen: Channel:ManageMessages · Ratenlimit: 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.

Für Bots nicht verfügbar.

Berechtigungen: Channel:ViewChannel, Channel:ReadMessageHistory, Channel:SendMessage, Channel:UploadFiles, Channel:SendEmbeds · Ratenlimit: 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.

Berechtigungen: Channel:ReadMessageHistory · Ratenlimit: 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.

Ratenlimit: 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).

Berechtigungen: Channel:ViewChannel, Channel:ReadMessageHistory · Ratenlimit: servers, 5 / 10 s

Anheften und Reaktionen

PUT /channels/{target}/messages/{msg}/reactions/{emoji} fügt die Reaktion des Bots hinzu, DELETE auf demselben Pfad entfernt sie. Das Emoji steht URL-kodiert im Pfad (%F0%9F%91%8D für Daumen hoch) oder als ID eines eigenen Emojis. POST /channels/{target}/messages/{msg}/pin heftet an. POST /channels/{target}/search mit pinned: true listet angeheftete Nachrichten. Andere Suche ist nur für Menschen: Bots bekommen IsBot, denn sonst könnten sie lesen, was ihre Intents verbergen.

Umfragen

Eine Nachricht kann eine Umfrage tragen (poll in der gesendeten Nachricht: eine Frage, 2 bis 10 Antworten, eine Dauer von 1, 4, 8, 24, 72, 168 oder 336 Stunden, eine oder mehrere Antworten wählbar). Zum Posten braucht es Nachrichten senden und Embeds senden. Umfragen werden pro Server-Installation eingeschaltet (features.polls in GET /); wo sie aus sind, antwortet das Senden einer Umfrage mit FeatureDisabled. poll einer Nachricht zeigt, wie viele jede Antwort gewählt haben; poll.me nennt die Antworten der lesenden Person.

Wer abgestimmt hat, geht nie an alle: Umfrage-Events (MessagePollVoteAdd, MessagePollVoteRemove, MessagePollEnd) tragen nur Zahlen. /channels/{target}/messages/{msg}/polls/answers/{answer}/voters (GET) listet seitenweise, wer eine Antwort gewählt hat, für alle, die die Nachricht lesen können (Kanal ansehen und Nachrichtenverlauf lesen); eine Stimme ist also für alle im Kanal sichtbar, die nachsehen. Bots können nicht abstimmen (IsBot); sie können Abstimmende lesen und eigene Umfragen beenden (/channels/{target}/messages/{msg}/polls/end, POST). Eine Stimme in einer beendeten Umfrage ergibt PollEnded.