> ## Documentation Index
> Fetch the complete documentation index at: https://twigz.arqqin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin Chat

> Administrative chat management and conversation transfer functions

## 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.

<ParamField path="conversationId" type="Id<'conversations'>" required>
  ID of the conversation to transfer
</ParamField>

<ParamField path="storeId" type="Id<'stores'>" required>
  Target store ID to transfer to
</ParamField>

<ParamField path="orderId" type="Id<'orders'>">
  Optional order ID if conversation is about a specific order
</ParamField>

<ParamField path="includeHistory" type="boolean" required>
  Whether to copy message history to new conversation
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await convex.mutation(api.admins.chat.transferConversationToStore, {
    conversationId: "conv123456789",
    storeId: "store123456789", 
    orderId: "order123456789",
    includeHistory: true
  });
  ```

  ```javascript JavaScript theme={null}
  const result = await convex.mutation("admins.chat.transferConversationToStore", {
    conversationId: "conv123456789",
    storeId: "store123456789",
    orderId: "order123456789", 
    includeHistory: true
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "newConversationId": "conv987654321"
  }
  ```
</ResponseExample>

## Transfer Conversation to Admin

Transfer a store conversation back to admin support.

<ParamField path="conversationId" type="Id<'conversations'>" required>
  ID of the conversation to transfer
</ParamField>

<ParamField path="reason" type="string">
  Optional reason for transfer
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await convex.mutation(api.admins.chat.transferConversationToAdmin, {
    conversationId: "conv123456789",
    reason: "Store unable to resolve issue"
  });
  ```

  ```javascript JavaScript theme={null}
  const result = await convex.mutation("admins.chat.transferConversationToAdmin", {
    conversationId: "conv123456789",
    reason: "Store unable to resolve issue"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "newConversationId": "conv987654321"
  }
  ```
</ResponseExample>

## Update Chat Settings

Update global chat system settings.

<ParamField path="directMessagingEnabled" type="boolean">
  Enable/disable direct messaging between customers and stores
</ParamField>

<ParamField path="maxImageSizeMB" type="number">
  Maximum image size in MB for chat messages
</ParamField>

<ParamField path="allowedImageTypes" type="Array<string>">
  Allowed image MIME types
</ParamField>

<ParamField path="adminSupportEnabled" type="boolean">
  Enable/disable admin support chat
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  await convex.mutation(api.admins.chat.updateChatSettings, {
    directMessagingEnabled: true,
    maxImageSizeMB: 5,
    allowedImageTypes: ["image/jpeg", "image/png", "image/gif"],
    adminSupportEnabled: true
  });
  ```

  ```javascript JavaScript theme={null}
  await convex.mutation("admins.chat.updateChatSettings", {
    directMessagingEnabled: true,
    maxImageSizeMB: 5,
    allowedImageTypes: ["image/jpeg", "image/png", "image/gif"],
    adminSupportEnabled: true
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  null
  ```
</ResponseExample>

## Get Admin Conversations

Retrieve admin conversations with customer and order information.

<ParamField path="status" type="'active' | 'archived' | 'closed'">
  Filter by conversation status (default: "active")
</ParamField>

<ParamField path="limit" type="number">
  Maximum number of conversations to return (default: 50)
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const conversations = await convex.query(api.admins.chat.getAdminConversations, {
    status: "active",
    limit: 25
  });
  ```

  ```javascript JavaScript theme={null}
  const conversations = await convex.query("admins.chat.getAdminConversations", {
    status: "active",
    limit: 25
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "_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"
    }
  ]
  ```
</ResponseExample>

## Block Conversation

Block a conversation from receiving new messages.

<ParamField path="conversationId" type="Id<'conversations'>" required>
  ID of the conversation to block
</ParamField>

<ParamField path="reason" type="string">
  Reason for blocking the conversation
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  await convex.mutation(api.admins.chat.blockConversation, {
    conversationId: "conv123456789",
    reason: "Inappropriate language"
  });
  ```

  ```javascript JavaScript theme={null}
  await convex.mutation("admins.chat.blockConversation", {
    conversationId: "conv123456789",
    reason: "Inappropriate language"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  null
  ```
</ResponseExample>

## Unblock Conversation

Unblock a previously blocked conversation.

<ParamField path="conversationId" type="Id<'conversations'>" required>
  ID of the conversation to unblock
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  await convex.mutation(api.admins.chat.unblockConversation, {
    conversationId: "conv123456789"
  });
  ```

  ```javascript JavaScript theme={null}
  await convex.mutation("admins.chat.unblockConversation", {
    conversationId: "conv123456789"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  null
  ```
</ResponseExample>

## Toggle Store Direct Messaging

Enable or disable direct messaging for a specific store.

<ParamField path="storeId" type="Id<'stores'>" required>
  Store ID to update messaging settings for
</ParamField>

<ParamField path="enabled" type="boolean" required>
  Whether to enable direct messaging
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  await convex.mutation(api.admins.chat.toggleStoreDirectMessaging, {
    storeId: "store123456789",
    enabled: true
  });
  ```

  ```javascript JavaScript theme={null}
  await convex.mutation("admins.chat.toggleStoreDirectMessaging", {
    storeId: "store123456789",
    enabled: true
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  null
  ```
</ResponseExample>

## Get Store Messaging Status

Check the messaging status for a specific store.

<ParamField path="storeId" type="Id<'stores'>" required>
  Store ID to check status for
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const status = await convex.query(api.admins.chat.getStoreMessagingStatus, {
    storeId: "store123456789"
  });
  ```

  ```javascript JavaScript theme={null}
  const status = await convex.query("admins.chat.getStoreMessagingStatus", {
    storeId: "store123456789"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "storeId": "store123456789",
    "storeName": "Pizza Palace",
    "directMessagingEnabled": true,
    "globalDirectMessagingEnabled": true,
    "effectivelyEnabled": true
  }
  ```
</ResponseExample>

## Get Chat Statistics

Retrieve comprehensive chat system statistics.

<ParamField path="startDate" type="number">
  Start date filter (Unix timestamp)
</ParamField>

<ParamField path="endDate" type="number">
  End date filter (Unix timestamp)
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const stats = await convex.query(api.admins.chat.getChatStats, {
    startDate: Date.now() - (7 * 24 * 60 * 60 * 1000), // Last 7 days
    endDate: Date.now()
  });
  ```

  ```javascript JavaScript theme={null}
  const stats = await convex.query("admins.chat.getChatStats", {
    startDate: Date.now() - (7 * 24 * 60 * 60 * 1000), // Last 7 days
    endDate: Date.now()
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  {
    "totalConversations": 1250,
    "activeConversations": 45,
    "archivedConversations": 1180,
    "customerToAdminConversations": 890,
    "customerToStoreConversations": 360,
    "totalMessages": 15680,
    "blockedConversations": 12
  }
  ```
</ResponseExample>

## Get Eligible Stores for Transfer

Get stores that a customer has orders with, eligible for conversation transfer.

<ParamField path="customerId" type="Id<'customers'>" required>
  Customer ID to check eligible stores for
</ParamField>

<CodeGroup>
  ```typescript TypeScript theme={null}
  const eligibleStores = await convex.query(api.admins.chat.getEligibleStoresForTransfer, {
    customerId: "cust123456789"
  });
  ```

  ```javascript JavaScript theme={null}
  const eligibleStores = await convex.query("admins.chat.getEligibleStoresForTransfer", {
    customerId: "cust123456789"
  });
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={null}
  [
    {
      "storeId": "store123456789",
      "storeName": "Pizza Palace",
      "orderCount": 3,
      "orderIds": ["order123456789", "order987654321", "order456789123"]
    },
    {
      "storeId": "store987654321",
      "storeName": "Burger Joint",
      "orderCount": 1,
      "orderIds": ["order111222333"]
    }
  ]
  ```
</ResponseExample>

<Note>
  All admin chat functions require admin authentication and will throw an error if called by non-admin users.
</Note>

<Warning>
  Conversation transfers create new conversations and archive the original ones. Message history can optionally be copied to the new conversation.
</Warning>