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.

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

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.

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

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.

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

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.

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

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.

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

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

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

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

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.

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

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.

customerId

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