Skip to content

ENG-41634: docs(ai-agents): metadata variables from plain text, and no secrets in card buttons - #624

Open
ketanyekale wants to merge 1 commit into
mainfrom
docs/eng-41634-agent-variables-card-secrets
Open

ketanyekale wants to merge 1 commit into
mainfrom
docs/eng-41634-agent-variables-card-secrets

Conversation

@ketanyekale

Copy link
Copy Markdown
Member

Why

ENG-41634 / Zendesk #45919: a customer's AI agent sent a Card Builder card with an "Ask Admin" button.

  1. @var-custom:dt_ai_question was set to read from Message Metadata, but the UI Kit sends the user's message as plain text with no metadata, so the variable came through empty.
  2. The customer put their REST API key in the button's request headers. Every recipient of a card gets the card definition, so they can read anything in the action's URL, headers or body.

What changed

  • ai-agents/agent-builder/variables/overview.mdx: added a Note under Custom Variables. A Message Metadata variable is empty unless the client puts that key in the message metadata, and the default UI Kit composer sends only text. To fix it, set the metadata from the client (links to /sdk/javascript/send-message) or use a card Custom callback action that sends the value to the backend.
  • card-builder/elements.mdx: added a <Warning> under Actions saying not to put secrets in an action's URL, headers or body, and to call your own backend endpoint instead.
  • card-builder/schema.mdx: added the same <Warning> under Actions, aimed at apiCall url/headers/body. This is the only page that documents headers.

Needs confirmation

  • customCallback runs in the app, not the backend. L2 called it a "backend customCallback". The repo says something else: Card Builder describes it as "Triggers custom handling in your app", and the UI Kit card-messages docs say it is entirely app-defined and sends no server message. So the Note says the app's handler sends the value to your backend. Please confirm there's no server-side customCallback hook I should mention instead.
  • No UI Kit guide for text metadata. I couldn't find a UI Kit guide that shows how to attach metadata to text from the composer (text formatter or custom composer), so the Note links to the JS SDK send-message page. If a UI Kit guide exists, we should link it.
  • Schema may be missing callbackId. The Card JSON Schema lists customCallback as type only. The React v6 UI Kit docs say it carries a callbackId (and optional payload). That mismatch is outside this PR's scope but worth checking.

@mintlify

mintlify Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
cometchat 🟢 Ready View Preview Nov 18, 2026, 4:26 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

@raj-dubey1 raj-dubey1 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated first-pass review (Claude), Raj hasn't reviewed this yet and will do the final review.
Requested by Ketan Yekale on Slack · commit fe72546b6e

Looks good, no blocking issues found. This PR adds three small, additive docs callouts (12 lines across 3 Mintlify MDX files): a Note clarifying that Message Metadata variables are empty unless the sending client writes the key, and two Warnings against putting secrets in card action URLs/headers/body. Both internal links resolve to real pages registered in docs.json navigation, the #actions anchor exists, the / components are valid and used identically elsewhere in the repo, and the action-name references ("Custom callback", apiCall) match the existing action tables. Nothing blocks merge; only two minor content nits remain (claims the surrounding docs don't explicitly back up).

Findings

  1. ⚪ nit ai-agents/agent-builder/variables/overview.mdx:35: Claim that the default UI Kit composer sends plain text without metadata is unverified in-repo
    The new Note states "the default UI Kit message composer sends plain text without it." I searched the repo and found no UI Kit/composer page documenting that the composer omits message metadata; only the metadata concept itself is documented (variables/overview.mdx:29 describes it as message.data.metadata). The claim is plausible and likely correct, but currently unsupported by cited docs — treat as unverified, not wrong. Suggested fix: link the claim to the UI Kit composer docs, or soften to e.g. "a plain-text composer message carries no metadata unless you add it."
  2. ⚪ nit ai-agents/agent-builder/variables/overview.mdx:35: Note describes a Custom callback backend pattern the Card Builder docs don't spell out
    The Note tells readers to use a Custom callback "whose handler sends the value to your backend," but card-builder/elements.mdx:67 only says Custom callback "Triggers custom handling in your app" and card-builder/schema.mdx:90 lists customCallback as type-only. This does not contradict the repo, but it points readers at a pattern the Card Builder pages never describe. Suggested fix: add a brief sentence to the Card Builder Actions section describing the custom-callback-to-backend pattern, or adjust the Note's phrasing to match what those docs actually state.
Checks run
Command Exit Result
git diff origin/main...HEAD 0 3 files, 12 additive lines (one , two callouts); no code or config changes
find . -name 'send-message*' (sdk/javascript) + grep '^#' card-builder/elements.mdx 0 sdk/javascript/send-message.mdx exists; '## Actions' heading at line 53 → slug #actions valid; both links resolve
grep -rl '<Warning>'/'<Note>' --include='*.mdx' . 0 Both components used across the repo (e.g. calls/react-native/events.mdx); new blocks are well-formed
grep -n 'Custom callback/customCallback/apiCall' card-builder/elements.mdx card-builder/schema.mdx 0 'Custom callback' matches elements.mdx:67; customCallback matches schema.mdx:90; apiCall/url/headers/body wording matches schema table
grep -n 'sdk/javascript/send-message/card-builder/elements/card-builder/schema' docs.json 0 All three routes registered in navigation (lines 119, 120, 3151); links are valid Mintlify routes
Mintlify build / link checker 0 NOT RUN — no build tooling installed in worktree; verification limited to scoped static checks per review constraints (no e2e/app run)

This comment doesn't approve or block the PR.

This branch was successfully deployed

1 active deployment
staging — fe72546b Deployed Nov 18, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants