# Announcing a new model in Cowork

The desktop receives the active announcement in `modelAnnouncement` from [`GET /v1/cowork/state`](./state.md). The field is `null` for keys without the `cowork-desktop` assignment. The key must have `vibe:cowork` and be bound to a person and a Bitrix24 account.

## Saved model choice

After restoring the model choice for **new sessions**, and after each explicit switch, the desktop calls `PUT /v1/cowork/model-preference`:

```json
{"modelId":"bitrix/bitrixgpt-5.5-agent","previousModelId":"bitrix/bitrixgpt-6.0-agent"}
```

`modelId` and `previousModelId` are public canonical identifiers from `/v1/models`. For a personal or external model absent from `/v1/models`, send only the literal `modelId: "external"` instead of its private ID. Do not send the request until the person's choice has been restored. The Bitrix24 account default does not stand in for that choice. Repeating the same choice does not add a history entry.

## Snapshot and events

`modelAnnouncement` contains `id`, `modelId`, `shortName`, `title`, `baseLocale`, the `descriptionByLocale` and `returningByLocale` dictionaries, `starterIds`, `startedAt`, `endsAt`, `returning`, `eligible`, `reason`, and `progress`. `title` is for the first window; `shortName` is for other surfaces. When a translation is missing, the client uses `baseLocale` (`ru` on `.tech`, `en` on `.com`).

`eligible: false` means no touch should appear. Possible `reason` values are `selection_unknown`, `selected_model`, `recently_used`, `refused`, `already_tried`, and `dismissed_three_times`. An unknown saved choice always gives `selection_unknown`, even when the target model is the default.

`POST /v1/cowork/model-announcement/:id/events` accepts `{ "eventId": "UUID", "action": "shown", "step": 1 }` for a display. Send `dismiss`, `never`, and `try` separately, reusing the same UUID when retrying one request. `never` rejects the entire announcement; `dismiss` closes the current touch. The server atomically validates the next step, intervals, and campaign state. The response is `{ "success": true, "replayed": false }`.

For funnel breakdowns, a display or dismissal may include `surface: "window" | "hint"`. A `try` may include `surface: "window" | "hint" | "session"`, `source: "primary" | "starter" | "session_switch"`, and a `starterId` for a ready task. All actions may include `tab: "cowork" | "code"` and `locale: "ru" | "en" | "de" | "es" | "fr" | "pt-BR" | "ja" | "zh" | "th" | "vi"`. The `session_opened` event sends `{ "eventId": "UUID", "action": "session_opened", "tab": "cowork", "sessionId": "stable session ID", "sessionKind": "new" }`; `tab: "code"` and `sessionKind: "existing_idle"` are also valid. The server deduplicates by campaign, seat, tab, session, and opening kind. Send it for eligible people before or after trying the model. Arbitrary tabs and kinds are rejected.

The touch schedule is the first display, then days 3, 7, 21, and 30 after that display, with at least three full days between touches. `endsAt` is an exclusive boundary after the campaign's last calendar day.

## Administration

When adding a chat model in Cowork settings, an administrator must explicitly answer whether to announce it (`announce: true/false` in `POST /api/platform/cowork-settings/models`). Draft creation, audience preview, statistics, launch, and stop are available through `/api/platform/cowork-settings/models/:policyId/announcement`. A completed announcement cannot be relaunched.

The `/announcement/stats` endpoint measures the share of recipients and their Bitrix24 accounts with a successful model turn in a week. The prelaunch audience is reconstructed from saved choice history at the beginning of the preceding week; `before` is `null` when history is incomplete. `after` appears after a full week for the audience frozen at launch. Overall active seats are never substituted for that audience. `eventsByStep` contains actual displays, dismissals, refusals, tries, starter choices, switches, and session openings across five steps; `eventsByTabLocale` breaks touches down by tab and language. `sessionTriggers` counts new and resumed sessions before a try separately from sessions after a try. `outcomes.tried` counts audience members who pressed Try, chose the model themselves, or made a successful turn; `outcomes.retained` counts those whose current choice is the target model. `firstSuccessfulTurnUsers` counts recipients who made at least one successful turn on the target model during the campaign. `rollback` counts returns to the immediately preceding saved model and separately reports recipients with unknown choice history.

The quiet-phase line in the model list uses only complete UTC days from the last seven days after the model was added. Its denominator is seats with turns, and its numerator is those same seats with a successful turn on the model. It shows no percentage when the daily rollup is incomplete. For a default model, this is an informative usage share, not an announcement effect.

On the international site, the author enters English copy and may manually enter other languages. The platform has no arbitrary-text translation service yet: it does not generate translations, and an empty client language falls back to English. This is the current AC-034 limitation.