Posted-file actions and external links

Declare attachments to add an action to posted file-card context menus. Add external_links to open a public HTTPS page from the resulting trusted context, and ui for a disclosure dialog.

Resolve the selected file

cleanup.push(
  await api.attachments.registerContextAction(
    {
      id: "file-details",
      label: "File details",
      submenu: { id: "tools", label: "Tools" },
    },
    async (context) => {
      try {
        const file = await api.attachments.resolve(context.handle);
        await api.ui.notify(file.filename + ": " + file.size + " bytes");
      } catch {
        await api.ui.notify(
          "File context expired or unavailable. Open the file menu again.",
        );
      }
    },
  ),
);

The callback receives { handle, filename }. Resolution returns { id, filename, size, url }. The host requests only the clicked message’s metadata and resolves an exact attachment ID or unique filename. Ambiguous duplicate names fail rather than guessing.

This covers posted file cards, not inline media or unsent uploads. It differs from ui.registerAttachmentAction, which adds a composer action.

Open an external page

Call await api.externalLinks.open(url) within the live context. Only a trusted file-menu activation or trusted native-dialog submission in that context authorizes navigation. The authorization expires after two minutes and is single-use; it never enters the sandbox.

Before sharing an attachment URL with a third-party website, show a disclosure and allow cancellation. URLs may include signed access parameters. Do not log them. Virus Check demonstrates the full consent flow and safe URL encoding.

Lifetime and failures

Attachment handles expire after five minutes or upon navigation, replacement, another context selection, or shutdown. Ordinary menu dismissal after activation does not invalidate the selected context.

Lookup is limited to ten seconds, 1 MiB response data, and 100 attachments. External URLs must use public-host HTTPS without credentials or nonstandard ports; literal IPs and local hostnames are rejected.

After context or authorization errors, ask the user to activate the file menu again. External links open the browser; they do not return network response content.