ContextQMD
Back to Gitlabhq

Broadcast Messages API

doc/api/broadcast_messages.md

18.11.28.2 KB
Original Source

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

{{< history >}}

  • target_access_levels introduced in GitLab 14.8 with a flag named role_targeted_broadcast_messages. Disabled by default.
  • color parameter removed in GitLab 15.6.
  • theme introduced in GitLab 17.6.

{{< /history >}}

Use this API to interact with banners and notifications displayed in the UI. For more information, see broadcast messages.

GET requests do not require authentication. All other broadcast message API endpoints are accessible only to administrators. Non-GET requests by:

  • Guests result in 401 Unauthorized.
  • Regular users result in 403 Forbidden.

List all broadcast messages

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Lists all broadcast messages.

plaintext
GET /broadcast_messages

Example request:

shell
curl "https://gitlab.example.com/api/v4/broadcast_messages"

Example response:

json
[
    {
        "message":"Example broadcast message",
        "starts_at":"2016-08-24T23:21:16.078Z",
        "ends_at":"2016-08-26T23:21:16.080Z",
        "font":"#FFFFFF",
        "id":1,
        "active": false,
        "target_access_levels": [10,30],
        "target_path": "*/welcome",
        "broadcast_type": "banner",
        "dismissable": false,
        "theme": "indigo"
    }
]

Retrieve a broadcast message

{{< details >}}

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Retrieves a specified broadcast message.

plaintext
GET /broadcast_messages/:id

Parameters:

AttributeTypeRequiredDescription
idintegeryesID of broadcast message to retrieve.

Example request:

shell
curl "https://gitlab.example.com/api/v4/broadcast_messages/1"

Example response:

json
{
    "message":"Deploy in progress",
    "starts_at":"2016-08-24T23:21:16.078Z",
    "ends_at":"2016-08-26T23:21:16.080Z",
    "font":"#FFFFFF",
    "id":1,
    "active":false,
    "target_access_levels": [10,30],
    "target_path": "*/welcome",
    "broadcast_type": "banner",
    "dismissable": false,
    "theme": "indigo"
}

Create a broadcast message

[!warning] Broadcast messages are publicly accessible through the API regardless of targeting settings. Do not include sensitive or confidential information, and do not use broadcast messages to communicate private information to specific groups or projects.

Creates a broadcast message.

plaintext
POST /broadcast_messages

Parameters:

AttributeTypeRequiredDescription
messagestringyesMessage to display.
starts_atdatetimenoStarting time (defaults to current time in UTC). Expected in ISO 8601 format (2019-03-15T08:00:00Z)
ends_atdatetimenoEnding time (defaults to one hour from current time in UTC). Expected in ISO 8601 format (2019-03-15T08:00:00Z)
fontstringnoForeground color hex code.
target_access_levelsarray of integersnoTarget access levels (roles) of the broadcast message.
target_pathstringnoTarget path of the broadcast message.
broadcast_typestringnoAppearance type (defaults to banner)
dismissablebooleannoCan the user dismiss the message?
themestringnoColor theme for the broadcast message (banners only).

The target_access_levels are defined in the Gitlab::Access module. The following levels are valid:

  • Guest (10)
  • Planner (15)
  • Reporter (20)
  • Security Manager (25)
  • Developer (30)
  • Maintainer (40)
  • Owner (50)

The theme options are defined in the System::BroadcastMessage class. The following themes are valid:

  • indigo (default)
  • light-indigo
  • blue
  • light-blue
  • green
  • light-green
  • red
  • light-red
  • dark
  • light

Example request:

shell
curl --data "message=Deploy in progress&target_access_levels[]=10&target_access_levels[]=30&theme=red" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/broadcast_messages"

Example response:

json
{
    "message":"Deploy in progress",
    "starts_at":"2016-08-26T00:41:35.060Z",
    "ends_at":"2016-08-26T01:41:35.060Z",
    "font":"#FFFFFF",
    "id":1,
    "active": true,
    "target_access_levels": [10,30],
    "target_path": "*/welcome",
    "broadcast_type": "notification",
    "dismissable": false,
    "theme": "red"
}

Update a broadcast message

[!warning] Broadcast messages are publicly accessible through the API regardless of targeting settings. Do not include sensitive or confidential information, and do not use broadcast messages to communicate private information to specific groups or projects.

Updates a specified broadcast message.

plaintext
PUT /broadcast_messages/:id

Parameters:

AttributeTypeRequiredDescription
idintegeryesID of broadcast message to update.
messagestringnoMessage to display.
starts_atdatetimenoStarting time (UTC). Expected in ISO 8601 format (2019-03-15T08:00:00Z)
ends_atdatetimenoEnding time (UTC). Expected in ISO 8601 format (2019-03-15T08:00:00Z)
fontstringnoForeground color hex code.
target_access_levelsarray of integersnoTarget access levels (roles) of the broadcast message.
target_pathstringnoTarget path of the broadcast message.
broadcast_typestringnoAppearance type (defaults to banner)
dismissablebooleannoCan the user dismiss the message?
themestringnoColor theme for the broadcast message (banners only).

The target_access_levels are defined in the Gitlab::Access module. The following levels are valid:

  • Guest (10)
  • Planner (15)
  • Reporter (20)
  • Developer (30)
  • Maintainer (40)
  • Owner (50)

The theme options are defined in the System::BroadcastMessage class. The following themes are valid:

  • indigo (default)
  • light-indigo
  • blue
  • light-blue
  • green
  • light-green
  • red
  • light-red
  • dark
  • light

Example request:

shell
curl --request PUT \
  --data "message=Update message" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/broadcast_messages/1"

Example response:

json
{
    "message":"Update message",
    "starts_at":"2016-08-26T00:41:35.060Z",
    "ends_at":"2016-08-26T01:41:35.060Z",
    "font":"#FFFFFF",
    "id":1,
    "active": true,
    "target_access_levels": [10,30],
    "target_path": "*/welcome",
    "broadcast_type": "notification",
    "dismissable": false,
    "theme": "indigo"
}

Delete a broadcast message

Deletes a specified broadcast message.

plaintext
DELETE /broadcast_messages/:id

Parameters:

AttributeTypeRequiredDescription
idintegeryesID of broadcast message to delete.

Example request:

shell
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/broadcast_messages/1"