Announcing a new model in Cowork

The desktop receives the active announcement in modelAnnouncement from GET /v1/cowork/state. 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:

{"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.