GraphQL schema

POST /api/chat/graphql — the dashboard’s real-time API surface. JWT-authenticated; the token comes from /api/auth/login.

Major root types

• Query — read everything (conversations, messages, contacts, flows, bookings, …)
• Mutation — write everything (send message, archive contact, publish flow, …)
• Subscription — real-time push (new message, presence, conversation update)

Auth

Every request must include Authorization: Bearer [jwt]. The JWT carries:

• userId
• agencyId
• clientId — null for AGENCY_*; populated for CLIENT_USER
• role

Resolvers enforce role + permission + tenant scoping. CLIENT_USER queries are auto-filtered to clientId = JWT.clientId; mismatched ids are silently dropped.

Tenant scoping cheat sheet

Common queries

# Active conversations
query Inbox($tab: ConversationTab!) {
  conversations(tab: $tab, limit: 50) {
    id customerExternalId customerDisplayName lastMessageAt status assigneeId
    unreadCount channel { id provider displayName }
  }
}
 
# A conversation's messages
query Messages($conversationId: ID!, $beforeId: ID, $limit: Int) {
  messages(conversationId: $conversationId, beforeId: $beforeId, limit: $limit) {
    id direction messageType body createdAt status
    interactive { type ... }
    mediaId mediaMimeType
  }
}
 
# Send a text reply
mutation SendText($conversationId: ID!, $body: String!) {
  sendText(conversationId: $conversationId, body: $body) { id status }
}
 
# Start a flow on a conversation
mutation StartFlow($conversationId: ID!, $flowId: ID!) {
  startFlowForConversation(conversationId: $conversationId, flowId: $flowId)
}

Subscriptions

Server pushes via WebSocket. Connect → subscribe to topic:

• new_message:[conversation_id]
• conversation_updated:[agency_id]
• agent_presence:[agency_id]

The frontend bundles these subscriptions into its real-time hook.

Schema introspection

Tooling target: Apollo Studio, GraphiQL, or the interactive IDE at /api/chat/graphiql (dev only).