Commenting

Plan Feature

This feature is only available on Growth and Scale plans.

Comments let your users leave feedback and have discussions directly on email templates inside the editor. Comments are thread-based, can be anchored to specific blocks, and support resolving/unresolving for review workflows.

How It Works

1. Your token endpoint returns the current user's identity and a cryptographic signature (see Setup)
2. The SDK shows a Comments button in the editor toolbar
3. Users can create comments, reply to existing threads, and resolve conversations
4. The SDK calls the onComment callback (if configured) whenever a comment action occurs

User identity is verified with HMAC-SHA256 so it cannot be spoofed on the client side. Each user can only edit and delete their own comments.

Setup

1. Get Your Signing Key

Find the Signing Key in your project settings on the Templatical dashboard. This key is used to sign user identity data. Store it securely on your backend alongside your Client ID and Client Secret.

2. Update Your Token Endpoint

Your token endpoint already returns a token response (see Authentication). To enable commenting, add a user object to the response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1709251200,
  "project_id": "proj_abc123",
  "tenant": "acme-corp",
  "user": {
    "id": "user_123",
    "name": "Jane Smith",
    "signature": "a1b2c3d4..."
  }
}

Field	Type	Description
user.id	string	A unique identifier for the user in your system
user.name	string	The user's display name (shown on comments)
user.signature	string	HMAC-SHA256 signature of the user ID

If the user object is omitted, the Comments button will not appear in the toolbar.

Computing the Signature

The signature algorithm is:

1. HMAC-SHA256 the user's id string (e.g. "user_123") with your signing key

Backend Examples

import crypto from 'crypto';

app.post('/api/token', async (req, res) => {
  // 1. Get the token from Templatical
  const response = await fetch('https://templatical.com/api/v1/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: process.env.TEMPLATICAL_CLIENT_ID,
      client_secret: process.env.TEMPLATICAL_CLIENT_SECRET,
      tenant: req.user.organizationId,
    }),
  });

  const tokenData = await response.json();

  // 2. Compute the user signature
  const signature = crypto
    .createHmac('sha256', process.env.TEMPLATICAL_SIGNING_KEY)
    .update(String(req.user.id))
    .digest('hex');

  // 3. Return token + user config
  res.json({
    ...tokenData,
    user: {
      id: req.user.id,
      name: req.user.name,
      signature,
    },
  });
});

Important

The id value used for signing must match the user.id value returned in the response. Ensure you use the same string representation in both places.

Features

Thread-Based Comments

Comments support threading — users can reply to any root comment to create a conversation thread. Replies are displayed inline below their parent comment.

Block Anchoring

Comments can be anchored to specific template blocks. When a comment is associated with a block, a comment indicator badge appears on that block in the editor. Clicking the badge opens the comments sidebar filtered to that block's comments.

Resolving Comments

Any user can resolve or unresolve a comment thread. Resolved comments are visually distinct and can be filtered out, making it easy to track which feedback has been addressed.

Permissions

Users can only edit and delete their own comments. Ownership is verified server-side by matching the signed user identity against the comment's author. Any user can resolve or unresolve any comment.

Disabling Commenting

Even if your plan supports commenting and your token endpoint returns user identity, you can disable commenting on demand by setting commenting: false in the SDK configuration:

const editor = await init({
  container: '#email-editor',
  auth: { url: 'https://your-app.com/api/token' },
  commenting: false,
});

When commenting is false, the Comments button will not appear in the toolbar regardless of plan or user configuration. Omitting the option or setting it to true (default) allows commenting based on plan availability and user identity.

onComment

Called whenever a comment action occurs. Use this callback to sync comment activity with your own systems — for example, to send notifications or log activity.

const editor = await init({
  container: '#email-editor',
  auth: { url: 'https://your-app.com/api/token' },
  onComment: (event) => {
    console.log(event.type, event.comment);

    // Example: notify your backend about new comments
    if (event.type === 'created') {
      fetch('/api/comment-notifications', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          templateId: event.comment.template_id,
          authorName: event.comment.author_name,
          body: event.comment.body,
        }),
      });
    }
  },
});

The event object contains:

Field	Type	Description
type	string	One of: created, updated, deleted, resolved, unresolved
comment	Comment	The comment object (see Comment Object)

Comment Object

Field	Type	Description
id	string	Unique comment identifier (UUID)
template_id	string	The template this comment belongs to
block_id	string | null	The block this comment is anchored to (null for general comments)
parent_id	string | null	Parent comment ID (null for root comments)
body	string	The comment text (max 2000 characters)
author_identifier	string	The author's user ID
author_name	string	The author's display name
resolved_at	string | null	ISO timestamp when the comment was resolved
resolved_by_identifier	string | null	User ID of who resolved the comment
resolved_by_name	string | null	Display name of who resolved the comment
created_at	string	ISO timestamp when the comment was created
updated_at	string	ISO timestamp when the comment was last updated
replies	Comment[]	Array of reply comments (only on root comments)