TECHNICAL_NOTES.md

Technical Notes: @Mentions Implementation

Problem

The initial implementation (v1.2.0) sent mentions as plain text using the message field:

{
  "message": "Hey @john_designer please review this"
}

Result: Mentions appeared as plain text in Figma, not as clickable user objects. Users were not notified.

Solution

Version 1.2.1 implements the correct format using Figma's message_meta structure:

{
  "message_meta": [
    {"t": "Hey "},
    {"t": "@john_designer", "mention": "user_id_here"},
    {"t": " please review this"}
  ]
}

Result: Mentions appear as clickable user objects in Figma. Users receive notifications.

Implementation Details

1. Message Parsing

The parseMessageWithMentions() function:

• Uses regex /@@\w+/g to find all @mentions
• Splits the message into segments (text + mentions)
• Creates a message_meta array with proper structure

2. User ID Resolution

The getCommentUsers() function now returns:

{
  users: [...],        // Array of user objects for display
  usersMap: Map()      // Map of handle → user_id for mentions
}

3. Automatic Detection

Both postFigmaComment() and replyToFigmaComment():

• Detect if message contains @\w+ pattern
• If YES: Fetch users, parse mentions, use message_meta
• If NO: Use simple message field (backward compatible)

Message Format Comparison

Without Mentions (Simple)

{
  "message": "This looks great!",
  "client_meta": { ... }
}

With Mentions (message_meta)

{
  "message_meta": [
    {"t": "Hey "},
    {"t": "@john", "mention": "123456789"},
    {"t": " and "},
    {"t": "@maria", "mention": "987654321"},
    {"t": " please review"}
  ],
  "client_meta": { ... }
}

Discovery Process

This format was discovered through:

1. Researching Figma API documentation (mentions not documented)
2. Finding community forum discussions confirming mentions work
3. Learning about message_meta format from formatting discussions
4. Reverse-engineering the web client request structure
5. Implementing based on pattern: {t: "text", mention: "user_id"}

Important Notes

Not Officially Documented

• The message_meta format is not in official Figma API docs
• This implementation is based on reverse-engineering the web client
• Figma uses this format internally, so it's stable in practice
• No official guarantee of long-term support

Fallback Behavior

• If username not found: keeps @username as plain text
• If no mentions detected: uses simple message field
• Maintains backward compatibility

Limitations

• Can only mention users who have previously commented
• Username must match exactly (case-sensitive in implementation)
• Regex pattern \w+ means usernames with special chars may not work

Future Improvements

Potential enhancements:

1. Cache user list to avoid repeated API calls
2. Support for mentioning users who haven't commented yet
3. Better username matching (fuzzy search)
4. Support for Figma's other formatting options (bold, italic, etc.)

References

• Figma Forum: User mentions in REST API
• Figma Forum: Format comments messages
• Figma Comments API Endpoint

Example Usage

// Input from user
const message = "Hey @john_designer please review the @maria_ux color updates";

// Internal processing
// 1. Detect mentions: ["john_designer", "maria_ux"]
// 2. Fetch users and get IDs
// 3. Transform to message_meta

// Output to Figma API
{
  "message_meta": [
    {"t": "Hey "},
    {"t": "@john_designer", "mention": "user_id_1"},
    {"t": " please review the "},
    {"t": "@maria_ux", "mention": "user_id_2"},
    {"t": " color updates"}
  ]
}

Version History

• v1.2.0: Initial @mentions support (plain text only - buggy)
• v1.2.1: Fixed @mentions using proper message_meta format (working)