@warriorteam/redai-zalo-sdk
Version:
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
875 lines • 26 kB
TypeScript
/**
* 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[];
}
/**
* Enhanced response for getAllGroupMembers with additional metadata
*/
export interface AllGroupMembersResponse {
/** Error code (0 = success) */
error: number;
/** Response message */
message: string;
/** Enhanced data with all members and pagination info */
data: {
/** Total number of members in the group */
total_members: number;
/** ALL members retrieved */
members: GroupMemberInfo[];
/** Total number of API pages fetched */
pages_fetched: number;
/** Whether all available members were retrieved */
is_complete: boolean;
};
}
/**
* Enhanced response for getAllGroupsOfOA with additional metadata
*/
export interface AllGroupsOfOAResponse {
/** Error code (0 = success) */
error: number;
/** Response message */
message: string;
/** Enhanced data with pagination info */
data: {
/** Total number of groups for the OA */
total_groups: number;
/** Array of all OA groups */
groups: OAGroupItem[];
/** Number of API pages fetched to get all groups */
pages_fetched: number;
/** Whether all available groups were retrieved (not limited by maxGroups) */
is_complete: boolean;
};
}
/**
* Progress callback interface for getAllGroupMembers
*/
export interface GetAllMembersProgress {
/** Current number of members retrieved */
currentCount: number;
/** Total number of members in group (if known) */
totalCount?: number;
/** Completion percentage (if totalCount is known) */
percentage?: number;
/** Whether the operation is complete */
isComplete: boolean;
}
/**
* Enhanced group member with detailed user information
* Combines basic member info from group API with detailed user info from user API
*/
export interface EnhancedGroupMember {
/** Basic member info from group API (always available) */
basic_info: GroupMemberInfo;
/** Detailed user info from user API (null if failed to fetch) */
detailed_info: import('../types/user').UserInfo | null;
/** Whether detailed info was successfully fetched */
has_detailed_info: boolean;
/** Error message if failed to fetch detailed info */
detail_fetch_error?: string;
}
/**
* Enhanced response for getAllGroupMembersWithDetails
*/
export interface AllGroupMembersWithDetailsResponse {
/** Error code (0 = success) */
error: number;
/** Response message */
message: string;
/** Enhanced data with detailed member information */
data: {
/** Total number of members in the group */
total_members: number;
/** ALL enhanced members retrieved */
members: EnhancedGroupMember[];
/** Total number of API pages fetched during member retrieval */
pages_fetched: number;
/** Whether all available members were retrieved */
is_complete: boolean;
/** Statistics about detailed info fetching */
detail_fetch_stats: {
/** Total members processed */
total_processed: number;
/** Successfully fetched detailed info */
successful_details: number;
/** Failed to fetch detailed info */
failed_details: number;
/** Success rate percentage */
success_rate: number;
};
};
}
/**
* Progress callback interface for getAllGroupMembersWithDetails
*/
export interface GetAllMembersWithDetailsProgress {
/** Current number of members retrieved */
currentCount: number;
/** Total number of members in group (if known) */
totalCount?: number;
/** Completion percentage (if totalCount is known) */
percentage?: number;
/** Whether the operation is complete */
isComplete: boolean;
/** Current phase of operation */
phase: 'fetching_members' | 'fetching_details' | 'complete';
/** Details about current phase */
phase_details?: {
/** For fetching_details phase: number of details fetched */
details_fetched?: number;
/** For fetching_details phase: number of details failed */
details_failed?: number;
/** Current batch being processed */
current_batch?: number;
/** Total batches to process */
total_batches?: number;
};
}
//# sourceMappingURL=group.d.ts.map