GraphQL: roadmap, status and chat

Client operations for the public roadmap, the status page and the visitor chat attached to notifications and surveys.

Roadmap

The roadmap queries are read-only. There is no mutation that lets visitors vote or react on roadmap items.

query {
  client_getRoadMap(id: "ROADMAP_ID") {
    id
    name
    description
    state
    columns
    items
    tags
    appearance
  }
}

query {
  client_getRoadMaps {
    id
    name
    state
  }
}

columns, items, tags and appearance are JSON. Items carry a title, description, columnId, tagIds, status (planned, in_progress, done, blocked), priority (low, medium, high), owner, due date and link. Subscriptions: client_roadMapUpdated and client_roadMapDeleted.

Status page

query {
  client_getStatusPage {
    name
    description
    enabled
    overallStatus
    components
    componentGroups
    componentUptime
    activeIncidents { id kind name status impact updates }
    upcomingMaintenance { id name scheduledFor scheduledUntil }
    incidentHistory { id kind name status resolvedAt }
    publicUrl
  }
}

mutation {
  client_subscribeStatusPage(email: "visitor@example.com") {
    ok
    email
  }
}

Enum	Values
StatusComponentStatus	operational, degraded_performance, partial_outage, major_outage, under_maintenance
StatusIncidentKind	incident, maintenance
StatusIncidentStatus	investigating, identified, monitoring, resolved, scheduled, in_progress, completed
StatusIncidentImpact	none, minor, major, critical

Uptime comes from incidents

The uptime strip (90 days, in UTC days) is computed from the incidents and maintenance recorded in Hubbo. It does not come from an external monitor. A day counts as down if an incident or maintenance affecting the component overlapped it. Optional Health monitors configured in the admin app can open and resolve incidents automatically; their URLs must be public (localhost, private ranges, link-local and cloud metadata addresses are rejected).

Chat (Messages)

Visitors can start a conversation attached to a notification or a survey. Those conversations arrive in Messages in the admin app. The context type is notification or survey.

createChat returns a short-lived guestToken (HMAC, about 24 hours) and may set an httpOnly hubbo_chat_* cookie. Further guest reads, messages and the client_messageCreated subscription require that token (GraphQL argument, Hubbo-Chat-Token header, or cookie). Knowing only the chat id is not enough. On the public notification page the UI is ephemeral: refreshing starts a new conversation.

mutation {
  createChat(contextType: notification, contextId: "NOTIFICATION_ID", email: "visitor@example.com", name: "Alex") {
    id
    authorId
    guestToken
  }
}

mutation {
  createMessage(chatId: "CHAT_ID", message: "Hello", type: text, guestToken: "GUEST_TOKEN") {
    id
    message
  }
}

query {
  client_getChatByIdAndAuthor(id: "CHAT_ID", authorId: "AUTHOR_ID", guestToken: "GUEST_TOKEN") {
    id
    contextType
    contextId
    messages { id message type read createdAt author { id name } }
  }
}

subscription {
  client_messageCreated(chatId: "CHAT_ID", guestToken: "GUEST_TOKEN") {
    message { id message createdAt author { name } }
  }
}

HTTP guest calls still need your account key (Hubbo-Project-Key or hubbo_api_key cookie). The guest subscription can authorize with the guest token alone when the WebSocket handshake has no project key. Staff replies use createMessage(..., inApp: true) from the signed-in admin app. See also Messages.

Not a general support API

The chat operations exist to power the widget and the notification page. There is no public support-ticket API, and no email or push notification is sent for new messages. Guest create/message endpoints are rate-limited.