2020-10-26 21:08:22 +00:00
---
2021-04-23 15:09:37 +00:00
stage: Growth
group: Activation
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-10-26 21:08:22 +00:00
---
2021-06-11 09:09:58 +00:00
# Broadcast Messages API **(FREE SELF)**
2016-08-30 19:47:44 +00:00
2022-03-10 12:07:07 +00:00
> 'target_access_levels' [introduced](https://gitlab.com/gitlab-org/growth/team-tasks/-/issues/461) in GitLab 14.8 [with a flag](../administration/feature_flags.md) named `role_targeted_broadcast_messages`. Disabled by default.
2019-02-05 03:49:11 +00:00
Broadcast messages API operates on [broadcast messages ](../user/admin_area/broadcast_messages.md ).
2020-01-24 18:09:00 +00:00
As of GitLab 12.8, GET requests do not require authentication. All other broadcast message API endpoints are accessible only to administrators. Non-GET requests by:
2019-02-05 03:49:11 +00:00
2020-12-16 15:10:18 +00:00
- Guests result in `401 Unauthorized` .
- Regular users result in `403 Forbidden` .
2016-08-30 19:47:44 +00:00
2021-09-09 09:11:16 +00:00
## Get all broadcast messages **(FREE)**
2016-08-30 19:47:44 +00:00
2019-02-05 03:49:11 +00:00
List all broadcast messages.
2020-05-20 03:08:04 +00:00
```plaintext
2016-08-30 19:47:44 +00:00
GET /broadcast_messages
```
2019-02-05 03:49:11 +00:00
Example request:
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl "https://gitlab.example.com/api/v4/broadcast_messages"
2016-08-30 19:47:44 +00:00
```
Example response:
```json
[
{
"message":"Example broadcast message",
"starts_at":"2016-08-24T23:21:16.078Z",
"ends_at":"2016-08-26T23:21:16.080Z",
"color":"#E75E40",
"font":"#FFFFFF",
"id":1,
2019-12-12 03:07:34 +00:00
"active": false,
2022-03-10 12:07:07 +00:00
"target_access_levels": [10,30],
2020-01-30 21:08:47 +00:00
"target_path": "*/welcome",
2020-03-05 00:07:49 +00:00
"broadcast_type": "banner",
"dismissable": false
2016-08-30 19:47:44 +00:00
}
]
```
2021-09-09 09:11:16 +00:00
## Get a specific broadcast message **(FREE)**
2016-08-30 19:47:44 +00:00
2019-02-05 03:49:11 +00:00
Get a specific broadcast message.
2020-05-20 03:08:04 +00:00
```plaintext
2016-08-30 19:47:44 +00:00
GET /broadcast_messages/:id
```
2019-02-05 03:49:11 +00:00
Parameters:
| Attribute | Type | Required | Description |
|:----------|:--------|:---------|:-------------------------------------|
| `id` | integer | yes | ID of broadcast message to retrieve. |
Example request:
2016-08-30 19:47:44 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl "https://gitlab.example.com/api/v4/broadcast_messages/1"
2016-08-30 19:47:44 +00:00
```
Example response:
```json
{
"message":"Deploy in progress",
"starts_at":"2016-08-24T23:21:16.078Z",
"ends_at":"2016-08-26T23:21:16.080Z",
"color":"#cecece",
"font":"#FFFFFF",
"id":1,
2019-12-12 03:07:34 +00:00
"active":false,
2022-03-10 12:07:07 +00:00
"target_access_levels": [10,30],
2020-01-30 21:08:47 +00:00
"target_path": "*/welcome",
2020-03-05 00:07:49 +00:00
"broadcast_type": "banner",
"dismissable": false
2016-08-30 19:47:44 +00:00
}
```
## Create a broadcast message
2019-02-05 03:49:11 +00:00
Create a new broadcast message.
2020-05-20 03:08:04 +00:00
```plaintext
2016-08-30 19:47:44 +00:00
POST /broadcast_messages
```
2019-02-05 03:49:11 +00:00
Parameters:
2016-08-30 19:47:44 +00:00
2022-03-10 12:07:07 +00:00
| Attribute | Type | Required | Description |
|:-----------------------|:------------------|:---------|:------------------------------------------------------|
| `message` | string | yes | Message to display. |
2022-05-30 09:09:35 +00:00
| `starts_at` | datetime | no | Starting time (defaults to current time in UTC). Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `ends_at` | datetime | no | Ending time (defaults to one hour from current time in UTC). Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
2022-03-10 12:07:07 +00:00
| `color` | string | no | Background color hex code. |
| `font` | string | no | Foreground color hex code. |
| `target_access_levels` | array of integers | no | Target access levels (roles) of the broadcast message.|
| `target_path` | string | no | Target path of the broadcast message. |
| `broadcast_type` | string | no | Appearance type (defaults to banner) |
| `dismissable` | boolean | no | Can the user dismiss the message? |
The `target_access_levels` are defined in the `Gitlab::Access` module. The
following levels are valid:
- Guest (`10`)
- Reporter (`20`)
- Developer (`30`)
- Maintainer (`40`)
- Owner (`50`)
2019-02-05 03:49:11 +00:00
Example request:
2020-01-30 15:09:15 +00:00
```shell
2022-03-10 12:07:07 +00:00
curl --data "message=Deploy in progress& color=#cecece& target_access_levels[]=10& target_access_levels[]=30" \
2021-06-02 15:09:59 +00:00
--header "PRIVATE-TOKEN: < your_access_token > " \
"https://gitlab.example.com/api/v4/broadcast_messages"
2016-08-30 19:47:44 +00:00
```
Example response:
```json
{
"message":"Deploy in progress",
"starts_at":"2016-08-26T00:41:35.060Z",
"ends_at":"2016-08-26T01:41:35.060Z",
"color":"#cecece",
"font":"#FFFFFF",
"id":1,
2019-12-12 03:07:34 +00:00
"active": true,
2022-03-10 12:07:07 +00:00
"target_access_levels": [10,30],
2020-01-30 21:08:47 +00:00
"target_path": "*/welcome",
"broadcast_type": "notification",
2020-03-05 00:07:49 +00:00
"dismissable": false
2016-08-30 19:47:44 +00:00
}
```
## Update a broadcast message
2019-02-05 03:49:11 +00:00
Update an existing broadcast message.
2020-05-20 03:08:04 +00:00
```plaintext
2016-08-30 19:47:44 +00:00
PUT /broadcast_messages/:id
```
2019-02-05 03:49:11 +00:00
Parameters:
2022-03-10 12:07:07 +00:00
| Attribute | Type | Required | Description |
|:-----------------------|:------------------|:---------|:------------------------------------------------------|
| `id` | integer | yes | ID of broadcast message to update. |
| `message` | string | no | Message to display. |
2022-05-30 09:09:35 +00:00
| `starts_at` | datetime | no | Starting time (UTC). Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `ends_at` | datetime | no | Ending time (UTC). Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
2022-03-10 12:07:07 +00:00
| `color` | string | no | Background color hex code. |
| `font` | string | no | Foreground color hex code. |
| `target_access_levels` | array of integers | no | Target access levels (roles) of the broadcast message.|
| `target_path` | string | no | Target path of the broadcast message. |
| `broadcast_type` | string | no | Appearance type (defaults to banner) |
| `dismissable` | boolean | no | Can the user dismiss the message? |
The `target_access_levels` are defined in the `Gitlab::Access` module. The
following levels are valid:
- Guest (`10`)
- Reporter (`20`)
- Developer (`30`)
- Maintainer (`40`)
- Owner (`50`)
2016-08-30 19:47:44 +00:00
2019-02-05 03:49:11 +00:00
Example request:
2020-01-30 15:09:15 +00:00
```shell
2021-06-02 15:09:59 +00:00
curl --request PUT --data "message=Update message& color=#000" \
--header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/broadcast_messages/1"
2016-08-30 19:47:44 +00:00
```
Example response:
```json
{
"message":"Update message",
"starts_at":"2016-08-26T00:41:35.060Z",
"ends_at":"2016-08-26T01:41:35.060Z",
"color":"#000",
"font":"#FFFFFF",
"id":1,
2019-12-12 03:07:34 +00:00
"active": true,
2022-03-10 12:07:07 +00:00
"target_access_levels": [10,30],
2020-01-30 21:08:47 +00:00
"target_path": "*/welcome",
"broadcast_type": "notification",
2020-03-05 00:07:49 +00:00
"dismissable": false
2016-08-30 19:47:44 +00:00
}
```
## Delete a broadcast message
2019-02-05 03:49:11 +00:00
Delete a broadcast message.
2022-06-09 03:08:17 +00:00
```plaintext
2016-08-30 19:47:44 +00:00
DELETE /broadcast_messages/:id
```
2019-02-05 03:49:11 +00:00
Parameters:
| Attribute | Type | Required | Description |
|:----------|:--------|:---------|:-----------------------------------|
| `id` | integer | yes | ID of broadcast message to delete. |
Example request:
2016-08-30 19:47:44 +00:00
2020-01-30 15:09:15 +00:00
```shell
2020-05-28 00:08:37 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/broadcast_messages/1"
2016-08-30 19:47:44 +00:00
```