Updating Model Context

A widget can contribute content to the model context so your app can use it on future turns.

ui/update-model-context is sent over the same messageBack channel other Teams surfaces use, so it arrives as a message activity. Tool calls are different: they arrive as htmlwidget/calltool invoke activities (see tool calls). This particular request is fire-and-forget: your app does not send a response.

(If you have used adaptive cards, this is the widget-side equivalent of Action.Submit.)

Preview

HTML Widgets are in preview and the API surface may change. HTML Widgets are planned for public preview on 11/16.

The request

When a widget calls ui/update-model-context, the Teams client delivers an ordinary message activity, and the McpUiUpdateModelContextRequest arrives on its value field:

{
  "type": "message",
  "value": {
    "method": "ui/update-model-context",
    "params": {
      "content": [{ "type": "text", "text": "The user selected the blue theme." }],
      "structuredContent": { "theme": "blue" }
    }
  }
}

Inside value, the content field reuses the same content block union as a tool call result, and the structuredContent field carries arbitrary structured data. You never parse this by hand; the helper below reads value off the activity and returns the typed request.

Parsing the request

The SDK provides a helper that reads the typed request off an incoming message activity. It returns the parsed request when the activity carries a valid ui/update-model-context request, and nothing otherwise, so you can branch on the result inside your message handler.

Call tryGetWidgetModelContext inside your message handler. It returns the typed request when the activity carries a valid ui/update-model-context request, and undefined otherwise.

import { App, tryGetWidgetModelContext } from '@microsoft/teams.apps';

const app = new App();

app.on('message', async ({ activity, send }) => {
  const modelContext = tryGetWidgetModelContext(activity);
  if (modelContext) {
    // Use modelContext.params.content / modelContext.params.structuredContent
    // to update your model context for future turns. No response is sent.
    console.log('model context update:', modelContext.params);
    return;
  }

  // ... handle other messages
});

The helper is tolerant of two wire shapes: the raw request object, and an envelope of the form { "type": "widgetModelContext", "data": <request> }. Both resolve to the same typed request.