@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
312 lines • 15 kB
TypeScript
import { ZaloClient } from "../clients/zalo-client";
import { MessageRecipient, SendMessageResponse, TextMessage, ConsultationQuoteMessage } from "../types/message";
import { TemplateAction, TemplateElement, TemplateButton, SendMessageSequenceRequest, SendMessageSequenceResponse, SendMessageSequenceToMultipleUsersRequest, SendMessageSequenceToMultipleUsersResponse, SendCustomMessageSequenceToMultipleUsersRequest, SendCustomMessageSequenceToMultipleUsersResponse } from "../types/consultation";
/**
* Service xử lý các API tin nhắn tư vấn của Zalo Official Account
*
* Tin nhắn tư vấn (CS - Customer Service) 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
*
* ĐIỀU KIỆN GỬI TIN TƯ VẤN:
*
* 1. THỜI GIAN GỬI:
* - Chỉ được gửi trong vòng 48 giờ kể từ khi người dùng tương tác cuối cùng với OA
* - Tương tác bao gồm: gửi tin nhắn, nhấn button, gọi điện, truy cập website từ OA
*
* 2. NỘI DUNG TIN NHẮN:
* - Phải liên quan đến tư vấn, hỗ trợ khách hàng
* - Bao gồm: trả lời câu hỏi, hướng dẫn sử dụng, hỗ trợ kỹ thuật
* - Không được chứa nội dung quảng cáo trực tiếp
*
* 3. TẦN SUẤT GỬI:
* - Không giới hạn số lượng tin nhắn tư vấn trong ngày
* - Tuy nhiên cần tuân thủ nguyên tắc không spam
*
* 4. 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 phải có tương tác gần đây với OA
*/
export declare class ConsultationService {
private readonly client;
private readonly endpoint;
constructor(client: ZaloClient);
/**
* Gửi tin nhắn tư vấn văn bản
* @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 văn bản
* @returns Thông tin tin nhắn đã gửi
*/
sendTextMessage(accessToken: string, recipient: MessageRecipient, message: TextMessage): Promise<SendMessageResponse>;
/**
* Gửi tin nhắn tư vấn trích dẫn (quote message)
* @param accessToken Access token của Official Account
* @param recipient Thông tin người nhận
* @param text Nội dung tin nhắn trả lời (tối đa 2000 ký tự)
* @param quoteMessageId ID của tin nhắn muốn trích dẫn
* @returns Thông tin tin nhắn đã gửi với quota information
*/
sendQuoteMessage(accessToken: string, recipient: MessageRecipient, text: string, quoteMessageId: string): Promise<SendMessageResponse>;
/**
* Tạo ConsultationQuoteMessage object
* @param text Nội dung tin nhắn trả lời
* @param quoteMessageId ID của tin nhắn muốn trích dẫn
* @param quoteContent Nội dung của tin nhắn được trích dẫn (optional)
* @returns ConsultationQuoteMessage object
*/
createQuoteMessage(text: string, quoteMessageId: string, quoteContent?: string): ConsultationQuoteMessage;
/**
* Gửi tin nhắn tư vấn hình ảnh bằng URL
*
* API Specification:
* - URL: https://openapi.zalo.me/v3.0/oa/message/cs
* - Method: POST
* - Content-Type: application/json
*
* @param accessToken Access token của Official Account
* @param userId ID người nhận (user_id)
* @param imageUrl URL trực tiếp đến hình ảnh (jpg, png, tối đa 1MB, tỷ lệ tối ưu 16:9)
* @param text Tiêu đề ảnh (optional, tối đa 2000 ký tự)
* @returns Thông tin tin nhắn đã gửi với quota information
*/
sendImageMessage(accessToken: string, userId: string, imageUrl: string, text?: string): Promise<SendMessageResponse>;
/**
* Gửi tin nhắn tư vấn hình ảnh bằng attachment_id (ảnh đã upload trước)
*
* API Specification:
* - URL: https://openapi.zalo.me/v3.0/oa/message/cs
* - Method: POST
* - Content-Type: application/json
* - Lưu ý: Chỉ sử dụng attachment_id HOẶC url, không được dùng cả hai
*
* @param accessToken Access token của Official Account
* @param userId ID người nhận (user_id)
* @param attachmentId ID của ảnh đã upload trước đó (từ API upload ảnh)
* @param text Tiêu đề ảnh (optional, tối đa 2000 ký tự)
* @returns Thông tin tin nhắn đã gửi với quota information
*/
sendImageByAttachmentId(accessToken: string, userId: string, attachmentId: string, text?: string): Promise<SendMessageResponse>;
/**
* Gửi tin nhắn tư vấn hình ảnh (hỗ trợ cả URL và attachment_id)
*
* API Specification:
* - URL: https://openapi.zalo.me/v3.0/oa/message/cs
* - Method: POST
* - Content-Type: application/json
* - Lưu ý: Chỉ sử dụng MỘT trong hai: imageUrl HOẶC attachmentId
*
* @param accessToken Access token của Official Account
* @param userId ID người nhận (user_id)
* @param options Tùy chọn gửi ảnh
* @param options.imageUrl URL trực tiếp đến hình ảnh (jpg, png, tối đa 1MB)
* @param options.attachmentId ID của ảnh đã upload trước đó
* @param options.text Tiêu đề ảnh (optional, tối đa 2000 ký tự)
* @returns Thông tin tin nhắn đã gửi với quota information
*/
sendImage(accessToken: string, userId: string, options: {
imageUrl?: string;
attachmentId?: string;
text?: string;
}): Promise<SendMessageResponse>;
/**
* Gửi tin nhắn tư vấn ảnh GIF động
*
* API Specification:
* - URL: https://openapi.zalo.me/v3.0/oa/message/cs
* - Method: POST
* - Content-Type: application/json
* - Lưu ý: width và height là BẮT BUỘC cho media_type = "gif"
*
* @param accessToken Access token của Official Account
* @param userId ID người nhận (user_id)
* @param gifUrl URL trực tiếp đến ảnh GIF (tối đa 1MB)
* @param width Chiều rộng của ảnh GIF (bắt buộc, > 0)
* @param height Chiều cao của ảnh GIF (bắt buộc, > 0)
* @param text Tiêu đề ảnh (optional, tối đa 2000 ký tự)
* @returns Thông tin tin nhắn đã gửi với quota information
*/
sendGifMessage(accessToken: string, userId: string, gifUrl: string, width: number, height: number, text?: string): Promise<SendMessageResponse>;
/**
* Gửi tin nhắn tư vấn đính kèm file
* Endpoint: https://openapi.zalo.me/v3.0/oa/message/cs
* Method: POST
*
* @param accessToken Access token của Official Account
* @param userId ID người nhận (user_id)
* @param fileToken Token của file đã upload (từ API upload file)
* @returns Thông tin tin nhắn đã gửi
*
* Note: Cần sử dụng API upload file trước để lấy token
*/
sendFileMessage(accessToken: string, userId: string, fileToken: string): Promise<SendMessageResponse>;
/**
* Gửi tin nhắn tư vấn theo mẫu yêu cầu thông tin người dùng
* Endpoint: https://openapi.zalo.me/v3.0/oa/message/cs
* Method: POST
*
* @param accessToken Access token của Official Account
* @param userId ID người nhận (user_id)
* @param title Tiêu đề hiển thị của template (tối đa 100 ký tự)
* @param subtitle Tiêu đề phụ của template (tối đa 500 ký tự)
* @param imageUrl Đường dẫn đến ảnh
* @returns Thông tin tin nhắn đã gửi
*/
sendRequestUserInfoMessage(accessToken: string, userId: string, title: string, subtitle: string, imageUrl: string): Promise<SendMessageResponse>;
/**
* Gửi tin nhắn tư vấn kèm Sticker
* Endpoint: https://openapi.zalo.me/v3.0/oa/message/cs
* Method: POST
*
* @param accessToken Access token của Official Account
* @param userId ID người nhận (user_id)
* @param stickerAttachmentId ID của sticker (lấy từ https://stickers.zaloapp.com/)
* @returns Thông tin tin nhắn đã gửi
*
* Note: Sticker ID lấy từ nguồn https://stickers.zaloapp.com/
* Xem video hướng dẫn: https://vimeo.com/649330161
*/
sendStickerMessage(accessToken: string, userId: string, stickerAttachmentId: string): Promise<SendMessageResponse>;
/**
* Gửi chuỗi tin nhắn tư vấn với delay tùy chỉnh
* Hỗ trợ tất cả các loại tin nhắn: text, image, gif, file, sticker, request_user_info
*
* @param request Thông tin request gửi chuỗi tin nhắn
* @returns Kết quả gửi từng tin nhắn
*/
sendMessageSequence(request: SendMessageSequenceRequest): Promise<SendMessageSequenceResponse>;
/**
* Gửi chuỗi tin nhắn tư vấn tới nhiều users với callback tracking
*
* @param request Thông tin request gửi chuỗi tin nhắn tới nhiều users
* @returns Kết quả gửi tin nhắn cho tất cả users
*/
sendMessageSequenceToMultipleUsers(request: SendMessageSequenceToMultipleUsersRequest): Promise<SendMessageSequenceToMultipleUsersResponse>;
/**
* Gửi tin nhắn tư vấn tùy chỉnh tới nhiều users với callback tracking
* Mỗi user có thể có bộ tin nhắn riêng biệt
*
* @param request Thông tin request gửi tin nhắn tùy chỉnh tới nhiều users
* @returns Kết quả gửi tin nhắn cho tất cả users
*/
sendCustomMessageSequenceToMultipleUsers(request: SendCustomMessageSequenceToMultipleUsersRequest): Promise<SendCustomMessageSequenceToMultipleUsersResponse>;
/**
* Gửi tin nhắn template tổng quát với elements và buttons
* Endpoint: https://openapi.zalo.me/v3.0/oa/message/cs
* Method: POST
*
* @param accessToken Access token của Official Account
* @param userId ID người nhận (user_id)
* @param templateType Loại template (ví dụ: "request_user_info")
* @param elements Mảng elements (tối đa 5 phần tử)
* @param buttons Mảng buttons (tối đa 5 phần tử, optional)
* @returns Thông tin tin nhắn đã gửi
*/
sendTemplateMessage(accessToken: string, userId: string, templateType: string, elements: TemplateElement[], buttons?: TemplateButton[]): Promise<SendMessageResponse>;
/**
* Validate template element theo quy tắc API
* @param element Template element cần validate
* @param index Index của element trong mảng (để báo lỗi)
*/
private validateTemplateElement;
/**
* Validate template button theo quy tắc API
* @param button Template button cần validate
* @param index Index của button trong mảng (để báo lỗi)
*/
private validateTemplateButton;
/**
* Validate template action (cho default_action)
* @param action Template action cần validate
* @param context Context để báo lỗi
*/
private validateTemplateAction;
/**
* Validate button payload theo type
* @param button Template button cần validate
* @param index Index của button trong mảng (để báo lỗi)
*/
private validateButtonPayload;
/**
* Helper function để tạo template element
* @param title Tiêu đề (bắt buộc, ≤ 100 ký tự)
* @param subtitle Tiêu đề phụ (≤ 500 ký tự)
* @param imageUrl URL ảnh (optional)
* @param defaultAction Hành động khi click (optional)
* @returns TemplateElement object
*/
createTemplateElement(title: string, subtitle?: string, imageUrl?: string, defaultAction?: TemplateAction): TemplateElement;
/**
* Helper function để tạo template button với URL
* @param title Tiêu đề button (≤ 100 ký tự)
* @param url URL để mở
* @returns TemplateButton object
*/
createUrlButton(title: string, url: string): TemplateButton;
/**
* Helper function để tạo template button với query (hiển thị)
* @param title Tiêu đề button (≤ 100 ký tự)
* @param payload Dữ liệu callback (≤ 1000 ký tự)
* @returns TemplateButton object
*/
createQueryShowButton(title: string, payload: string): TemplateButton;
/**
* Helper function để tạo template button với query (ẩn)
* @param title Tiêu đề button (≤ 100 ký tự)
* @param payload Dữ liệu callback (≤ 1000 ký tự)
* @returns TemplateButton object
*/
createQueryHideButton(title: string, payload: string): TemplateButton;
/**
* Helper function để tạo template button với SMS
* @param title Tiêu đề button (≤ 100 ký tự)
* @param phoneCode Số điện thoại
* @param content Nội dung SMS (≤ 160 ký tự)
* @returns TemplateButton object
*/
createSmsButton(title: string, phoneCode: string, content?: string): TemplateButton;
/**
* Helper function để tạo template button với Phone
* @param title Tiêu đề button (≤ 100 ký tự)
* @param phoneCode Số điện thoại
* @returns TemplateButton object
*/
createPhoneButton(title: string, phoneCode: string): TemplateButton;
/**
* Helper function để tạo template action với URL
* @param url URL để mở
* @returns TemplateAction object
*/
createUrlAction(url: string): TemplateAction;
/**
* Helper function để tạo template action với query (hiển thị)
* @param payload Dữ liệu callback (≤ 1000 ký tự)
* @returns TemplateAction object
*/
createQueryShowAction(payload: string): TemplateAction;
/**
* Helper function để tạo template action với query (ẩn)
* @param payload Dữ liệu callback (≤ 1000 ký tự)
* @returns TemplateAction object
*/
createQueryHideAction(payload: string): TemplateAction;
/**
* Helper function để tạo template action với SMS
* @param phoneCode Số điện thoại
* @param content Nội dung SMS (≤ 160 ký tự)
* @returns TemplateAction object
*/
createSmsAction(phoneCode: string, content?: string): TemplateAction;
/**
* Helper function để tạo template action với Phone
* @param phoneCode Số điện thoại
* @returns TemplateAction object
*/
createPhoneAction(phoneCode: string): TemplateAction;
/**
* Utility method để sleep/delay
* @param ms Thời gian delay tính bằng milliseconds
*/
private sleep;
}
//# sourceMappingURL=consultation.service.d.ts.map