User Presence

Know who is online and keep organization membership in sync as it changes. This page covers four subscriptions: subscribeToUserPresence (a user coming online or going offline), subscribeToCompany (organization record changes), subscribeToCompanyPeopleList (the org’s member roster), and subscribeToInvitation (workspace invitations created or revoked). Organizations are Company objects in the API and workspaces are Project objects.

All four run over the same authenticated WebSocket as every other subscription — see Connect & Authenticate for the graphql-ws handshake and credentials. The endpoint is wss://api.blue.cc/graphql.

subscribeToUserPresence returns a bare User! (no payload wrapper), because presence is a status snapshot rather than an entity change-feed. subscribeToCompany and subscribeToInvitation return the standard payload ({ mutation, node, previousValues, updatedFields }) described on the Real-time overview, where mutation is a MutationType (CREATED, UPDATED, or DELETED).

subscribeToUserPresence

Streams online/offline transitions for the people you share an organization with. An event fires when a user comes online (their first WebSocket connection opens) or goes offline (their last connection closes). Read isOnline on the delivered User to tell which way the transition went.

Presence is wired directly to the WebSocket connection lifecycle. When a client completes the onConnect handshake the server runs handleUserConnect; when the socket closes it runs handleUserDisconnect. A user is “online” while they hold at least one open connection, so opening a second tab does not re-fire an online event and closing one of two tabs does not fire an offline event — only the first connect and the last disconnect publish. Presence keys carry a 5-minute TTL, so a connection that dies without a clean close is reaped shortly after.

This replaces the deprecated subscribeToNetworkStatus.

Request

subscription OnUserPresenceChanged {
  subscribeToUserPresence(filter: { companyId: "company_123" }) {
    id
    fullName
    email
    isOnline
    lastActiveAt
    image {
      medium
    }
  }
}

Omit filter to watch presence across every organization you belong to. Pass filter.companyId to narrow to one organization — you only receive events for users who are members of that organization alongside you.

Parameters

UserPresenceFilter

Response

Each event is a User. isOnline reflects the transition that triggered the event — true when the user just came online, false when they just went offline.

{
  "data": {
    "subscribeToUserPresence": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "fullName": "Ada Lovelace",
      "email": "[email protected]",
      "isOnline": true,
      "lastActiveAt": "2026-05-29T14:02:11.000Z",
      "image": {
        "medium": "https://cdn.blue.cc/avatars/clm4n8qwx000008l0g4oxdqn7.png"
      }
    }
  }
}

Returns: User

User exposes many more fields — select only what your presence UI needs. See User Management for the full type.

subscribeToCompany

Streams changes to the organization record itself — for example a rename, a plan or settings change, or other Company field edits. Returns the standard entity payload.

Request

subscription OnCompanyChanged {
  subscribeToCompany(filter: { companyId: "company_123" }) {
    mutation
    node {
      id
      name
      slug
    }
    updatedFields
    previousValues {
      name
    }
  }
}

Pass filter.companyId to watch a single organization. With no companyId, you receive change events for every organization you are a member of.

Parameters

CompanyFilter

CompanyFilterStatus

ACTIVE, CANCELED, EXPIRED, TRIALING, PAST_DUE, UNKNOWN.

Response

Each event is a CompanySubscriptionPayload.

{
  "data": {
    "subscribeToCompany": {
      "mutation": "UPDATED",
      "node": {
        "id": "clm4n8qwx000008l0g4oxdqn7",
        "name": "Acme, Inc.",
        "slug": "acme"
      },
      "updatedFields": ["name"],
      "previousValues": {
        "name": "Acme Co."
      }
    }
  }
}

CompanySubscriptionPayload

subscribeToCompanyPeopleList

Notifies a client when the organization’s member roster changes — someone added, removed, or having their role updated — so a “People” view can refresh. Scoped to a single organization by companyId.

Request

subscription OnCompanyPeopleListChanged {
  subscribeToCompanyPeopleList(companyId: "company_123") {
    mutation
    node {
      id
      fullName
      email
    }
  }
}

Parameters

UserSubscriptionPayload

subscribeToInvitation

Streams workspace invitations being created or revoked. Invitations are Invitation objects. There are two ways to use it:

• Watch one workspace — pass projectId to receive every invitation created or deleted for that workspace (an admin view of pending invites).
• Watch your own invitations — omit projectId to receive only invitations addressed to your email, so a logged-in user is notified the moment they’re invited somewhere (matched on node.email for CREATED and previousValues.email for DELETED).

Request

subscription OnInvitationChanged {
  subscribeToInvitation(projectId: "project_123") {
    mutation
    node {
      id
      email
      accessLevel
      invitedBy {
        fullName
      }
      project {
        id
        name
      }
      expiredAt
    }
    previousValues {
      email
    }
  }
}

Parameters

Response

Each event is an InvitationSubscriptionPayload. On a CREATED event node carries the new invitation; on DELETED (the invite was revoked or accepted) inspect previousValues.

{
  "data": {
    "subscribeToInvitation": {
      "mutation": "CREATED",
      "node": {
        "id": "clm4n8qwx000008l0g4oxdqn7",
        "email": "[email protected]",
        "accessLevel": "MEMBER",
        "invitedBy": {
          "fullName": "Ada Lovelace"
        },
        "project": {
          "id": "clm4n8qwx000108l0h2pyerm8",
          "name": "Q3 Roadmap"
        },
        "expiredAt": "2026-06-05T14:02:11.000Z"
      },
      "previousValues": null
    }
  }
}

InvitationSubscriptionPayload

Invitation

Errors

Subscriptions report invalid arguments and missing scopes when the operation is set up; permission scoping is otherwise silent (see Permissions below).

Permissions

Events are filtered per delivered event, not just at connection time. Subscribing always succeeds for an authenticated client, but you only receive events you are allowed to see:

• subscribeToUserPresence delivers a presence event only for a user who shares an organization with you. With filter.companyId, the user must be a member of that organization (and so must you); without a filter, any shared organization qualifies.
• subscribeToCompany delivers an event only for an organization you belong to. With filter.companyId, the event must also match that organization.
• subscribeToInvitation with projectId delivers events for that workspace; without projectId it delivers only invitations addressed to your own email.

Related

• Real-time (Subscriptions) — the shared payload shape and the full subscription catalog.
• Connect & Authenticate — open an authenticated WebSocket.
• Project & Workspace Subscriptions — membership, roles, and workspace lifecycle streams.
• User Management — invite and remove members, list the people in an organization.