@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
202 lines • 7.99 kB
TypeScript
import { ZaloClient } from "../clients/zalo-client";
import { SendMessageResponse, MessageRecipient } from "../types/message";
import { PromotionMessage, PromotionUserResult, MultiplePromotionProgress, MultiplePromotionResult, PromotionButtonInput, BannerConfig } from "../types/promotion";
/**
* Service xử lý các API tin nhắn truyền thông/quảng cáo của Zalo Official Account
*
* ĐIỀU KIỆN GỬI TIN TRUYỀN THÔNG:
*
* 1. THỜI GIAN GỬI:
* - Chỉ được gửi trong khung giờ từ 8:00 - 22:00 hàng ngày
* - Không được gửi vào các ngày lễ, tết theo quy định
*
* 2. NỘI DUNG TIN NHẮN:
* - Phải là nội dung quảng cáo, khuyến mãi, tin tức
* - Không được chứa nội dung vi phạm pháp luật
* - Phải tuân thủ quy định về quảng cáo của Việt Nam
*
* 3. TẦN SUẤT GỬI:
* - Tối đa 1 tin nhắn truyền thông/ngày cho mỗi người dùng
* - Người dùng có thể từ chối nhận tin truyền thông
*
* 4. ĐỊNH DẠNG:
* - Phải sử dụng template được Zalo phê duyệt trước
* - Template phải tuân thủ format chuẩn của tin truyền thông
*
* 5. NGƯỜI DÙNG:
* - Người dùng phải đã follow OA
* - Người dùng không được block OA
* - Người dùng không được từ chối nhận tin truyền thông
*
* 6. OFFICIAL ACCOUNT:
* - OA phải được xác minh (verified)
* - OA phải có quyền gửi tin truyền thông được Zalo cấp phép
* - OA không được vi phạm chính sách về quảng cáo
*
* LỖI THƯỜNG GẶP:
* - 2001: Ngoài khung giờ cho phép (8:00-22:00)
* - 2002: Người dùng đã từ chối nhận tin truyền thông
* - 2003: Vượt quá giới hạn 1 tin/ngày
* - 2004: Template chưa được phê duyệt
* - 2005: Nội dung vi phạm chính sách quảng cáo
* - 2006: OA chưa có quyền gửi tin truyền thông
*/
export declare class PromotionService {
private readonly client;
private readonly promotionApiUrl;
constructor(client: ZaloClient);
/**
* Convert input button to proper typed button for API
* @param button Input button with flexible typing
* @returns Properly typed button for API
*/
private convertToTypedButton;
/**
* Gửi tin nhắn truyền thông/quảng cáo
* @param accessToken Access token của Official Account
* @param recipient Thông tin người nhận
* @param message Nội dung tin nhắn truyền thông
* @returns Thông tin tin nhắn đã gửi
*/
sendPromotionMessage(accessToken: string, recipient: MessageRecipient, message: PromotionMessage): Promise<SendMessageResponse>;
/**
* Gửi tin nhắn khuyến mãi sản phẩm
* @param accessToken Access token của Official Account
* @param recipient Thông tin người nhận
* @param promotionInfo Thông tin khuyến mãi
* @returns Thông tin tin nhắn đã gửi
*/
sendProductPromotion(accessToken: string, recipient: MessageRecipient, promotionInfo: {
title: string;
description: string;
imageUrl?: string;
attachmentId?: string;
originalPrice: number;
discountPrice: number;
discountPercent: number;
validUntil: string;
productUrl: string;
}): Promise<SendMessageResponse>;
/**
* Gửi tin nhắn thông báo sự kiện
* @param accessToken Access token của Official Account
* @param recipient Thông tin người nhận
* @param eventInfo Thông tin sự kiện
* @returns Thông tin tin nhắn đã gửi
*/
sendEventNotification(accessToken: string, recipient: MessageRecipient, eventInfo: {
title: string;
description: string;
imageUrl?: string;
attachmentId?: string;
eventDate: string;
location: string;
registrationUrl: string;
}): Promise<SendMessageResponse>;
/**
* Gửi tin nhắn newsletter
* @param accessToken Access token của Official Account
* @param recipient Thông tin người nhận
* @param newsletterInfo Thông tin newsletter
* @returns Thông tin tin nhắn đã gửi
*/
sendNewsletter(accessToken: string, recipient: MessageRecipient, newsletterInfo: {
title: string;
summary: string;
imageUrl?: string;
attachmentId?: string;
articles: Array<{
title: string;
url: string;
}>;
unsubscribeUrl: string;
}): Promise<SendMessageResponse>;
/**
* Tạo promotion message theo format chuẩn v3.0 (như trong docs)
* @param accessToken Access token của Official Account
* @param recipient Thông tin người nhận
* @param promotionData Dữ liệu promotion
* @returns Thông tin tin nhắn đã gửi
*/
sendCustomPromotion(accessToken: string, recipient: MessageRecipient, promotionData: {
banner: BannerConfig;
headerContent: string;
textContent: string;
tableData: Array<{
key: string;
value: string;
}>;
footerText?: string;
buttons: PromotionButtonInput[];
language?: "VI" | "EN";
}): Promise<SendMessageResponse>;
/**
* Validate banner configuration
* @param banner Banner configuration to validate
*/
private validateBannerConfig;
/**
* Validate promotion message format
* @param message Promotion message to validate
*/
private validatePromotionMessage;
/**
* Gửi promotion message đến nhiều user_ids với callback tracking
* @param accessToken Access token của Official Account
* @param userIds Danh sách user IDs cần gửi
* @param promotionData Dữ liệu promotion
* @param options Tùy chọn gửi và tracking
* @returns Kết quả gửi đến tất cả users
*/
sendCustomPromotionToMultipleUsers(accessToken: string, userIds: string[], promotionData: {
banner: BannerConfig;
headerContent: string;
textContent: string;
tableData: Array<{
key: string;
value: string;
}>;
footerText?: string;
buttons: PromotionButtonInput[];
language?: "VI" | "EN";
}, options?: {
mode?: "sequential" | "parallel";
delayMs?: number;
onProgress?: (progress: MultiplePromotionProgress) => void;
onUserComplete?: (result: PromotionUserResult) => void;
continueOnError?: boolean;
}): Promise<MultiplePromotionResult>;
/**
* Gửi promotion message đến nhiều user_ids với promotionData riêng cho từng user
* @param accessToken Access token của Official Account
* @param userPromotions Danh sách user và promotionData tương ứng
* @param options Tùy chọn gửi và tracking
* @returns Kết quả gửi đến tất cả users
*/
sendPersonalizedPromotionToMultipleUsers(accessToken: string, userPromotions: Array<{
userId: string;
promotionData: {
banner: BannerConfig;
headerContent: string;
textContent: string;
tableData: Array<{
key: string;
value: string;
}>;
footerText?: string;
buttons: PromotionButtonInput[];
language?: "VI" | "EN";
};
}>, options?: {
mode?: "sequential" | "parallel";
delayMs?: number;
onProgress?: (progress: MultiplePromotionProgress) => void;
onUserComplete?: (result: PromotionUserResult) => void;
continueOnError?: boolean;
}): Promise<MultiplePromotionResult>;
/**
* Validate sending time (8:00 - 22:00)
*/
private validateSendingTime;
}
//# sourceMappingURL=promotion.service.d.ts.map