---

Add Comment

The createComment mutation allows you to add comments to records in Blue. Comments support rich HTML content, file attachments, @mentions, and are automatically integrated with the activity feed and notification system.

Basic Example

Add a simple text comment to a record:

mutation AddComment {
  createComment(
    input: {
      html: "<p>This task is progressing well!</p>"
      text: "This task is progressing well!"
      category: TODO
      categoryId: "clm4n8qwx000008l0g4oxdqn7"
    }
  ) {
    id
    html
    text
    createdAt
    user {
      id
      name
    }
  }
}

Advanced Example

Add a comment with rich formatting, images, and TipTap editor processing:

mutation AddCommentAdvanced {
  createComment(
    input: {
      html: "<p>Here's my <strong>feedback</strong> on this task:</p><ul><li>Great progress on the design</li><li>Need to review the API integration</li></ul><p>Attaching screenshot:</p><img src='data:image/png;base64,iVBOR...' />"
      text: "Here's my feedback on this task: - Great progress on the design - Need to review the API integration Attaching screenshot:"
      category: TODO
      categoryId: "clm4n8qwx000008l0g4oxdqn7"
      tiptap: true
    }
  ) {
    id
    html
    text
    createdAt
    user {
      id
      name
      avatar
    }
    activity {
      id
    }
    isRead
    isSeen
  }
}

Input Parameters

CreateCommentInput

Parameter	Type	Required	Description
html	String!	✅ Yes	HTML content of the comment (will be sanitized for security)
text	String!	✅ Yes	Plain text version of the comment content
category	CommentCategory!	✅ Yes	Type of entity being commented on (use TODO for records)
categoryId	String!	✅ Yes	ID of the entity (record) being commented on
tiptap	Boolean	No	Enable TipTap editor-specific HTML sanitization and processing

CommentCategory Values

Value	Description
TODO	Comment on a record/todo item
DISCUSSION	Comment on a discussion thread
STATUS_UPDATE	Comment on a status update

Response Fields

The mutation returns a Comment object with comprehensive details:

Field	Type	Description
id	ID!	Unique identifier for the comment
uid	String!	Alternative unique identifier
html	String!	HTML content of the comment
text	String!	Plain text version of the comment
category	CommentCategory!	Type of entity commented on
createdAt	DateTime!	When the comment was created
updatedAt	DateTime!	When the comment was last updated
deletedAt	DateTime	When the comment was deleted (null if active)
deletedBy	User	User who deleted the comment
user	User!	User who created the comment
activity	Activity	Associated activity record
discussion	Discussion	Associated discussion (if category is DISCUSSION)
statusUpdate	StatusUpdate	Associated status update (if category is STATUS_UPDATE)
todo	Todo	Associated record (if category is TODO)
isRead	Boolean	Whether current user has read this comment
isSeen	Boolean	Whether current user has seen this comment
aiSummary	Boolean	Whether this comment was generated by AI

Required Permissions

Users must have appropriate project access to comment on records:

Access Level	Can Add Comments
OWNER	✅ Yes
ADMIN	✅ Yes
MEMBER	✅ Yes
CLIENT	✅ Yes
COMMENT_ONLY	✅ Yes
VIEW_ONLY	❌ No

Important: The user must be a member of the project that contains the record and must NOT have VIEW_ONLY access level.

Error Responses

UnauthorizedError

{
  "errors": [{
    "message": "You don't have permission to comment on this record",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

When: User lacks permission to comment on the specified record/entity.

ValidationError

{
  "errors": [{
    "message": "Invalid input parameters",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

When: Required fields are missing or contain invalid data.

CommentNotFoundError

{
  "errors": [{
    "message": "Record not found",
    "extensions": {
      "code": "COMMENT_NOT_FOUND"
    }
  }]
}

When: The specified categoryId doesn't correspond to an existing record.

UserInputError

{
  "errors": [{
    "message": "Content validation failed",
    "extensions": {
      "code": "BAD_USER_INPUT"
    }
  }]
}

When: HTML content fails sanitization or contains malicious code.

Important Notes

Content Processing

• HTML Sanitization: All HTML content is automatically sanitized to prevent XSS attacks
• File Extraction: Images and attachments embedded in HTML are extracted and stored in S3
• TipTap Mode: When tiptap: true, uses specialized sanitization for TipTap editor content
• @Mentions: User mentions in comments are automatically processed and trigger notifications

Performance Considerations

• Comments are indexed for search automatically
• Large image attachments are processed asynchronously
• Each comment creates an activity record for the project timeline

Side Effects

Adding a comment triggers several automated processes:

• Activity Creation: Creates an activity record visible in project timeline
• Search Indexing: Comment content is added to the project search index
• Notifications: Sends email, push, and in-app notifications to relevant users
• Real-time Updates: Publishes comment to GraphQL subscriptions for live updates
• Webhooks: Triggers external webhook if configured for the project
• @Mention Processing: Processes user mentions and sends targeted notifications
• File Processing: Extracts and processes any embedded images or files from HTML content

Content Security

• All HTML is sanitized using industry-standard libraries
• File uploads are validated for type and size
• Malicious content is automatically stripped
• User-generated content is escaped properly in all contexts

Integration Features

• Activity Feed: Comments appear in the project activity timeline
• Search: Comment content is searchable within the project
• Notifications: Configurable notification preferences for different comment types
• Real-time: Comments appear instantly for other users viewing the same record
• Mobile Support: Comments are fully supported in mobile applications

Related Endpoints

• List Comments: Query comments to retrieve existing comments on records
• Update Comment: Modify existing comment content
• Delete Comment: Remove comments with proper authorization
• List Records: Query todos to find records that can be commented on