# Organization API: Organizations & Members: Announcements

> The 4 Organization API operations for announcements.

Source: https://www.coritan.com/docs/api/reference/organizations/organizations-members/announcements/

Part of [Organizations & Members](/docs/api/reference/organizations/organizations-members/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/announcements`](#op-get-api-v1-orgs-org-slug-announcements) | Read the Discord webhook settings for announcements |
| PUT | [`/api/v1/orgs/{org_slug}/announcements`](#op-put-api-v1-orgs-org-slug-announcements) | Save or remove the Discord webhook for announcements |
| GET | [`/api/v1/orgs/{org_slug}/announcements/history`](#op-get-api-v1-orgs-org-slug-announcements-history) | Read the announcements that were posted |
| POST | [`/api/v1/orgs/{org_slug}/announcements/post`](#op-post-api-v1-orgs-org-slug-announcements-post) | Post an announcement to Discord |

### Read the Discord webhook settings for announcements {#op-get-api-v1-orgs-org-slug-announcements}

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Save or remove the Discord webhook for announcements {#op-put-api-v1-orgs-org-slug-announcements}

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `webhook_url` | string or null | no | The Discord webhook address, which starts with `https://discord.com/api/webhooks/`. It is sealed and never shown again. Null or empty removes the saved one. Left out, the saved one stays. |
| `channel_label` | string or null | no | A name for the channel, such as `#announcements`, shown to your team. At most 80 characters. Null or empty removes it. Left out, the saved one stays. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Read the announcements that were posted {#op-get-api-v1-orgs-org-slug-announcements-history}

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

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_slug` | path | string | yes |  |
| `limit` | query | integer | no | Announcements to return, newest first, 1 to 100. Left out, 20. Default: `20`. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Post an announcement to Discord {#op-post-api-v1-orgs-org-slug-announcements-post}

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

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content` | string or null | no | The message, 1 to 1,800 characters. Discord's own formatting works in it. Nothing in it can mention a role or a person. |
| `title` | string or null | no | A bold first line, at most 120 characters. |
| `link` | string or null | no | A link added after the message. It starts with `https://`, at most 500 characters. |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |