Skip to main content

Explain the setting the customer is looking at

Section: DOC-MA-conversations-client-context#give-the-assistant-context-about-the-current-screen.

Add a “help with this setting” conversation to your application. When a user asks from the notification settings page, send a small description of that screen with the question, then show the reply and refresh the context if the user moves elsewhere.

The result is a screen-aware help exchange. Client context is descriptive data; it does not authenticate the user, authorize a settings change or prove the assistant used every value.

Before you start​

Section: DOC-MA-conversations-client-context#before-you-start.

Create a thread and configure authentication. Use only context your application is entitled to send. Avoid credentials, full URLs containing tokens, and unnecessary personal data.

Choose the few facts the help answer needs: a short page identifier, device type and locale are sufficient for the example. Read them from the current application view at send time; do not reuse an old page description after navigation.

Step 1: Send the current settings page with the question​

Section: DOC-MA-conversations-client-context#send-the-current-context.

Use this body with send-message. Replace the conversation key with your created thread:

{
  "conversationKey": "<your-thread-id>",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [{"type": "CONTENT_PART_TYPE_TEXT", "content": "Help me understand this setting."}],
    "clientContext": {
      "values": {
        "page": "/settings/notifications",
        "device": "web",
        "locale": "en-US"
      }
    }
  }
}

Request example: Send a message to a conversation · Request fields.

Keep this map small and relevant to the current screen. Check the reference limits before adding more context.

Retain the accepted run ID. The sample describes /settings/notifications; the map is not a snapshot of every setting or permission, so keep checks for actual changes in your application.

Step 2: Show the answer and handle a stale-screen reply​

Section: DOC-MA-conversations-client-context#handle-the-result.

Follow the returned run using the generation guide. If the connection drops, refresh that run's state before resending. If the answer refers to an old screen, send a new message with the current context and a clear correction. Do not assume that client context reduces cost or latency.

See profile prompt variables for reusable template inputs and API conventions for JSON presence rules.

Finished result: the user can ask about the visible screen and receive a correlated answer. If the answer addresses an earlier screen, correct the context in a new user message after reconciling the previous run. Do not silently execute a proposed settings change from descriptive context.

Step 3: Refresh context when the user changes screens​

Section: DOC-MA-conversations-client-context#understand-when-it-applies.

For a follow-up from a different screen, rebuild the map from that screen and attach it to the new message. This is the recommended path; appending a context-only message is not a persistent setting for future sends.

Treat context as descriptive data, not an instruction that grants permissions. Check the assistant's proposed action against the actual current page and the user's permissions; its answer does not confirm that every context value was used.

Document ID: DOC-MA-conversations-client-context. Section identities and revisions.