@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
318 lines • 10.7 kB
TypeScript
/**
* Types cho Consultation Service - Zalo OA API
*
* Consultation messages (tin nhắn tư vấn) là loại tin nhắn đặc biệt
* cho phép OA gửi tin nhắn chủ động đến người dùng trong khung thời gian nhất định
*
* API Endpoint: https://openapi.zalo.me/v3.0/oa/message/cs
* Method: POST
* Content-Type: application/json
*/
/**
* Interface cho template action (default_action trong elements)
*/
export interface TemplateAction {
/** Loại action */
type: "oa.open.url" | "oa.query.show" | "oa.query.hide" | "oa.open.sms" | "oa.open.phone";
/** URL (cho oa.open.url) */
url?: string;
/** Payload string (cho oa.query.show, oa.query.hide) hoặc object (cho oa.open.sms, oa.open.phone) */
payload?: string | {
content?: string;
phone_code?: string;
} | {
phone_code?: string;
};
}
/**
* Interface cho template element
*
* Quy tắc elements:
* - elements là mảng JSON, tối đa 5 phần tử
* - title: bắt buộc, ≤ 100 ký tự
* - subtitle: bắt buộc cho element đầu tiên, tùy chọn cho các element sau, ≤ 500 ký tự
* - image_url: URL ảnh (tùy chọn)
* - default_action: hành động khi click vào element (tùy chọn)
*/
export interface TemplateElement {
/** Tiêu đề (bắt buộc, ≤ 100 ký tự) */
title: string;
/** Tiêu đề phụ (bắt buộc cho element đầu tiên, tùy chọn cho các element sau, ≤ 500 ký tự) */
subtitle?: string;
/** URL ảnh (tùy chọn) */
image_url?: string;
/** Hành động khi click vào element (tùy chọn) */
default_action?: TemplateAction;
}
/**
* Interface cho template button
*
* Quy tắc buttons:
* - buttons là mảng JSON, tối đa 5 phần tử
* - title: bắt buộc, ≤ 100 ký tự
* - type: loại action
* - payload: dữ liệu của action, phụ thuộc vào loại type
*/
export interface TemplateButton {
/** Tiêu đề button (bắt buộc, ≤ 100 ký tự) */
title: string;
/** Loại button */
type: "oa.open.url" | "oa.query.show" | "oa.query.hide" | "oa.open.sms" | "oa.open.phone";
/** Payload của button, phụ thuộc vào type */
payload: string | {
url?: string;
} | {
content?: string;
phone_code?: string;
} | {
phone_code?: string;
};
}
/**
* Interface cho từng tin nhắn trong chuỗi tin nhắn
*/
export interface MessageItem {
/** Loại tin nhắn */
type: "text" | "image" | "gif" | "file" | "sticker" | "request_user_info";
/** Nội dung tin nhắn (cho text message) */
text?: string;
/** URL hình ảnh (cho image/gif message) */
imageUrl?: string;
/** URL GIF (cho gif message) */
gifUrl?: string;
/** Chiều rộng GIF (bắt buộc cho gif) */
width?: number;
/** Chiều cao GIF (bắt buộc cho gif) */
height?: number;
/** Token file (cho file message) */
fileToken?: string;
/** Attachment ID (cho image/sticker message) */
attachmentId?: string;
/** Sticker attachment ID (cho sticker message) */
stickerAttachmentId?: string;
/** Tiêu đề (cho request_user_info message) */
title?: string;
/** Tiêu đề phụ (cho request_user_info message) */
subtitle?: string;
/** Delay sau khi gửi tin nhắn này (milliseconds) */
delay?: number;
}
/**
* Interface cho request gửi chuỗi tin nhắn
*/
export interface SendMessageSequenceRequest {
/** Access token của Official Account */
accessToken: string;
/** ID người nhận */
userId: string;
/** Danh sách tin nhắn */
messages: MessageItem[];
/** Delay mặc định giữa các tin nhắn (milliseconds) - nếu không có delay riêng */
defaultDelay?: number;
}
/**
* Interface cho response gửi chuỗi tin nhắn
*/
export interface SendMessageSequenceResponse {
/** Tổng số tin nhắn đã gửi thành công */
successCount: number;
/** Tổng số tin nhắn thất bại */
failureCount: number;
/** Chi tiết kết quả từng tin nhắn */
results: Array<{
/** Index của tin nhắn trong danh sách */
index: number;
/** Loại tin nhắn */
type: string;
/** Trạng thái gửi */
success: boolean;
/** Thông tin response nếu thành công */
response?: any;
/** Thông tin lỗi nếu thất bại */
error?: string;
/** Thời gian gửi */
timestamp: number;
}>;
/** Tổng thời gian thực hiện (milliseconds) */
totalDuration: number;
}
/**
* Interface cho request gửi chuỗi tin nhắn tới nhiều users
*/
export interface SendMessageSequenceToMultipleUsersRequest {
/** Access token của Official Account */
accessToken: string;
/** Danh sách user IDs */
userIds: string[];
/** Danh sách tin nhắn */
messages: MessageItem[];
/** Delay mặc định giữa các tin nhắn (milliseconds) */
defaultDelay?: number;
/** Delay giữa các user (milliseconds) để tránh rate limit */
delayBetweenUsers?: number;
/** Callback function để tracking tiến trình */
onProgress?: (progress: UserProgressInfo) => void;
}
/**
* Interface cho thông tin tiến trình từng user
*/
export interface UserProgressInfo {
/** User ID hiện tại */
userId: string;
/** Index của user trong danh sách (bắt đầu từ 0) */
userIndex: number;
/** Tổng số users */
totalUsers: number;
/** 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?: SendMessageSequenceResponse;
/** 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 chuỗi tin nhắn tới nhiều users
*/
export interface SendMessageSequenceToMultipleUsersResponse {
/** Tổng số users */
totalUsers: number;
/** Số users gửi thành công */
successfulUsers: number;
/** Số users gửi thất bại */
failedUsers: number;
/** Chi tiết kết quả từng user */
userResults: Array<{
/** User ID */
userId: string;
/** Index của user trong danh sách */
userIndex: number;
/** Trạng thái gửi cho user này */
success: boolean;
/** Kết quả chi tiết gửi tin nhắn */
messageSequenceResult?: SendMessageSequenceResponse;
/** 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;
};
}
/**
* Các loại template action types
*/
export type TemplateActionType = "oa.open.url" | "oa.query.show" | "oa.query.hide" | "oa.open.sms" | "oa.open.phone";
/**
* Các loại template button types (giống với action types)
*/
export type TemplateButtonType = TemplateActionType;
/**
* Payload cho URL action/button
*/
export interface UrlPayload {
url: string;
}
/**
* Payload cho SMS action/button
*/
export interface SmsPayload {
phone_code: string;
content?: string;
}
/**
* Payload cho Phone action/button
*/
export interface PhonePayload {
phone_code: string;
}
/**
* Union type cho tất cả các loại payload
*/
export type ConsultationTemplatePayload = string | UrlPayload | SmsPayload | PhonePayload;
/**
* Template types được hỗ trợ
*/
export type TemplateType = "request_user_info" | "media" | string;
/**
* Interface cho tin nhắn tùy chỉnh của từng user
*/
export interface UserCustomMessage {
/** User ID */
userId: string;
/** Danh sách tin nhắn riêng cho user này */
messages: MessageItem[];
}
/**
* Interface cho request gửi tin nhắn tùy chỉnh tới nhiều users
*/
export interface SendCustomMessageSequenceToMultipleUsersRequest {
/** Access token của Official Account */
accessToken: string;
/** Danh sách user và tin nhắn tùy chỉnh */
userCustomMessages: UserCustomMessage[];
/** Delay mặc định giữa các tin nhắn (milliseconds) */
defaultDelay?: number;
/** Delay giữa các user (milliseconds) để tránh rate limit */
delayBetweenUsers?: number;
/** Callback function để tracking tiến trình */
onProgress?: (progress: UserProgressInfo) => void;
}
/**
* Interface cho response gửi tin nhắn tùy chỉnh tới nhiều users
*/
export interface SendCustomMessageSequenceToMultipleUsersResponse {
/** Tổng số users */
totalUsers: number;
/** Số users gửi thành công */
successfulUsers: number;
/** Số users gửi thất bại */
failedUsers: number;
/** Chi tiết kết quả từng user */
userResults: Array<{
/** User ID */
userId: string;
/** Index của user trong danh sách */
userIndex: number;
/** Trạng thái gửi cho user này */
success: boolean;
/** Kết quả chi tiết gửi tin nhắn */
messageSequenceResult?: SendMessageSequenceResponse;
/** 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;
};
}
//# sourceMappingURL=consultation.d.ts.map