Direct Messages & Group Chats

Direct messages and group chats are Chat rows — the same type that already backed workspace chat threads — distinguished by kind: CHANNEL for a workspace chat, DM for a 1:1, GROUP for a named multi-person conversation. A DM/group Chat has project: null (it has no workspace anchor) and carries a members: [ChatMember!]! list that a CHANNEL chat does not use. Replies in any of the three are posted the same way — as Comment rows with category: DISCUSSION — see Create, edit & delete comments.

messageableUsers

Before starting a conversation, use messageableUsers to find who you’re allowed to message. Organization OWNER/ADMIN can message anyone in the organization; everyone else can message organization OWNER/ADMINs plus anyone they share at least one active workspace with. The same rule is enforced server-side on startDirectMessage, createGroupChat, and addGroupChatMembers — this query only lists it.

Request

query WhoCanIMessage {
  messageableUsers(query: "pri", first: 25) {
    id
    fullName
    email
  }
}

Parameters

Response

{
  "data": {
    "messageableUsers": [
      { "id": "clm4n8qwx000108l0a1b2c3d4", "fullName": "Priya Shah", "email": "priya@example.com" }
    ]
  }
}

messageableUsers returns [User!]! and never includes yourself.

startDirectMessage

Open (or return) the canonical 1:1 conversation with another user. Calling it again for the same pair of users returns the same Chat rather than creating a duplicate — DMs are deduplicated per organization, keyed by the two user IDs regardless of who calls first.

Request

mutation MessagePriya {
  startDirectMessage(userId: "user_456") {
    id
    kind
    members {
      user {
        id
        fullName
      }
      role
    }
  }
}

Parameters

Response

{
  "data": {
    "startDirectMessage": {
      "id": "clm4n8qwx000308l0i9j0k1l2",
      "kind": "DM",
      "members": [
        { "user": { "id": "clm4n8qwx000108l0h2pyerm8", "fullName": "You" }, "role": "MEMBER" },
        {
          "user": { "id": "clm4n8qwx000108l0a1b2c3d4", "fullName": "Priya Shah" },
          "role": "MEMBER"
        }
      ]
    }
  }
}

Returns

Returns the Chat — either newly created or the existing DM between you and userId in this organization.

Errors

createGroupChat

Create a named (or unnamed) group conversation. You become its first admin automatically.

Request

mutation StartLaunchCrew {
  createGroupChat(input: { title: "Launch crew", userIds: ["user_456", "user_789"] }) {
    id
    kind
    title
    members {
      user {
        id
        fullName
      }
      role
    }
  }
}

Parameters

CreateGroupChatInput

Response

{
  "data": {
    "createGroupChat": {
      "id": "clm4n8qwx000408l0m3n4o5p6",
      "kind": "GROUP",
      "title": "Launch crew",
      "members": [
        { "user": { "id": "clm4n8qwx000108l0h2pyerm8", "fullName": "You" }, "role": "ADMIN" },
        {
          "user": { "id": "clm4n8qwx000108l0a1b2c3d4", "fullName": "Priya Shah" },
          "role": "MEMBER"
        },
        {
          "user": { "id": "clm4n8qwx000508l0mtu2ivpc", "fullName": "Sarah Mensah" },
          "role": "MEMBER"
        }
      ]
    }
  }
}

Returns

Returns the created Chat with kind: GROUP.

Errors

addGroupChatMembers

Add people to an existing group. Admin-only. A person re-added after being removed regains access to the entire message history, exactly like a brand-new member — their role also resets to MEMBER, even if they were an admin before being removed.

Request

mutation AddToLaunchCrew {
  addGroupChatMembers(input: { discussionId: "chat_123", userIds: ["user_999"] }) {
    id
    members {
      user {
        id
        fullName
      }
      role
      removedAt
    }
  }
}

Parameters

GroupChatMembersInput

Response

{
  "data": {
    "addGroupChatMembers": {
      "id": "clm4n8qwx000408l0m3n4o5p6",
      "members": [
        {
          "user": { "id": "clm4n8qwx000608l0u1v2w3x4", "fullName": "New Person" },
          "role": "MEMBER",
          "removedAt": null
        }
      ]
    }
  }
}

Returns

Returns the updated Chat.

Errors

removeGroupChatMember

Remove someone from a group. Admin-only, and the row is soft-removed rather than deleted — the removed member keeps read-only access to everything up to the moment they were removed, but nothing after.

Request

mutation RemoveFromLaunchCrew {
  removeGroupChatMember(input: { discussionId: "chat_123", userId: "user_999" }) {
    id
    members {
      user {
        id
      }
      removedAt
    }
  }
}

Parameters

GroupChatMemberInput

To remove yourself, use leaveGroupChat instead — passing your own userId here is rejected.

Response

{
  "data": {
    "removeGroupChatMember": {
      "id": "clm4n8qwx000408l0m3n4o5p6",
      "members": [
        { "user": { "id": "clm4n8qwx000608l0u1v2w3x4" }, "removedAt": "2026-07-15T10:02:00.000Z" }
      ]
    }
  }
}

Returns

Returns the updated Chat.

Errors

leaveGroupChat

Leave a group chat you’re a member of. Only group chats can be left — passing a DM’s discussionId is rejected, which is what makes DMs permanent for as long as both people remain in the organization.

If you’re the last active admin, the longest-standing remaining member (by when they joined this conversation) is automatically promoted to admin. If you’re the last member of any role, the conversation is deleted entirely.

Request

mutation LeaveLaunchCrew {
  leaveGroupChat(discussionId: "chat_123")
}

Parameters

leaveGroupChat returns a bare Boolean!.

Response

{
  "data": {
    "leaveGroupChat": true
  }
}

Errors

setGroupChatMemberRole

Promote a member to admin, or demote an admin to member. Admin-only.

Request

mutation PromoteToAdmin {
  setGroupChatMemberRole(input: { discussionId: "chat_123", userId: "user_456", role: ADMIN }) {
    id
    members {
      user {
        id
      }
      role
    }
  }
}

Parameters

SetGroupChatMemberRoleInput

Setting a member’s role to the role they already have is a no-op — it returns the unchanged Chat rather than erroring.

Response

{
  "data": {
    "setGroupChatMemberRole": {
      "id": "clm4n8qwx000408l0m3n4o5p6",
      "members": [{ "user": { "id": "clm4n8qwx000108l0a1b2c3d4" }, "role": "ADMIN" }]
    }
  }
}

Returns

Returns the updated Chat.

Errors

The Chat type

The fields relevant to DMs and group chats. Chat also backs workspace chat threads (kind: CHANNEL) — see Create, update & delete chats for that surface’s full field list.

ChatKind

enum ChatKind {
  CHANNEL
  DM
  GROUP
}

ChatMember

enum ChatMemberRole {
  ADMIN
  MEMBER
}

Permissions

An organization can disable direct messaging entirely; when disabled, startDirectMessage, createGroupChat, and addGroupChatMembers all reject with FORBIDDEN.

Related

• Inbox & Messaging overview — how DM/group threads surface in the unified Inbox (DM_THREAD).
• Query your Inbox — read the conversations these mutations create.
• Manage inbox threads — mute, pin, and mark read/unread.
• Comments overview — post replies with createComment(category: DISCUSSION, ...).
• Query chats — the read paths shared with workspace chat threads.
• Inbox subscriptions — stream new activity in real time.