Skip to main content

​
Overview

Admin Chat API provides administrative functions for managing customer conversations, transferring chats between stores and admin support, and monitoring chat system health. Location: convex/admins/chat.ts

​
Transfer Conversation to Store

Transfer an admin conversation to a specific store for direct customer support.
​
conversationId
Id<'conversations'>
required
ID of the conversation to transfer
​
storeId
Id<'stores'>
required
Target store ID to transfer to
​
orderId
Id<'orders'>
Optional order ID if conversation is about a specific order
​
includeHistory
boolean
required
Whether to copy message history to new conversation
const result = await convex.mutation(api.admins.chat.transferConversationToStore, {
  conversationId: "conv123456789",
  storeId: "store123456789", 
  orderId: "order123456789",
  includeHistory: true
});

{
  "newConversationId": "conv987654321"
}

​
Transfer Conversation to Admin

Transfer a store conversation back to admin support.
​
conversationId
Id<'conversations'>
required
ID of the conversation to transfer
​
reason
string
Optional reason for transfer
const result = await convex.mutation(api.admins.chat.transferConversationToAdmin, {
  conversationId: "conv123456789",
  reason: "Store unable to resolve issue"
});

{
  "newConversationId": "conv987654321"
}

​
Update Chat Settings

Update global chat system settings.
​
directMessagingEnabled
boolean
Enable/disable direct messaging between customers and stores
​
maxImageSizeMB
number
Maximum image size in MB for chat messages
​
allowedImageTypes
Array<string>
Allowed image MIME types
​
adminSupportEnabled
boolean
Enable/disable admin support chat
await convex.mutation(api.admins.chat.updateChatSettings, {
  directMessagingEnabled: true,
  maxImageSizeMB: 5,
  allowedImageTypes: ["image/jpeg", "image/png", "image/gif"],
  adminSupportEnabled: true
});

null

​
Get Admin Conversations

Retrieve admin conversations with customer and order information.
​
status
'active' | 'archived' | 'closed'
Filter by conversation status (default: “active”)
​
limit
number
Maximum number of conversations to return (default: 50)
const conversations = await convex.query(api.admins.chat.getAdminConversations, {
  status: "active",
  limit: 25
});

[
  {
    "_id": "conv123456789",
    "_creationTime": 1640995200000,
    "customerId": "cust123456789",
    "customerName": "John Doe",
    "orderId": "order123456789",
    "orderSummary": {
      "_id": "order123456789",
      "totalAmount": 25.50,
      "status": "delivered",
      "orderDate": 1640995000000
    },
    "lastMessageAt": 1640995800000,
    "lastMessagePreview": "Thank you for your help!",
    "unreadCountRecipient": 0,
    "status": "active"
  }
]

​
Block Conversation

Block a conversation from receiving new messages.
​
conversationId
Id<'conversations'>
required
ID of the conversation to block
​
reason
string
Reason for blocking the conversation
await convex.mutation(api.admins.chat.blockConversation, {
  conversationId: "conv123456789",
  reason: "Inappropriate language"
});

null

​
Unblock Conversation

Unblock a previously blocked conversation.
​
conversationId
Id<'conversations'>
required
ID of the conversation to unblock
await convex.mutation(api.admins.chat.unblockConversation, {
  conversationId: "conv123456789"
});

null

​
Toggle Store Direct Messaging

Enable or disable direct messaging for a specific store.
​
storeId
Id<'stores'>
required
Store ID to update messaging settings for
​
enabled
boolean
required
Whether to enable direct messaging
await convex.mutation(api.admins.chat.toggleStoreDirectMessaging, {
  storeId: "store123456789",
  enabled: true
});

null

​
Get Store Messaging Status

Check the messaging status for a specific store.
​
storeId
Id<'stores'>
required
Store ID to check status for
const status = await convex.query(api.admins.chat.getStoreMessagingStatus, {
  storeId: "store123456789"
});

{
  "storeId": "store123456789",
  "storeName": "Pizza Palace",
  "directMessagingEnabled": true,
  "globalDirectMessagingEnabled": true,
  "effectivelyEnabled": true
}

​
Get Chat Statistics

Retrieve comprehensive chat system statistics.
​
startDate
number
Start date filter (Unix timestamp)
​
endDate
number
End date filter (Unix timestamp)
const stats = await convex.query(api.admins.chat.getChatStats, {
  startDate: Date.now() - (7 * 24 * 60 * 60 * 1000), // Last 7 days
  endDate: Date.now()
});

{
  "totalConversations": 1250,
  "activeConversations": 45,
  "archivedConversations": 1180,
  "customerToAdminConversations": 890,
  "customerToStoreConversations": 360,
  "totalMessages": 15680,
  "blockedConversations": 12
}

​
Get Eligible Stores for Transfer

Get stores that a customer has orders with, eligible for conversation transfer.
​
customerId
Id<'customers'>
required
Customer ID to check eligible stores for
const eligibleStores = await convex.query(api.admins.chat.getEligibleStoresForTransfer, {
  customerId: "cust123456789"
});

[
  {
    "storeId": "store123456789",
    "storeName": "Pizza Palace",
    "orderCount": 3,
    "orderIds": ["order123456789", "order987654321", "order456789123"]
  },
  {
    "storeId": "store987654321",
    "storeName": "Burger Joint",
    "orderCount": 1,
    "orderIds": ["order111222333"]
  }
]
All admin chat functions require admin authentication and will throw an error if called by non-admin users.
Conversation transfers create new conversations and archive the original ones. Message history can optionally be copied to the new conversation.