@warriorteam/redai-zalo-sdk/dist/services/group-message.service.d.ts

Comprehensive TypeScript/JavaScript SDK for Zalo APIs - Official Account v3.0, ZNS with Full Type Safety, Consultation Service, Broadcast Service, Group Messaging with List APIs, Social APIs, Enhanced Article Management, Promotion Service v3.0 with Multip

import { ZaloClient } from "../clients/zalo-client";
import { GroupTextMessage, GroupImageMessage, GroupFileMessage, GroupStickerMessage, GroupMentionMessage, GroupMessageResult, GroupInfo, GroupMember } from "../types/group";
/**
 * Interface cho từng tin nhắn trong danh sách tin nhắn group
 */
export interface GroupMessageItem {
    /** Loại tin nhắn */
    type: "text" | "image" | "file" | "sticker" | "mention";
    /** Nội dung tin nhắn (cho text/mention message) */
    text?: string;
    /** URL hình ảnh (cho image message) */
    imageUrl?: string;
    /** Attachment ID (cho image message) */
    attachmentId?: string;
    /** Caption cho hình ảnh (tối đa 2000 ký tự) */
    caption?: string;
    /** Token file (cho file message) */
    fileToken?: string;
    /** Tên file (cho file message) */
    fileName?: string;
    /** Sticker ID (cho sticker message) */
    stickerId?: string;
    /** Danh sách mentions (cho mention message) */
    mentions?: Array<{
        user_id: string;
        offset: number;
        length: number;
    }>;
    /** Delay sau khi gửi tin nhắn này (milliseconds) */
    delay?: number;
}
/**
 * Interface cho request gửi danh sách tin nhắn tới 1 group
 */
export interface SendMessageListToGroupRequest {
    /** Access token của Official Account */
    accessToken: string;
    /** Group ID */
    groupId: string;
    /** Danh sách tin nhắn */
    messages: GroupMessageItem[];
    /** Delay mặc định giữa các tin nhắn (milliseconds) */
    defaultDelay?: number;
    /** Callback function để tracking tiến trình */
    onProgress?: (progress: GroupMessageProgressInfo) => void;
}
/**
 * Interface cho thông tin tiến trình từng tin nhắn
 */
export interface GroupMessageProgressInfo {
    /** Group ID */
    groupId: string;
    /** Index của tin nhắn trong danh sách (bắt đầu từ 0) */
    messageIndex: number;
    /** Tổng số tin nhắn */
    totalMessages: number;
    /** Loại tin nhắn */
    messageType: string;
    /** Trạng thái: 'started' | 'completed' | 'failed' */
    status: 'started' | 'completed' | 'failed';
    /** Kết quả gửi tin nhắn (nếu đã hoàn thành) */
    result?: GroupMessageResult;
    /** Thông tin lỗi (nếu thất bại) */
    error?: string;
    /** Thời gian bắt đầu */
    startTime: number;
    /** Thời gian kết thúc (nếu đã hoàn thành) */
    endTime?: number;
}
/**
 * Interface cho response gửi danh sách tin nhắn tới 1 group
 */
export interface SendMessageListToGroupResponse {
    /** Group ID */
    groupId: string;
    /** Tổng số tin nhắn */
    totalMessages: number;
    /** Số tin nhắn gửi thành công */
    successfulMessages: number;
    /** Số tin nhắn gửi thất bại */
    failedMessages: number;
    /** Chi tiết kết quả từng tin nhắn */
    messageResults: Array<{
        /** Index của tin nhắn trong danh sách */
        messageIndex: number;
        /** Loại tin nhắn */
        messageType: string;
        /** Trạng thái gửi */
        success: boolean;
        /** Kết quả chi tiết */
        result?: GroupMessageResult;
        /** Thông tin lỗi nếu thất bại */
        error?: string;
        /** Thời gian bắt đầu gửi */
        startTime: number;
        /** Thời gian kết thúc */
        endTime: number;
        /** Thời gian thực hiện (milliseconds) */
        duration: number;
    }>;
    /** Tổng thời gian thực hiện (milliseconds) */
    totalDuration: number;
}
/**
 * Interface cho request gửi danh sách tin nhắn tới nhiều groups
 */
export interface SendMessageListToMultipleGroupsRequest {
    /** Access token của Official Account */
    accessToken: string;
    /** Danh sách group IDs */
    groupIds: string[];
    /** Danh sách tin nhắn */
    messages: GroupMessageItem[];
    /** Delay mặc định giữa các tin nhắn (milliseconds) */
    defaultDelay?: number;
    /** Delay giữa các groups (milliseconds) để tránh rate limit */
    delayBetweenGroups?: number;
    /** Callback function để tracking tiến trình */
    onProgress?: (progress: MultipleGroupsProgressInfo) => void;
}
/**
 * Interface cho thông tin tiến trình từng group
 */
export interface MultipleGroupsProgressInfo {
    /** Group ID hiện tại */
    groupId: string;
    /** Index của group trong danh sách (bắt đầu từ 0) */
    groupIndex: number;
    /** Tổng số groups */
    totalGroups: number;
    /** Trạng thái: 'started' | 'completed' | 'failed' */
    status: 'started' | 'completed' | 'failed';
    /** Kết quả gửi tin nhắn cho group này (nếu đã hoàn thành) */
    result?: SendMessageListToGroupResponse;
    /** Thông tin lỗi (nếu thất bại) */
    error?: string;
    /** Thời gian bắt đầu */
    startTime: number;
    /** Thời gian kết thúc (nếu đã hoàn thành) */
    endTime?: number;
}
/**
 * Interface cho response gửi danh sách tin nhắn tới nhiều groups
 */
export interface SendMessageListToMultipleGroupsResponse {
    /** Tổng số groups */
    totalGroups: number;
    /** Số groups gửi thành công */
    successfulGroups: number;
    /** Số groups gửi thất bại */
    failedGroups: number;
    /** Chi tiết kết quả từng group */
    groupResults: Array<{
        /** Group ID */
        groupId: string;
        /** Index của group trong danh sách */
        groupIndex: number;
        /** Trạng thái gửi cho group này */
        success: boolean;
        /** Kết quả chi tiết gửi tin nhắn */
        messageListResult?: SendMessageListToGroupResponse;
        /** Thông tin lỗi nếu thất bại */
        error?: string;
        /** Thời gian bắt đầu gửi */
        startTime: number;
        /** Thời gian kết thúc */
        endTime: number;
        /** Thời gian thực hiện (milliseconds) */
        duration: number;
    }>;
    /** Tổng thời gian thực hiện (milliseconds) */
    totalDuration: number;
    /** Thống kê tin nhắn tổng cộng */
    messageStats: {
        /** Tổng số tin nhắn đã gửi thành công */
        totalSuccessfulMessages: number;
        /** Tổng số tin nhắn thất bại */
        totalFailedMessages: number;
        /** Tổng số tin nhắn */
        totalMessages: number;
    };
}
/**
 * Interface cho tin nhắn cá nhân hóa cho từng group
 */
export interface PersonalizedGroupMessage {
    /** Group ID */
    groupId: string;
    /** Danh sách tin nhắn riêng cho group này */
    messages: GroupMessageItem[];
}
/**
 * Interface cho request gửi tin nhắn cá nhân hóa tới nhiều groups
 */
export interface SendPersonalizedMessageToMultipleGroupsRequest {
    /** Access token của Official Account */
    accessToken: string;
    /** Danh sách tin nhắn cá nhân hóa cho từng group */
    personalizedMessages: PersonalizedGroupMessage[];
    /** Delay mặc định giữa các tin nhắn (milliseconds) */
    defaultDelay?: number;
    /** Delay giữa các groups (milliseconds) để tránh rate limit */
    delayBetweenGroups?: number;
    /** Callback function để tracking tiến trình */
    onProgress?: (progress: PersonalizedGroupsProgressInfo) => void;
}
/**
 * Interface cho thông tin tiến trình gửi tin nhắn cá nhân hóa
 */
export interface PersonalizedGroupsProgressInfo {
    /** Group ID hiện tại */
    groupId: string;
    /** Index của group trong danh sách (bắt đầu từ 0) */
    groupIndex: number;
    /** Tổng số groups */
    totalGroups: number;
    /** Trạng thái: 'started' | 'completed' | 'failed' */
    status: 'started' | 'completed' | 'failed';
    /** Kết quả gửi tin nhắn cho group này (nếu đã hoàn thành) */
    result?: SendMessageListToGroupResponse;
    /** Thông tin lỗi (nếu thất bại) */
    error?: string;
    /** Thời gian bắt đầu */
    startTime: number;
    /** Thời gian kết thúc (nếu đã hoàn thành) */
    endTime?: number;
}
/**
 * Interface cho response gửi tin nhắn cá nhân hóa tới nhiều groups
 */
export interface SendPersonalizedMessageToMultipleGroupsResponse {
    /** Tổng số groups */
    totalGroups: number;
    /** Số groups gửi thành công */
    successfulGroups: number;
    /** Số groups gửi thất bại */
    failedGroups: number;
    /** Chi tiết kết quả từng group */
    groupResults: Array<{
        /** Group ID */
        groupId: string;
        /** Index của group trong danh sách */
        groupIndex: number;
        /** Trạng thái gửi cho group này */
        success: boolean;
        /** Kết quả chi tiết gửi tin nhắn */
        messageListResult?: SendMessageListToGroupResponse;
        /** Thông tin lỗi nếu thất bại */
        error?: string;
        /** Thời gian bắt đầu gửi */
        startTime: number;
        /** Thời gian kết thúc */
        endTime: number;
        /** Thời gian thực hiện (milliseconds) */
        duration: number;
    }>;
    /** Tổng thời gian thực hiện (milliseconds) */
    totalDuration: number;
    /** Thống kê tin nhắn tổng cộng */
    messageStats: {
        /** Tổng số tin nhắn đã gửi thành công */
        totalSuccessfulMessages: number;
        /** Tổng số tin nhắn thất bại */
        totalFailedMessages: number;
        /** Tổng số tin nhắn */
        totalMessages: number;
    };
}
/**
 * Service for handling Zalo Official Account Group Message Framework (GMF) APIs
 *
 * CONDITIONS FOR USING ZALO GMF:
 *
 * 1. OPT-IN CONDITIONS FOR SENDING GROUP MESSAGES:
 *    - OA must have the group_id of the chat group
 *    - OA must be added to the chat group by group admin
 *    - OA must have permission to send messages in the group (granted by group admin)
 *    - Chat group must be active (not locked or disbanded)
 *
 * 2. ACCESS PERMISSIONS:
 *    - Application needs to be granted group chat management permissions
 *    - Access token must have "manage_group" scope or equivalent
 *    - OA must be authenticated and have active status
 *
 * 3. LIMITS AND CONSTRAINTS:
 *    - Can only send messages to groups that OA has joined
 *    - Cannot send messages to private groups that OA hasn't been invited to
 *    - Must comply with Zalo's message sending frequency limits
 *    - Message content must comply with Zalo's content policy
 *
 * 4. SUPPORTED MESSAGE TYPES:
 *    - Text message: Plain text messages
 *    - Image message: Image messages (JPG, PNG, GIF - max 5MB)
 *    - File message: File attachments (max 25MB)
 *    - Sticker message: Stickers from Zalo collection
 *    - Mention message: Tag/mention specific members
 *
 * 5. TECHNICAL REQUIREMENTS:
 *    - Use HTTPS for all API calls
 *    - Content-Type: application/json for text/mention messages
 *    - Content-Type: multipart/form-data for file/image uploads
 */
export declare class GroupMessageService {
    private readonly client;
    private readonly endpoints;
    constructor(client: ZaloClient);
    /**
     * Send text message to group
     * @param accessToken OA access token
     * @param groupId Group ID
     * @param message Text message content
     * @returns Send result
     */
    sendTextMessage(accessToken: string, groupId: string, message: GroupTextMessage): Promise<GroupMessageResult>;
    /**
     * Send image message to group
     * @param accessToken OA access token
     * @param groupId Group ID
     * @param message Image message content
     * @returns Send result
     */
    sendImageMessage(accessToken: string, groupId: string, message: GroupImageMessage): Promise<GroupMessageResult>;
    /**
     * Send file message to group
     * @param accessToken OA access token
     * @param groupId Group ID
     * @param message File message content
     * @returns Send result
     */
    sendFileMessage(accessToken: string, groupId: string, message: GroupFileMessage): Promise<GroupMessageResult>;
    /**
     * Send sticker message to group
     * @param accessToken OA access token
     * @param groupId Group ID
     * @param message Sticker message content
     * @returns Send result
     */
    sendStickerMessage(accessToken: string, groupId: string, message: GroupStickerMessage): Promise<GroupMessageResult>;
    /**
     * Send mention message to group
     * @param accessToken OA access token
     * @param groupId Group ID
     * @param message Mention message content
     * @returns Send result
     */
    sendMentionMessage(accessToken: string, groupId: string, message: GroupMentionMessage): Promise<GroupMessageResult>;
    /**
     * Get group information
     * @param accessToken OA access token
     * @param groupId Group ID
     * @returns Group information
     */
    getGroupInfo(accessToken: string, groupId: string): Promise<GroupInfo>;
    /**
     * Get group members
     * @param accessToken OA access token
     * @param groupId Group ID
     * @param offset Offset for pagination
     * @param count Number of members to retrieve
     * @returns Group members list
     */
    getGroupMembers(accessToken: string, groupId: string, offset?: number, count?: number): Promise<{
        members: GroupMember[];
        total: number;
    }>;
    /**
     * Gửi danh sách tin nhắn tới 1 group với delay tùy chỉnh
     * Hỗ trợ tất cả các loại tin nhắn: text, image, file, sticker, mention
     *
     * @param request Thông tin request gửi danh sách tin nhắn
     * @returns Kết quả gửi từng tin nhắn
     */
    sendMessageListToGroup(request: SendMessageListToGroupRequest): Promise<SendMessageListToGroupResponse>;
    private handleGroupMessageError;
    /**
     * Gửi danh sách tin nhắn tới nhiều groups với callback tracking
     *
     * @param request Thông tin request gửi danh sách tin nhắn tới nhiều groups
     * @returns Kết quả gửi tin nhắn cho tất cả groups
     */
    sendMessageListToMultipleGroups(request: SendMessageListToMultipleGroupsRequest): Promise<SendMessageListToMultipleGroupsResponse>;
    /**
     * Gửi tin nhắn cá nhân hóa tới nhiều groups - mỗi group có bộ tin nhắn riêng
     *
     * @param request Thông tin request gửi tin nhắn cá nhân hóa tới nhiều groups
     * @returns Kết quả gửi tin nhắn cho tất cả groups
     */
    sendPersonalizedMessageToMultipleGroups(request: SendPersonalizedMessageToMultipleGroupsRequest): Promise<SendPersonalizedMessageToMultipleGroupsResponse>;
    /**
     * Utility method để sleep/delay
     * @param ms Thời gian delay tính bằng milliseconds
     */
    private sleep;
}
//# sourceMappingURL=group-message.service.d.ts.map