@warriorteam/redai-zalo-sdk/dist/types/group.d.ts

Comprehensive TypeScript/JavaScript SDK for Zalo APIs - Official Account, ZNS, Consultation Service, Group Messaging, and Social APIs

/**
 * Group Message Framework (GMF) Type Definitions
 */
export interface GroupMessage {
    type: "text" | "image" | "file" | "sticker" | "mention";
}
export interface GroupTextMessage extends GroupMessage {
    type: "text";
    text: string;
}
export interface GroupImageMessage extends GroupMessage {
    type: "image";
    imageUrl?: string;
    attachmentId?: string;
    caption?: string;
}
export interface GroupFileMessage extends GroupMessage {
    type: "file";
    fileToken: string;
    fileName?: string;
    fileSize?: number;
}
export interface GroupStickerMessage extends GroupMessage {
    type: "sticker";
    stickerId: string;
    stickerCategory?: string;
}
export interface GroupMentionMessage extends GroupMessage {
    type: "mention";
    text: string;
    mentions: Array<{
        user_id: string;
        offset: number;
        length: number;
    }>;
}
export interface GroupMessageResult {
    error: number;
    message: string;
    data?: {
        message_id: string;
        sent_time: string;
        group_id: string;
    };
}
export interface GroupInfo {
    error: number;
    message: string;
    data?: {
        group_id: string;
        group_name: string;
        group_description?: string;
        group_avatar?: string;
        member_count: number;
        created_time: string;
        group_type: "PUBLIC" | "PRIVATE";
        group_status: "ACTIVE" | "INACTIVE" | "DISBANDED";
        admin_ids: string[];
        oa_permissions: {
            can_send_message: boolean;
            can_view_members: boolean;
            can_manage_group: boolean;
        };
    };
}
export interface GroupMember {
    user_id: string;
    display_name: string;
    avatar?: string;
    role: "ADMIN" | "MEMBER";
    joined_time: string;
    is_active: boolean;
    last_seen?: string;
}
export interface GroupMemberList {
    error: number;
    message: string;
    data?: {
        members: GroupMember[];
        total_count: number;
        has_more: boolean;
    };
}
export interface GroupSettings {
    group_id: string;
    settings: {
        allow_member_invite: boolean;
        allow_member_add_admin: boolean;
        allow_member_change_info: boolean;
        require_admin_approval: boolean;
        auto_approve_join_request: boolean;
        message_history_visible: boolean;
    };
}
export interface GroupJoinRequest {
    request_id: string;
    user_id: string;
    display_name: string;
    avatar?: string;
    request_message?: string;
    request_time: string;
    status: "PENDING" | "APPROVED" | "REJECTED";
}
export interface GroupJoinRequestList {
    error: number;
    message: string;
    data?: {
        requests: GroupJoinRequest[];
        total_count: number;
        has_more: boolean;
    };
}
export interface GroupInvitation {
    invitation_id: string;
    group_id: string;
    inviter_id: string;
    invitee_phone?: string;
    invitee_user_id?: string;
    invitation_message?: string;
    invitation_time: string;
    expiry_time: string;
    status: "PENDING" | "ACCEPTED" | "REJECTED" | "EXPIRED";
}
export interface GroupActivity {
    activity_id: string;
    group_id: string;
    user_id: string;
    activity_type: "JOIN" | "LEAVE" | "MESSAGE" | "ADMIN_ACTION" | "SETTINGS_CHANGE";
    activity_description: string;
    activity_time: string;
    metadata?: Record<string, any>;
}
export interface GroupActivityList {
    error: number;
    message: string;
    data?: {
        activities: GroupActivity[];
        total_count: number;
        has_more: boolean;
    };
}
export interface GroupStatistics {
    group_id: string;
    period: {
        from: string;
        to: string;
    };
    stats: {
        total_messages: number;
        active_members: number;
        new_members: number;
        left_members: number;
        message_breakdown: {
            text: number;
            image: number;
            file: number;
            sticker: number;
            other: number;
        };
        daily_activity: Array<{
            date: string;
            message_count: number;
            active_member_count: number;
        }>;
        top_active_members: Array<{
            user_id: string;
            display_name: string;
            message_count: number;
        }>;
    };
}
export interface GroupMessageTemplate {
    template_id: string;
    template_name: string;
    template_content: string;
    template_type: "ANNOUNCEMENT" | "WELCOME" | "REMINDER" | "CUSTOM";
    variables: Array<{
        name: string;
        type: "TEXT" | "NUMBER" | "DATE";
        required: boolean;
        default_value?: string;
    }>;
    created_time: string;
    last_used?: string;
    usage_count: number;
}
export interface GroupMessageSchedule {
    schedule_id: string;
    group_id: string;
    message: GroupMessage;
    schedule_time: string;
    repeat_type?: "NONE" | "DAILY" | "WEEKLY" | "MONTHLY";
    repeat_interval?: number;
    repeat_end_date?: string;
    status: "PENDING" | "SENT" | "CANCELLED" | "FAILED";
    created_time: string;
}
export interface GroupBroadcast {
    broadcast_id: string;
    group_ids: string[];
    message: GroupMessage;
    send_time?: string;
    target_criteria?: {
        member_roles?: ("ADMIN" | "MEMBER")[];
        member_join_date_from?: string;
        member_join_date_to?: string;
        active_in_last_days?: number;
    };
    status: "PENDING" | "SENDING" | "COMPLETED" | "FAILED" | "CANCELLED";
    results?: {
        total_groups: number;
        successful_groups: number;
        failed_groups: number;
        total_recipients: number;
        successful_sends: number;
        failed_sends: number;
    };
    created_time: string;
    completed_time?: string;
}
export interface GroupPermission {
    group_id: string;
    user_id: string;
    permissions: {
        can_send_message: boolean;
        can_send_media: boolean;
        can_mention_all: boolean;
        can_invite_members: boolean;
        can_remove_members: boolean;
        can_change_group_info: boolean;
        can_pin_messages: boolean;
        can_delete_messages: boolean;
    };
}
export interface GroupWebhookEvent {
    event_type: "GROUP_MESSAGE" | "MEMBER_JOIN" | "MEMBER_LEAVE" | "GROUP_SETTINGS_CHANGE";
    group_id: string;
    timestamp: string;
    data: Record<string, any>;
}
export interface GroupApiResponse<T = any> {
    error: number;
    message: string;
    data?: T;
}
export type GroupCreateResponse = GroupApiResponse<{
    group_id: string;
    group_name: string;
    created_time: string;
}>;
export type GroupUpdateResponse = GroupApiResponse<{
    group_id: string;
    updated_fields: string[];
    updated_time: string;
}>;
export type GroupDeleteResponse = GroupApiResponse<{
    group_id: string;
    deleted_time: string;
}>;
export type GroupMemberActionResponse = GroupApiResponse<{
    group_id: string;
    user_id: string;
    action: "ADDED" | "REMOVED" | "PROMOTED" | "DEMOTED";
    action_time: string;
}>;
/**
 * Group creation request
 */
export interface GroupCreateRequest {
    group_name: string;
    group_description?: string;
    asset_id: string;
    member_user_ids: string[];
}
/**
 * Group creation data - theo chuẩn Zalo API response data field
 * API: POST https://openapi.zalo.me/v3.0/oa/group/creategroupwithoa
 */
export interface GroupCreateData {
    /** ID của nhóm vừa tạo */
    group_id: string;
    /** Tên nhóm */
    name: string;
    /** URL avatar của nhóm */
    avatar: string;
    /** Link để tham gia nhóm */
    group_link: string;
    /** Mô tả nhóm */
    group_description: string;
    /** Tổng số lượng thành viên trong nhóm */
    total_member: number;
    /** Trạng thái nhóm: "enabled" | "disabled" */
    status: "enabled" | "disabled";
}
/**
 * Group creation result - full Zalo API response wrapper
 * API: POST https://openapi.zalo.me/v3.0/oa/group/creategroupwithoa
 */
export interface GroupCreateResult {
    /** Response data */
    data: GroupCreateData;
    /** Error code (0 = success) */
    error: number;
    /** Response message */
    message: string;
}
/**
 * Group update request - theo chuẩn Zalo API
 * API: POST https://openapi.zalo.me/v3.0/oa/group/updateinfo
 */
export interface GroupUpdateRequest {
    /** Tên nhóm */
    group_name?: string;
    /** Avatar của nhóm */
    group_avatar?: string;
    /** Mô tả nhóm */
    group_description?: string;
    /** Cài đặt chức năng nhắn tin của các thành viên */
    lock_send_msg?: boolean;
    /** Cài đặt chế độ phê duyệt thành viên mới */
    join_appr?: boolean;
    /** Cài đặt cho phép thành viên mới đọc tin nhắn gần nhất */
    enable_msg_history?: boolean;
    /** Cài đặt bật tắt tham gia nhóm bằng link */
    enable_link_join?: boolean;
}
/**
 * Group update result - theo chuẩn Zalo API response
 * API: POST https://openapi.zalo.me/v3.0/oa/group/updateinfo
 */
export interface GroupUpdateResult {
    data: {
        /** Thông tin nhóm */
        group_info: {
            group_id: string;
            group_link: string;
            name: string;
            group_description: string;
            avatar: string;
            status: "enabled" | "disabled";
            total_member: number;
            max_member: string;
            auto_delete_date: string;
        };
        /** Thông tin asset */
        asset_info: {
            asset_type: "gmf10" | "gmf50" | "gmf100";
            asset_id: string;
            valid_through: string;
            auto_renew: string;
        };
        /** Cài đặt nhóm */
        group_setting: {
            lock_send_msg: boolean;
            join_appr: boolean;
            enable_msg_history: boolean;
            enable_link_join: boolean;
        };
    };
    error: number;
    message: string;
}
/**
 * Group asset update request - theo chuẩn Zalo API
 * API: POST https://openapi.zalo.me/v3.0/oa/group/updateasset
 *
 * Sử dụng để:
 * - Tăng giới hạn số lượng thành viên trong nhóm
 * - Gia hạn cho nhóm chat khi hết hạn
 */
export interface GroupAssetUpdateRequest {
    /** ID của nhóm */
    group_id: string;
    /** ID của gói hạn mức (lấy từ API kiểm tra hạn mức tạo nhóm GMF) */
    asset_id: string;
}
/**
 * Group avatar update request
 * @deprecated Use GroupUpdateRequest with group_avatar field instead
 */
export interface GroupAvatarUpdateRequest {
    avatar_url: string;
}
/**
 * Group member invitation request - theo chuẩn Zalo API
 * API: POST https://openapi.zalo.me/v3.0/oa/group/invite
 */
export interface GroupMemberInviteRequest {
    /** Danh sách user id muốn mời tham gia nhóm */
    member_user_ids: string[];
}
/**
 * Group member invitation result - theo chuẩn Zalo API response
 * API: POST https://openapi.zalo.me/v3.0/oa/group/invite
 */
export interface GroupInviteResult {
    /** Error code (0 = success) */
    error: number;
    /** Response message */
    message: string;
}
/**
 * Group member action request (for accept/reject)
 */
export interface GroupMemberActionRequest {
    member_uids: string[];
}
/**
 * Group admin action request - theo chuẩn Zalo API
 * API: POST https://openapi.zalo.me/v3.0/oa/group/addadmins
 * API: POST https://openapi.zalo.me/v3.0/oa/group/removeadmins
 */
export interface GroupAdminActionRequest {
    /** Danh sách các user_id được thêm/xóa làm phó nhóm */
    member_user_ids: string[];
}
/**
 * Group delete request
 */
export interface GroupDeleteRequest {
    group_id: string;
}
/**
 * Pending member information - theo chuẩn Zalo API
 * API: GET https://openapi.zalo.me/v3.0/oa/group/listpendinginvite
 */
export interface GroupPendingMember {
    /** Tên thành viên chờ tham gia nhóm */
    name: string;
    /** ID thành viên chờ tham gia nhóm */
    user_id: string;
}
/**
 * Group quota information
 */
export interface GroupQuota {
    error: number;
    message: string;
    data?: {
        max_groups: number;
        current_groups: number;
        remaining_groups: number;
        max_members_per_group: number;
        asset_info?: GroupQuotaAsset[];
    };
}
/**
 * Group quota asset information - theo chuẩn Zalo API
 * API: POST https://openapi.zalo.me/v3.0/oa/quota/group
 */
export interface GroupQuotaAsset {
    /** Loại sản phẩm (gmf10, gmf50, gmf100) */
    product_type: string;
    /** Loại quota (sub_quota, purchase_quota, reward_quota) */
    quota_type: string;
    /** ID gói GMF, sử dụng để làm dịch vụ hoạt động của Nhóm */
    asset_id: string;
    /** Ngày hết hạn của gói */
    valid_through: string;
    /** Có bật tự động gia hạn hay không */
    auto_renew: boolean;
    /** Trạng thái asset (available, used) */
    status: "available" | "used";
    /** ID của đối tượng sử dụng gói (group_id) */
    used_id?: string;
    /** Sử dụng used_id thay thế */
    group_id?: string;
}
/**
 * Recent chat message - theo chuẩn Zalo API
 * API: GET https://openapi.zalo.me/v3.0/oa/group/listrecentchat
 */
export interface RecentChatMessage {
    /** Thuộc tính cho biết tin nhắn được gửi từ OA (0) hoặc người dùng (1) */
    src: number;
    /** Thời gian tin nhắn được gửi (timestamp) */
    time: number;
    /** Loại tin nhắn (text, voice, photo, GIF, link, links, sticker, location) */
    type: string;
    /** Nội dung tin nhắn */
    message: string;
    /** ID của tin nhắn */
    message_id: string;
    /** ID của đối tượng gửi tin nhắn (user_id hoặc oa_id) */
    from_id: string;
    /** Tên hiển thị của đối tượng gửi tin nhắn */
    from_display_name: string;
    /** Đường dẫn đến ảnh đại diện của đối tượng gửi tin nhắn */
    from_avatar: string;
    /** ID của nhóm */
    group_id: string;
    /** Danh sách các đường dẫn được đính kèm (chỉ khi type là link hoặc links) */
    links?: string;
    /** URL của ảnh hoặc GIF (chỉ khi type là GIF hoặc photo) */
    thumb?: string;
    /** Đường dẫn đến audio/ảnh/GIF/sticker */
    url?: string;
    /** Mô tả của ảnh (chỉ khi type là photo) */
    description?: string;
    /** Giá trị longitude và latitude (chỉ khi type là location) */
    location?: string;
}
/**
 * Recent chats response - theo chuẩn Zalo API
 * API: GET https://openapi.zalo.me/v3.0/oa/group/listrecentchat
 */
export interface RecentChatsResponse {
    error: number;
    message: string;
    data: RecentChatMessage[];
}
/**
 * Recent chat information (legacy - deprecated)
 * @deprecated Use RecentChatMessage instead
 */
export interface GroupRecentChat {
    group_id: string;
    group_name: string;
    last_message: {
        message_id: string;
        content: string;
        sender_id: string;
        sent_time: string;
        message_type: string;
    };
    unread_count: number;
    last_activity: string;
}
/**
 * Group conversation response - theo chuẩn Zalo API
 * API: GET https://openapi.zalo.me/v3.0/oa/group/conversation
 *
 * Note: Response structure giống hệt với listrecentchat API
 */
export interface GroupConversationResponse {
    error: number;
    message: string;
    data: RecentChatMessage[];
}
/**
 * Group conversation message (legacy - deprecated)
 * @deprecated Use RecentChatMessage instead - API trả về structure giống hệt listrecentchat
 */
export interface GroupConversationMessage {
    message_id: string;
    sender_id: string;
    sender_name: string;
    content: string;
    message_type: "text" | "image" | "file" | "sticker" | "location";
    sent_time: string;
    attachments?: Array<{
        type: string;
        url: string;
        name?: string;
        size?: number;
    }>;
    mentioned_users?: string[];
}
/**
 * OA Group item - theo chuẩn Zalo API
 * API: GET https://openapi.zalo.me/v3.0/oa/group/getgroupsofoa
 */
export interface OAGroupItem {
    /** Tên nhóm */
    name: string;
    /** Hình đại diện của nhóm */
    avatar: string;
    /** ID của nhóm */
    group_id: string;
    /** Link để tham gia nhóm */
    group_link: string;
    /** Mô tả nhóm */
    group_description: string;
    /** Tổng số lượng thành viên trong nhóm */
    total_member: number;
    /** Trạng thái nhóm: enabled/disabled */
    status: string;
}
/**
 * Groups of OA response - theo chuẩn Zalo API
 * API: GET https://openapi.zalo.me/v3.0/oa/group/getgroupsofoa
 */
export interface GroupsOfOAResponse {
    error: number;
    message: string;
    data?: {
        /** Offset muốn query */
        offset: number;
        /** Số lượng muốn query */
        count: number;
        /** Tổng số lượng các nhóm của OA */
        total: number;
        /** Số lượng các nhóm được trả về */
        group_count: number;
        /** Danh sách các nhóm của OA */
        groups: OAGroupItem[];
    };
}
/**
 * Group detail response - theo chuẩn Zalo API
 * API: GET https://openapi.zalo.me/v3.0/oa/group/getgroup
 */
export interface GroupDetailResponse {
    error: number;
    message: string;
    data?: {
        /** Các thông tin của nhóm chat */
        group_info: {
            /** Tên nhóm */
            name: string;
            /** Avatar của nhóm */
            avatar: string;
            /** ID của nhóm */
            group_id: string;
            /** Link tham gia của nhóm */
            group_link: string;
            /** Mô tả nhóm */
            group_description: string;
            /** Trạng thái nhóm (enabled/disabled) */
            status: string;
            /** Tổng số lượng thành viên trong nhóm */
            total_member: number;
            /** Số lượng thành viên tối đa của nhóm */
            max_member: string;
            /** Ngày nhóm chat tự động giải tán */
            auto_delete_date: string;
        };
        /** Các thông tin của dịch vụ gắn với nhóm chat */
        asset_info: {
            /** Loại sản phẩm (gmf10, gmf50, gmf100) */
            asset_type: string;
            /** ID gói GMF */
            asset_id: string;
            /** Ngày hết hạn của gói */
            valid_through: string;
            /** Có bật tự động gia hạn hay không */
            auto_renew: string;
        };
        /** Các thông tin cài đặt trong nhóm chat */
        group_setting: {
            /** Cài đặt chức năng nhắn tin của các thành viên */
            lock_send_msg: boolean;
            /** Cài đặt chế độ phê duyệt thành viên mới */
            join_appr: boolean;
            /** Cài đặt cho phép thành viên mới đọc tin nhắn gần nhất */
            enable_msg_history: boolean;
            /** Cài đặt bật tắt tham gia nhóm bằng link */
            enable_link_join: boolean;
        };
    };
}
/**
 * Pending members response
 */
export interface GroupPendingMembersResponse {
    error: number;
    message: string;
    data?: {
        offset: number;
        count: number;
        total: number;
        member_count: number;
        members: GroupPendingMember[];
    };
}
/**
 * Accept pending members request
 */
export interface GroupAcceptPendingMembersRequest {
    group_id: string;
    member_user_ids: string[];
}
/**
 * Accept pending members response - theo chuẩn Zalo API
 * API: POST https://openapi.zalo.me/v3.0/oa/group/acceptpendinginvite
 */
export interface GroupAcceptPendingMembersResponse {
    /** Error code (0 = success) */
    error: number;
    /** Response message */
    message: string;
}
/**
 * Remove members request
 */
export interface GroupRemoveMembersRequest {
    group_id: string;
    member_user_ids: string[];
}
/**
 * Remove members response
 */
export interface GroupRemoveMembersResponse {
    error: number;
    message: string;
    data?: {
        removed_count: number;
        failed_members?: string[];
    };
}
/**
 * Group member information for list API - theo chuẩn Zalo API
 * API: GET https://openapi.zalo.me/v3.0/oa/group/listmember
 */
export interface GroupMemberInfo {
    /** ID thành viên trong nhóm (cho user thường) */
    user_id?: string;
    /** ID của OA (cho OA member) */
    oa_id?: string;
    /** Tên thành viên trong nhóm */
    name: string;
    /** Hình đại diện của thành viên trong nhóm */
    avatar: string;
}
/**
 * Group members response - theo chuẩn Zalo API
 * API: GET https://openapi.zalo.me/v3.0/oa/group/listmember
 */
export interface GroupMembersResponse {
    error: number;
    message: string;
    data?: {
        /** Offset muốn query */
        offset: number;
        /** Số lượng muốn query */
        count: number;
        /** Tổng số lượng các thành viên trong nhóm */
        total: number;
        /** Số lượng các thành viên được trả về */
        member_count: number;
        /** Thông tin các thành viên trong nhóm */
        members: GroupMemberInfo[];
    };
}
/**
 * Quota message request
 */
export interface GroupQuotaMessageRequest {
    quota_owner: "OA" | "APP";
    product_type?: string;
    quota_type?: string;
}
/**
 * Quota message response
 */
export interface GroupQuotaMessageResponse {
    error: number;
    message: string;
    data?: GroupQuotaAsset[];
}
//# sourceMappingURL=group.d.ts.map