TWIGZ Backend API Documentation

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.

Id<'conversations'>

required

ID of the conversation to transfer

Id<'stores'>

required

Target store ID to transfer to

Id<'orders'>

Optional order ID if conversation is about a specific order

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
});

const result = await convex.mutation("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.

Id<'conversations'>

required

ID of the conversation to transfer

string

Optional reason for transfer

const result = await convex.mutation(api.admins.chat.transferConversationToAdmin, {
  conversationId: "conv123456789",
  reason: "Store unable to resolve issue"
});

const result = await convex.mutation("admins.chat.transferConversationToAdmin", {
  conversationId: "conv123456789",
  reason: "Store unable to resolve issue"
});

{
  "newConversationId": "conv987654321"
}

Update Chat Settings

Update global chat system settings.

boolean

Enable/disable direct messaging between customers and stores

number

Maximum image size in MB for chat messages

Array<string>

Allowed image MIME types

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
});

await convex.mutation("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.

'active' | 'archived' | 'closed'

Filter by conversation status (default: “active”)

number

Maximum number of conversations to return (default: 50)

const conversations = await convex.query(api.admins.chat.getAdminConversations, {
  status: "active",
  limit: 25
});

const conversations = await convex.query("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.

Id<'conversations'>

required

ID of the conversation to block

string

Reason for blocking the conversation

await convex.mutation(api.admins.chat.blockConversation, {
  conversationId: "conv123456789",
  reason: "Inappropriate language"
});

await convex.mutation("admins.chat.blockConversation", {
  conversationId: "conv123456789",
  reason: "Inappropriate language"
});

null

Unblock Conversation

Unblock a previously blocked conversation.

Id<'conversations'>

required

ID of the conversation to unblock

await convex.mutation(api.admins.chat.unblockConversation, {
  conversationId: "conv123456789"
});

await convex.mutation("admins.chat.unblockConversation", {
  conversationId: "conv123456789"
});

null

Toggle Store Direct Messaging

Enable or disable direct messaging for a specific store.

Id<'stores'>

required

Store ID to update messaging settings for

boolean

required

Whether to enable direct messaging

await convex.mutation(api.admins.chat.toggleStoreDirectMessaging, {
  storeId: "store123456789",
  enabled: true
});

await convex.mutation("admins.chat.toggleStoreDirectMessaging", {
  storeId: "store123456789",
  enabled: true
});

null

Get Store Messaging Status

Check the messaging status for a specific store.

Id<'stores'>

required

Store ID to check status for

const status = await convex.query(api.admins.chat.getStoreMessagingStatus, {
  storeId: "store123456789"
});

const status = await convex.query("admins.chat.getStoreMessagingStatus", {
  storeId: "store123456789"
});

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

Get Chat Statistics

Retrieve comprehensive chat system statistics.

number

Start date filter (Unix timestamp)

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()
});

const stats = await convex.query("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.

Id<'customers'>

required

Customer ID to check eligible stores for

const eligibleStores = await convex.query(api.admins.chat.getEligibleStoresForTransfer, {
  customerId: "cust123456789"
});

const eligibleStores = await convex.query("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.

Shared Functions

Store Management

Customer Experience

Admin & Platform

HTTP Endpoints

Scheduled Tasks

Database

Development

Admin Chat

Overview

Transfer Conversation to Store

Transfer Conversation to Admin

Update Chat Settings

Get Admin Conversations

Block Conversation

Unblock Conversation

Toggle Store Direct Messaging

Get Store Messaging Status

Get Chat Statistics

Get Eligible Stores for Transfer

​Overview

​Transfer Conversation to Store

​Transfer Conversation to Admin

​Update Chat Settings

​Get Admin Conversations

​Block Conversation

​Unblock Conversation

​Toggle Store Direct Messaging

​Get Store Messaging Status

​Get Chat Statistics

​Get Eligible Stores for Transfer

Overview

Transfer Conversation to Store

Transfer Conversation to Admin

Update Chat Settings

Get Admin Conversations

Block Conversation

Unblock Conversation

Toggle Store Direct Messaging

Get Store Messaging Status

Get Chat Statistics

Get Eligible Stores for Transfer