Agents

Page modes

• Team Members list
  • Url: /app/agents
  • Description: Displays all agents with role badges, current user badge, permission summary, and actions.
• Add Agent L2
  • Url: /app/agents?mode=create
  • Description: Isolated full-page form for creating a new team member.
• Edit Agent L2
  • Url: /app/agents?mode=edit&id=
  • Description: Isolated full-page form for editing existing team member details and permissions.

Permissions matrix

• canReplyPublic: send customer replies
• canAddPrivateNotes: add/remove internal notes
• canResolveTickets: resolve tickets and related lifecycle actions
• canAssignTickets: assign tickets and route ownership
• canManageMacros: create/edit/delete macros
• canManageKnowledgeBase: manage support terms and knowledge base route
• canManageAgents: access Agents and Settings pages

Defaults

Support agent defaults

• Can Reply Public: true
• Can Add Private Notes: true
• Can Resolve Tickets: true
• Can Assign Tickets: false
• Can Manage Macros: false
• Can Manage Knowledge Base: false
• Can Manage Agents: false

Manager defaults

• Can Reply Public: true
• Can Add Private Notes: true
• Can Resolve Tickets: true
• Can Assign Tickets: true
• Can Manage Macros: true
• Can Manage Knowledge Base: true
• Can Manage Agents: true

Guardrails

• Page access is blocked unless current agent has canManageAgents.
• Current user cannot delete their own agent profile.
• At least one manager must remain in store.
• When editing your own profile, canManageAgents is force-preserved true.
• Duplicate agent email in same shop is blocked.

Owner workflows

• Add a new support teammate
  • Steps:
    • Open Add Agent from team list.
    • Fill full name and email.
    • Choose role or apply default permission preset.
    • Submit to create profile.
• Grant temporary macro or assignment privileges
  • Steps:
    • Open Edit on the target agent.
    • Enable required permission checkboxes.
    • Click Update Agent.
    • Later revert permissions if needed.

Data persistence

• Storage: Agent table in Prisma

Keys

- shop + email unique

- role
- permission booleans

• Session bootstrap: getOrCreateAgentForSession auto-creates an agent profile from Shopify admin session if missing.

Common issues

• Cannot open Agents page
  • Cause: Current profile lacks canManageAgents.
  • Fix: A manager with agent-management rights must grant permission.
• Update blocked by self-manage error
  • Cause: Self-edit attempted to remove canManageAgents.
  • Fix: Keep manage-agents permission enabled for your own profile.
• Cannot remove manager
  • Cause: Store would end up with zero manager profiles.
  • Fix: Create/promote another manager first.