What the ClickUp integration does

Every new comment on a project you route to ClickUp becomes a task in the List you choose, with the screenshot, the page and the browser details in its description. Status syncs both ways: move the task in ClickUp and the comment follows, change the comment in Huddlekit and the task catches up. For an overview, see the ClickUp integration page.

Before you start

Plan — ClickUp is on the Team plan. See Understanding plans and pricing.
Role — only workspace owners and admins can connect ClickUp or change its settings. Other members can open Integrations and see that ClickUp is connected, but can't change anything.
ClickUp access — the ClickUp account you connect with needs permission to create tasks in every List you plan to use.

Connect ClickUp

Open Integrations in your workspace sidebar.
Under Apps, click Connect on the ClickUp row.
ClickUp asks which of your ClickUp Workspaces to authorize. Tick the one that holds your Lists and approve.
You land back on Integrations with the message ClickUp connected: "Nothing syncs until you choose a List for your projects."

Nothing is sent yet. Huddlekit doesn't guess a List for you, so the ClickUp row shows Not configured until you choose one.

Choose where each project's tasks go

Open the ⋯ menu on the ClickUp row and choose Configure. Changes save as you make them, so Done just closes the dialog.

Default List — where comments go from every project you don't set individually, including projects created later. Choose No default if only the projects you set should sync.
Projects — one row for each website, web app and media project. Leave a row on Default to follow the default List, pick a List of its own, or choose Don't sync to keep that project out of ClickUp even when a default is set.

Lists are grouped by Space and Folder, as they are in ClickUp's sidebar. If you authorized more than one ClickUp Workspace, a ClickUp Workspace picker appears at the top. Every List has to be in the same ClickUp Workspace so status changes can come back, so you can only switch Workspaces while no project or default points at a List.

Changing a project's List only affects new comments. Tasks that already exist stay where they are and keep their status in sync, even if you later set their project to Don't sync or remove the default. To stop existing tasks syncing, disconnect.

Map statuses

Huddlekit has four statuses: Open, In review, In progress and Resolved. ClickUp statuses belong to each List, so every List has its own map. When you first choose a List, Huddlekit fills in its map from the List's statuses:

Statuses are matched by name first, then by ClickUp's status type.
In review is only filled in when the List has a status with a matching name, such as IN REVIEW.
A status named like a cancellation is never picked for Resolved: names like Cancelled, Won't fix, Duplicate, Rejected, Archived, Out of scope, Not a bug, Obsolete, Deferred or Postponed. That way, canceling a task doesn't tell a client their feedback is done.
Other finished statuses in the List also resolve the comment when a task moves to them, and other open statuses set it back to Open. Statuses added to the List later aren't included. Hover over the ⓘ next to a status to see them, for example "Also becomes Resolved when a task moves to Closed in ClickUp."

To change the map, click the gear next to the Default List or any project row. Each Huddlekit status gets one ClickUp status, or Never sync this status, which stops that status syncing in both directions, extra statuses included. It still counts as unmapped, so the warning stays. Several projects can share a List, and the dialog tells you when a change will apply to all of them. You can also point two Huddlekit statuses at the same ClickUp status. If you do, moving a task back to that status sets the comment to the earlier of the two in the order above.

A status with nothing mapped shows a warning next to every project it affects, and the row shows Status mapping incomplete. A comment moved to that status doesn't change its task, and a task moved to a ClickUp status nobody mapped doesn't change its comment.

If you rename or delete a status in ClickUp, its mapping stops working. It shows as unmapped as soon as you open Configure, and on the ClickUp row after that or after the next nightly check. Until you pick another, a comment moved to that status can't move its task, and the row can show Sync failing. Once the mapping is fixed, the next nightly check moves the task and leaves a comment on it explaining why, or a status change on the comment moves it straight away.

What each task includes

Name — the comment number and the first line of the comment, like #42 — Logo is blurry on mobile. When other projects can land in the same List, the project name goes in front: [Acme site] #42 — ….
Description — the full comment, the project, who reported it, where it was left, and the screenshot with a link to open it. Where it was left is a link to the page on a website, and the page number or video time on a media file. Media comments have no screenshot.
Environment — OS, browser, resolution, viewport, pixel ratio, color depth and network, whichever were captured. Website comments carry the most. Web app comments carry fewer, and media comments have none.
Open in Huddlekit — a link back to the comment.

Private comments are sent too, so think about who can see a List before routing a project to it. Each new comment waits about ten seconds so its screenshot can finish, then usually reaches ClickUp within a minute.

What stays in Huddlekit

Status is the only thing that syncs, and it's the only thing read back from ClickUp. The task description is written once, when the comment arrives, so later edits to the comment text aren't pushed. Replies, priority, tags, assignees and attachments stay in Huddlekit, and comments your team adds in ClickUp stay in ClickUp.

Comments aren't copied over later if they were left before you connected, before their project had a List, while it was set to Don't sync, or while syncing was paused. If one of them changes status later and its project syncs, it becomes a task then.

Deleting a task in ClickUp doesn't delete the comment. Its status just stops syncing.

One-way sync

If you'd rather keep changes made in ClickUp from coming back, open the ⋯ menu and choose Switch to one-way sync. The option appears once a project or the default has a List and two-way sync is running. Status changes in ClickUp then stay in ClickUp, including during the nightly check. Comments still become tasks and Huddlekit status changes still move them. Switch to two-way sync in the same menu turns it back on.

Nightly check

Once a night, Huddlekit compares linked tasks with their comments and fixes any status that drifted, for example after a missed update. If only the task moved, the comment follows it, unless the connection is set to one-way sync. If the comment changed since it last synced, Huddlekit's status wins, and a comment on the task explains why it was reset. The same check restarts two-way sync if ClickUp has paused it, and refreshes each List's statuses so a renamed one shows up on the row.

Disconnecting

Open the ⋯ menu and choose Disconnect. This works on any plan. Huddlekit stops sending comments, removes its webhook from your ClickUp Workspace and deletes its copy of the access token. Tasks already in ClickUp stay there.

ClickUp has no way for Huddlekit to revoke the authorization itself, so the Disconnected from ClickUp message stays until you close it and names the last step: "To finish, remove Huddlekit from your authorized apps in ClickUp settings."

If you connect again later and tick the same ClickUp Workspace, your Lists, project settings and status maps come back, and existing tasks keep syncing instead of being created twice. Ticking a different Workspace starts a fresh connection.

If your plan changes

Syncing only runs while the workspace is on the Team plan with its payments up to date. If the workspace moves to another plan, or a payment is past due, the ClickUp row shows Paused and nothing syncs in either direction. Comments left during that time aren't queued up to send later. Your settings are kept, and Disconnect stays available.

Once the workspace is back on Team, the nightly check repairs tasks that already exist. If a comment's status changed during the pause, its task is reset to match, with a comment explaining why. If only the task moved, the comment follows it, unless the connection is set to one-way sync.

Troubleshooting

If connecting doesn't finish, you're returned to Integrations with a ClickUp not connected message and the reason:

"No ClickUp Workspace was authorized. Tick one when ClickUp asks." Connect again and tick a Workspace on ClickUp's screen.
"Cancelled. Nothing changed." You cancelled on ClickUp's screen. Click Connect again when you're ready.
"That link expired. Start again." More than ten minutes passed on ClickUp's screen. Click Connect again.
"You switched accounts partway. Sign back in and retry." You were signed in to Huddlekit as someone else by the time you came back. Sign in as the admin who started, then connect again.
"That link was already used. Start again." or "That link was not valid. Start again." Click Connect again from Integrations.
"Only workspace admins can do this." or "Needs the Team plan." Ask an owner or admin, or upgrade the workspace first.
Anything ending in "Try again." Click Connect again.

Sync failing on the ClickUp row means a comment couldn't be sent to ClickUp and won't be retried. Open Configure from the ⋯ menu and hover over Sync failing at the top of the dialog for the reason, such as a status that no longer exists in the task's List, or "ClickUp no longer accepts Huddlekit. Reconnect ClickUp." It clears once a comment syncs to ClickUp again. The row shows one problem at a time, so open Configure to see all of them.

A List won't save. Huddlekit checks each List with ClickUp before saving it:

"Your ClickUp user cannot create tasks in that List. Pick another, or ask for edit access."
"That ClickUp Workspace is not authorized. Reconnect and tick it on ClickUp’s screen." Choose Reconnect in the ⋯ menu. ClickUp's consent screen is the only place to add a Workspace.
"ClickUp refused the connection. Reconnect ClickUp."

"The List … no longer exists in ClickUp" — the List was deleted or can no longer be reached. Point its projects at another List.

Two-way sync paused or Two-way sync not set up — status changes made in ClickUp aren't coming back. Choose Resume two-way sync in the ⋯ menu. If you see "ClickUp did not accept the webhook. Try again, or Reconnect in the ⋯ menu.", try Reconnect. Your Lists and maps are kept as long as you tick the same ClickUp Workspace.

Connecting ClickUp