Announcement Module

This module allows an app to show notices to the users of a Crowdin Enterprise organization.

Announcement placements:

• header-alert: the alert strip below the page header, present on every page of the organization
• glossary: above the term table on a glossary page

The module is available only in Crowdin Enterprise and only in self-hosted apps.

How It Works

1. An organization admin installs the app and chooses who can see its announcements.
2. A user opens a page with the module’s placement. Crowdin Enterprise sends a request to the module’s url with the current context.
3. The app answers with the announcements it wants that user to see, or with an empty list.
4. Crowdin Enterprise shows the announcements at the placement. The user can close the ones the app marked as dismissible.

Access

You can grant access to this module to one of the following user categories:

• Only organization admins
• Organization admins, project managers and developers
• All users in the organization projects
• Selected users

Crowdin Enterprise pre-selects All users in the organization projects for this module.

Structure

manifest.json

{
  "baseUrl": "https://app.example.com",
  "modules": {
    "announcement": [
      {
        "key": "header-announcements",
        "name": "Header announcements",
        "url": "/announcements/header",
        "placement": "header-alert"
      }
    ]
  }
}

An app can declare several announcement modules, one per placement or several at the same placement.

Properties

key	Type: string Required: yes Description: Module identifier within the Crowdin app.
name	Type: string Required: yes Description: The human-readable name of the module.
url	Type: string Required: yes Description: The relative URL Crowdin Enterprise requests the announcements from.
placement	Type: string Required: yes Allowed values: header-alert, glossary Description: Where the module’s announcements are shown.
environments	Type: string Allowed values: crowdin-enterprise Description: Set of environments where a module could be installed. This parameter is needed for cross-product applications.

Communication between Announcement App and Crowdin

Crowdin Enterprise requests the announcements each time it renders the module’s placement. It sends a POST request to baseUrl + url with the app’s JWT in the Authorization header, and the app has 10 seconds to answer.

Request to the App

Request payload example:

{
  "context": {
    "placement": "glossary",
    "userId": 123,
    "glossaryId": 456
  }
}

context.placement	Type: string Description: The placement the announcements are requested for.
context.userId	Type: integer Description: The user the announcements are requested for.
context.glossaryId	Type: integer Description: The glossary whose page the user opened. Sent with the glossary placement.

The organization is identified by the JWT, so the payload carries the context only.

Expected Response from the App

Response payload example:

{
  "data": {
    "items": [
      {
        "id": "autumn-release-terms",
        "text": "The autumn release terminology is in the glossary. Check it before you start translating.",
        "dismissible": true,
        "expiresAt": "2026-10-01T00:00:00+00:00",
        "actionLabel": "Read the release notes",
        "actionUrl": "https://example.com/releases/autumn"
      }
    ]
  }
}

Return an empty items array when the app has nothing to show.

id	Type: string Required: yes Description: Identifier of the announcement within the module, up to 255 characters. A closed announcement stays closed as long as it keeps this value, so give an edited announcement a new id to show it again.
text	Type: string Required: yes Description: The announcement itself, up to 65,535 characters. The text is shown as plain text, and bare http and https URLs in it become links. In the header strip the text is shown on one line, with the full text in a tooltip.
dismissible	Type: boolean Required: yes Description: Whether the user can close the announcement.
expiresAt	Type: string Description: The moment the announcement stops being shown, in ISO 8601 format. Announcements without this field are shown until the app stops returning them.
actionLabel	Type: string Description: The label of the announcement’s action link, up to 255 characters. Use it together with actionUrl.
actionUrl	Type: string Description: The address the action link opens in a new tab, up to 2,048 characters. Must start with https://. Use it together with actionLabel.

Crowdin Enterprise reads a response of up to 512 KB with up to 1,000 items, and shows the first 10 valid announcements from it. An announcement that breaks the rules above is skipped, and the rest of the response is still used.

Display Rules

Crowdin Enterprise applies the following rules to the announcements an app returns:

• Announcements the user cannot close come first, and the rest follow in the order the apps were installed.
• The header strip shows one announcement at a time. With more than one, the strip also shows a counter and the arrows for moving between them.
• Closing an announcement hides it in that browser only.
• Crowdin Enterprise reloads the header announcements every 15 minutes, and the announcements at both placements when the user returns to the tab. An announcement with expiresAt also triggers a reload at its expiry.