Create, update & delete chats

A chat is a standalone, workspace-scoped conversation thread — a place for a topic that isn’t tied to a single record. Chats are Chat objects in the API, and they live in a workspace. Once a thread exists, replies are posted as comments with category: DISCUSSION (see Create, edit & delete comments).

• Use createChat to seed a new thread with a title and an opening body.
• Use updateChat to rename a thread — it edits the title only; the body is fixed once created.
• Use deleteChat to remove a thread. Unlike a comment delete, this is a hard delete.

To read chats back, use the chat query paths. The Chat.comments field is deprecated — load replies with commentList(category: DISCUSSION) instead.

Legacy names. Chat was called Discussion, and these three mutations were createDiscussion / updateDiscussion / deleteDiscussion. Every legacy name still works and returns identical data — it is marked @deprecated in introspection and points at its modern replacement. CommentCategory.DISCUSSION is not renamed: it is a stored enum value on millions of comment rows.

createChat

Create a chat in a workspace. The opening message is supplied as both html (rich content, sanitized server-side) and text (the plain-text fallback). The mutation returns the created Chat.

Request

mutation CreateChat {
  createChat(
    input: {
      projectId: "workspace_123"
      title: "Q3 launch retro"
      html: "<p>What went well, what didn't?</p>"
      text: "What went well, what didn't?"
    }
  ) {
    id
    title
    html
    text
    createdAt
    user {
      id
      fullName
    }
    project {
      id
      name
    }
  }
}

Parameters

CreateChatInput

The body (html / text) is set once at creation and is immutable afterward — updateChat changes only the title. To revise the opening message, delete the thread and create a new one, or post a follow-up comment.

Response

{
  "data": {
    "createChat": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "title": "Q3 launch retro",
      "html": "<p>What went well, what didn't?</p>",
      "text": "What went well, what didn't?",
      "createdAt": "2026-05-29T14:02:11.000Z",
      "user": {
        "id": "clm4n8a1b000108l0c2d3e4f5",
        "fullName": "Dana Rao"
      },
      "project": {
        "id": "clm4n7zzz000008l0a1b2c3d4",
        "name": "Marketing"
      }
    }
  }
}

Returns

Returns the created Chat.

Mentions, images & attachments

@mentions, inline images, and file attachments all travel inside the html field of the opening message — there are no separate arguments for them. To mention a user, include an anchor whose href is #view-profile-<userId>; the server rewrites it into a mention and notifies that user. The same convention applies when posting comment replies (see Create, edit & delete comments).

Errors

updateChat

Rename a chat. This is the only mutable field: UpdateChatInput carries just id and an optional title. The mutation returns the updated Chat.

Request

mutation UpdateChat {
  updateChat(input: { id: "chat_123", title: "Q3 launch retro (final)" }) {
    id
    title
    updatedAt
  }
}

Parameters

UpdateChatInput

There is no editChat mutation, and there is no way to change html / text, projectId, or any other field through this call — only the title.

Response

{
  "data": {
    "updateChat": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "title": "Q3 launch retro (final)",
      "updatedAt": "2026-05-29T15:18:44.000Z"
    }
  }
}

Returns

Returns the updated Chat.

Errors

deleteChat

Remove a chat thread. This is a hard delete: before the row is removed, its reply chains are unlinked (threaded comment replies have their parentId cleared to release the foreign-key constraint), and a snapshot of the chat is written to the organization’s Trash. The mutation returns a MutationResult.

This differs from deleteComment, which is a soft delete that keeps the row and blanks its body — see Create, edit & delete comments.

Request

deleteChat takes the chat id directly (not an input object) and returns a MutationResult.

mutation DeleteChat {
  deleteChat(id: "chat_123") {
    success
    operationId
  }
}

Parameters

Response

{
  "data": {
    "deleteChat": {
      "success": true,
      "operationId": "clm4n8qwx000008l0g4oxdqn7"
    }
  }
}

Returns

Errors

Chat type

The fields available on a Chat. The comment thread itself is loaded separately via commentList(category: DISCUSSION) — the Chat.comments field is deprecated and should not be used.

Permissions

All three mutations require the caller to be a member of the chat’s workspace, and they deny VIEW_ONLY and COMMENT_ONLY access levels. The workspace must be active (not archived).

Related

• Comments overview — the Comment type, CommentCategory, threading, and read state.
• Query chats — fetch a single thread, list threads, or page through a workspace’s threads.
• Create, edit & delete comments — post the replies that hang off a chat.
• Query comments — load a chat’s replies with commentList.
• Comment & chat subscriptions — stream chat and comment changes in real time.
• Direct Messages & Group Chats — startDirectMessage/createGroupChat create the other two Chat kinds (DM/GROUP), started differently from the createChat flow on this page.