Organization API: Organizations & Members: Announcements

Part of Organizations & Members.

GET /api/v1/orgs/{org_slug}/announcements

Whether a Discord webhook is saved for announcements, and its channel label.

Needs the Admin or Owner role. configured says whether a webhook address is saved, channel_label is the name your team gave the channel (null for none) and webhook_hint is the last four characters of the webhook's ID, so you can tell which webhook is saved. The address is a secret and is never answered.

PUT /api/v1/orgs/{org_slug}/announcements

Save the Discord webhook address and the channel label. Send only what changes.

Needs the Admin or Owner role. webhook_url must be an https address on Discord's own hosts that starts with https://discord.com/api/webhooks/, or 422 answers with detail and field. It is sealed and never shown again, and null or an empty string removes it. channel_label is at most 80 characters. The answer is the one GET gives. Saving what is already saved changes nothing and writes no audit entry. A change is recorded as announcements.updated with the settings that changed and never the address.

application/json (required)

GET /api/v1/orgs/{org_slug}/announcements/history

The announcements posted or refused, newest first.

Needs the Admin or Owner role. Each entry has status (posted or failed), the title, content and link that were sent, the channel_label then saved, error (why a failed post failed, never what Discord said), actor_type (staff, user or admin for platform staff), actor ({id, name}, null when it is unknown) and created_at. The webhook address is never in an entry.

POST /api/v1/orgs/{org_slug}/announcements/post

Post one message to the saved Discord webhook.

Needs the Admin or Owner role. content is the message, 1 to 1,800 characters. title (at most 120 characters) becomes a bold first line, and link (an https address) goes after the message. The title, text and link together fit Discord's 2,000 characters, or 422 answers. Nothing in the message can mention a role or a person. The answer is {posted: true}. 409 means no webhook is saved. 502 means Discord did not take the message, with detail saying so in a sentence, and nothing was posted. At most 10 messages an hour for the organization, and the 11th answers 429. Every attempt is recorded in the audit log as announcement.posted or announcement.failed with the words and the channel label, never the address.

application/json (required)