> ## Documentation Index
> Fetch the complete documentation index at: https://assembly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Markup and comments

> Collect feedback on designs and PDFs by letting clients comment directly on the page, with version history and a clear status on every item.

> [!NOTE]
>
> **Template.** You can change anything about this app by describing it in its build chat. See [App templates](https://assembly.com/docs/building-new-apps/app-templates.md).

Send a design or PDF to a client and get feedback pinned to the exact spot it's about. Clients click anywhere on the file to leave a comment, then approve the item or request changes. You reply, resolve what you've handled, and upload a new version, and every earlier version stays on the item with its comments.

**Category:** Requests · **Used by:** your team and your clients · **Works with:** CRM

## Features

* Review items sent to a client or a whole company, each with a PNG, JPG, or PDF file up to 50 MB
* Pinned comments on a specific spot of any page, plus general comments on the whole file, with threaded replies
* Four statuses: **Awaiting review**, **Changes requested**, **Revised**, and **Approved**. Clients see them in plain language, such as **Needs your review** and **New version**
* Versions: upload a revised file and the item moves to **Revised**. Earlier versions and their comments stay viewable, read-only
* Resolve and reopen comments, with **Open**, **Resolved**, and **All** filters on each version
* A list with a count for each status, plus search, filters by recipient and due date (**Overdue** or **Due soon**), and sortable columns
* An activity history on every item, and a view of when the recipient last opened it
* An archive for items you want out of the way

## How to use it

### For your team

> [accordion] Send an item for review
>
> 1. Open the app and click **Send for review**.
> 2. Enter a **Name**, such as "Homepage design v1".
> 3. Under **Send to**, choose a client or a company. Sending to a company shares the item with every client in it.
> 4. Under **File**, upload a PNG, JPG, or PDF. Files can be up to 50 MB.
> 5. Optionally add **Instructions** telling the client what to look at, and a **Due date**. The due date can't be in the past.
> 6. Click **Send for review**. The item starts as **Awaiting review** and the client is notified.

> [accordion] Track what's waiting
>
> The status cards at the top of the list show how many items are in each status. Click a card to filter the list to it, and click it again to clear it. Use search, **Recipient**, and **Due dates** (**Overdue** or **Due soon**, meaning in the next seven days) to narrow the list, and sort by **Name**, **Recipient**, **Status**, **Version**, **Due**, or **Updated**. Items with the newest activity are at the top.

> [accordion] Reply to and resolve comments
>
> Open an item to see the file with the client's numbered pins, and the **Comments** list beside it.
>
> 1. Click a pin or a comment to open its thread.
> 2. Type in **Reply…** to answer the client. They're notified of your reply.
> 3. Click **Resolve** once you've handled a comment. Click **Reopen** to bring it back.
>
> Only clients drop pins and start new comments. Your team replies and resolves. Only your team can resolve a comment.

> [accordion] Upload a new version
>
> When a client requests changes, the item moves to **Changes requested** and your team is notified.
>
> 1. Open the item and click **Upload new version**.
> 2. If comments are still open, the app suggests resolving them first so the client can see what changed. Click **Resolve them first** to go back, or **Upload anyway**.
> 3. Choose the new file and click **Upload version**.
>
> The item moves to **Revised** and the client is notified. Use the version menu to view earlier versions and their comments, read-only. You can't upload a new version to an archived or approved item.

> [accordion] Edit an item's details
>
> From the item's actions, click **Edit details** to change the **Name**, **Instructions**, or **Due date**, then click **Save**. The client is notified about what changed.

> [accordion] See who's looked at it
>
> Hover over the recipient's avatar on an item to see who it was sent to and when they last opened it. The item's activity history lists every upload, comment, resolve, status change, and edit.

> [accordion] Archive or delete items
>
> From an item's actions, click **Archive** to hide it from the client and move it out of the main list. Turn on **Archived** in the list to see archived items, and click **Unarchive** to restore one. **Delete** permanently removes the item, every version, and all comments, for your team and the client, and can't be undone.

> [accordion] Use it from a client's profile
>
> The app also shows on a client's profile in your CRM, with the same list filtered to that client. Items you send from there go to that client.

### For your clients

> [accordion] Find items to review
>
> Clients see their items grouped under **Needs your review**, **Changes requested**, and **Approved**. Each item shows a short note, such as **Not opened yet**, **New version ready for your review**, or **You approved this**, and a dot marks unopened activity.

> [accordion] Comment on the file
>
> 1. Open an item. Any **Instructions from the team** appear above the file.
> 2. Click anywhere on the file to drop a pin, type what should change there, and post it. Pins can be dragged to a new spot.
> 3. To comment on the file as a whole, use the comment box under the **Comments** list.
> 4. Reply in any thread with **Reply…**.
>
> Clients can only comment on the latest version. Earlier versions are read-only.

> [accordion] Approve or request changes
>
> Click **Approve** or **Request changes** at the top of the item, then confirm.
>
> * **Request changes** sends the comments on the current version to your team. If there are no comments yet, the client writes one in the dialog first. After requesting changes, the client can keep commenting and replying, but can't approve or request changes again until a new version arrives.
> * **Approve** applies to the latest version and marks the item as done. Comments close once it's approved, and the item becomes read-only.

Clients only see items sent to them or to their company, and never see archived items. Team members with limited client access only see items for the companies they can access.

## Notifications

* **When you send an item, upload a new version, or edit an item's details**, the client, or every client in the company, gets an email and an in-product notification.
* **When your team replies to a comment**, the client gets an email and an in-product notification that quotes the reply. Client replies don't notify your team.
* **When a client requests changes**, your team gets an email and an in-product notification with the number of comments.
* **When a client approves**, your team gets an in-product notification. Email for approvals is off by default, and each team member can turn it on in their notification settings.

Resolving a comment never notifies anyone. Archiving an item clears the client's notifications for it.

To change who's notified or what the messages say, see [Configuring notifications](https://assembly.com/docs/building-new-apps/configuring-notifications.md).

## Set it up

**1. Add the template**

Click **Add App** in the Dashboard sidebar. Find **Markup and comments** under **Start from a template**, or scroll down to **Browse all apps** and pick the **Requests** filter.

**2. Try it as your team**

The app lands in your sidebar as a draft. Send a test item to your test client.

**3. Check the client side**

In the builder's **Client view**, pick your test client, drop a few pins on the file, and approve or request changes.

**4. Publish it**

Publish the app with visibility set to **Hidden from all people**, or on plans with custom visibility, limited to your test client. Sign in as your test client to try it in the real client experience, then make it visible to the clients who should use it. See [Launching apps](https://assembly.com/docs/building-new-apps/launching-apps.md).

## Change it with the app builder

This app is a template, so you can change anything about it by describing what you want.

**1. Open the build chat**

Open **Markup and comments** from your Dashboard sidebar, click its name at the top, then click **Switch to builder**.

**2. Describe the change**

Write what you want the way you'd ask a teammate. Say who it's for and where it shows up, such as your team's list or the client's review page.

**3. Check the preview**

The app builder makes the change and updates the preview. Switch between **Team view** and **Client view** to check both sides, and pick a client to see it as them.

**4. Publish**

Click **Publish** when you're happy. Until you do, your clients keep seeing the last published version.

Changes people often make to this template:

* "Remind clients by email three days before an item is due, and again on the due date"
* "Let my team drop pins and start comments on the file, not just reply"
* "Notify my team when a client replies to a comment"
* "Accept Word and PowerPoint files as well as PNG, JPG, and PDF"
* "Let my team set an item's status by hand, such as moving it back to Awaiting review"
* "Add a Project field and filter the list by it"

See [Iterating on apps](https://assembly.com/docs/building-new-apps/iterating-on-apps.md) for how to describe changes well and how to go back to an earlier version.

To rename the app, or change who can see it and how it notifies people, click its name at the top and choose **Rename app** or **Manage app**.

## Related

> [card] [Content approval workflow](https://assembly.com/docs/apps/content-approval-workflow.md)
>
> Send work to clients for sign-off, with a full status history

> [card] [Design proofing tool](https://assembly.com/docs/apps/design-proofing-tool.md)
>
> Compare visual options side by side and pick a direction

[View this template on assembly.com](https://assembly.com/templates/markup-comments)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.