@warriorteam/redai-zalo-sdk 1.28.1 → 1.30.0

package/CHANGELOG.md

@@ -2,6 +2,137 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.30.0] - 2025-01-05
+
+### ✨ Added - Template Message Support for ConsultationService
+
+#### 🎯 New Core Function
+- **`sendTemplateMessage()`** - Comprehensive template message function with full elements and buttons support
+- Support for all Zalo OA template types with complete API specification compliance
+- Type-safe template creation with comprehensive validation
+
+#### 🛠️ Helper Functions (12 new functions)
+- **Template Elements**: `createTemplateElement()` - Create template elements with validation
+- **Template Buttons**:
+  - `createUrlButton()` - Create URL buttons (oa.open.url)
+  - `createQueryShowButton()` - Create query show buttons (oa.query.show)
+  - `createQueryHideButton()` - Create query hide buttons (oa.query.hide)
+  - `createSmsButton()` - Create SMS buttons (oa.open.sms)
+  - `createPhoneButton()` - Create phone call buttons (oa.open.phone)
+- **Template Actions**:
+  - `createUrlAction()` - Create URL actions for elements
+  - `createQueryShowAction()` - Create query show actions
+  - `createQueryHideAction()` - Create query hide actions
+  - `createSmsAction()` - Create SMS actions
+  - `createPhoneAction()` - Create phone call actions
+
+#### 📋 TypeScript Interfaces
+- **`TemplateElement`** - Interface for template elements with validation rules
+- **`TemplateButton`** - Interface for template buttons with type-specific payloads
+- **`TemplateAction`** - Interface for template actions (default_action in elements)
+- **`ConsultationTemplatePayload`** - Union type for all payload types
+- **`UrlPayload`**, **`SmsPayload`**, **`PhonePayload`** - Specific payload interfaces
+
+#### ✅ API Specification Compliance
+- **Elements**: Maximum 5 elements, first element must have subtitle
+- **Buttons**: Maximum 5 buttons with comprehensive validation
+- **Title**: ≤ 100 characters validation
+- **Subtitle**: ≤ 500 characters validation (required for first element)
+- **Payload**: ≤ 1000 characters for string payloads
+- **SMS Content**: ≤ 160 characters validation
+- **Action Types**: Full support for all Zalo OA action types
+
+#### 🔧 Validation & Error Handling
+- Comprehensive input validation before API calls
+- Detailed error messages with context information
+- Type-safe development experience with TypeScript
+- Runtime validation for all API specification rules
+
+#### 📁 New Files
+- `src/types/consultation.ts` - Complete TypeScript interfaces for consultation service
+- `examples/consultation-template-example.ts` - Comprehensive usage examples
+- `CONSULTATION-TEMPLATE-ENHANCEMENT.md` - Detailed documentation
+
+#### 🔄 Updated Files
+- `src/services/consultation.service.ts` - Added template message functions
+- `src/index.ts` - Export new consultation types
+
+### 🎯 Use Cases Supported
+- **Customer Support Templates** - Multi-element templates with various action buttons
+- **Information Request Templates** - Templates requesting user information with callbacks
+- **Interactive Templates** - Templates with URL, SMS, phone, and query actions
+- **Marketing Templates** - Templates with multiple call-to-action buttons
+- **Service Templates** - Templates for service interactions and support
+
+### 💡 Developer Experience Improvements
+- **Type Safety**: Full TypeScript support with comprehensive interfaces
+- **IntelliSense**: Complete autocomplete support for all template properties
+- **Validation**: Automatic validation with clear error messages
+- **Helper Functions**: Easy-to-use functions for creating template components
+- **Documentation**: Comprehensive examples and API documentation
+
+## [1.29.0] - 2025-01-05
+
+### 🚀 Major Type Safety Improvements
+
+#### ZNS Service Type Safety Enhancement
+- **Feature**: Completely removed `any` types from ZNS Service validation functions
+- **Impact**: Full type safety for all ZNS template components and validation
+- **Benefits**: Better IDE support, compile-time error detection, improved developer experience
+
+#### New Type Definitions Added
+- `ZNSValidationComponent` - Union type for all ZNS components
+- `ZNSTitleComponent` - Type-safe TITLE component (9-65 chars, max 4 params)
+- `ZNSParagraphComponent` - Type-safe PARAGRAPH component (9-400 chars, max 10 params)
+- `ZNSOTPComponent` - Type-safe OTP component (1-10 chars)
+- `ZNSTableComponent` & `ZNSTableRow` - Type-safe TABLE component (2-8 rows)
+- `ZNSLogoComponent` - Type-safe LOGO component with light/dark attachments
+- `ZNSImagesComponent` - Type-safe IMAGES component (1-3 attachments)
+- `ZNSButtonsComponent` & `ZNSButtonItem` - Type-safe BUTTONS component (1-2 buttons)
+- `ZNSPaymentComponent` - Type-safe PAYMENT component with bank details
+- `ZNSVoucherComponent` - Type-safe VOUCHER component with display options
+- `ZNSRatingComponent` & `ZNSRatingItem` - Type-safe RATING component (exactly 5 items)
+- `ZNSAttachment` - Type-safe attachment object for images
+
+#### Updated Validation Functions
+All validation functions now use specific types instead of `any`:
+- `validateLayoutStructure()` - Uses `ZNSValidationComponent[]`
+- `validateTitleComponent()` - Uses `ZNSTitleComponent`
+- `validateParagraphComponent()` - Uses `ZNSParagraphComponent`
+- `validateOTPComponent()` - Uses `ZNSOTPComponent`
+- `validateTableComponent()` - Uses `ZNSTableComponent`
+- `validateLogoComponent()` - Uses `ZNSLogoComponent`
+- `validateImagesComponent()` - Uses `ZNSImagesComponent`
+- `validateButtonsComponent()` - Uses `ZNSButtonsComponent`
+- `validatePaymentComponent()` - Uses `ZNSPaymentComponent`
+- `validateVoucherComponent()` - Uses `ZNSVoucherComponent`
+- `validateRatingComponent()` - Uses `ZNSRatingComponent`
+- `validateAttachment()` - Uses `ZNSAttachment`
+
+#### Developer Experience Improvements
+- **IntelliSense**: Full autocomplete support for all ZNS components
+- **Error Detection**: Compile-time validation of component structures
+- **Type Safety**: Eliminated runtime errors from incorrect component usage
+- **Documentation**: Type definitions serve as inline documentation
+
+#### Files Added/Modified
+- `src/types/zns.ts` - Added comprehensive component type definitions
+- `src/services/zns.service.ts` - Updated all validation functions with proper types
+- `examples/zns-validation-example.ts` - Complete usage examples for all template types
+- `ZNS-TYPE-IMPROVEMENTS.md` - Detailed documentation of improvements
+
+#### Migration Guide
+Existing code continues to work, but developers can now benefit from:
+```typescript
+// Before: No type safety
+const component: any = { TITLE: { value: "Hello" } };
+
+// After: Full type safety
+const component: ZNSValidationComponent = {
+  TITLE: { value: "Hello {{customer_name}}!" }
+};
+```
+
 ## [1.27.3] - 2025-08-31
 
 ### 🐛 Critical Bug Fixes

package/ZNS-TYPE-IMPROVEMENTS.md

@@ -0,0 +1,220 @@
+# ZNS Service Type Improvements
+
+## Tổng quan
+
+Đã cập nhật ZNS Service để sử dụng các type cụ thể thay vì `any` type, cải thiện type safety và developer experience.
+
+## Những thay đổi chính
+
+### 1. Thêm các interface validation components mới trong `src/types/zns.ts`
+
+```typescript
+// Attachment object cho LOGO và IMAGES
+export interface ZNSAttachment {
+  type: "IMAGE";
+  media_id: string;
+}
+
+// TITLE component
+export interface ZNSTitleComponent {
+  value: string; // 9-65 ký tự, tối đa 4 params
+}
+
+// PARAGRAPH component  
+export interface ZNSParagraphComponent {
+  value: string; // 9-400 ký tự, tối đa 10 params
+}
+
+// OTP component
+export interface ZNSOTPComponent {
+  value: string; // 1-10 ký tự
+}
+
+// TABLE component
+export interface ZNSTableComponent {
+  rows: ZNSTableRow[]; // 2-8 rows
+}
+
+export interface ZNSTableRow {
+  title: string; // 3-36 ký tự, chỉ text cố định
+  value: string; // 3-90 ký tự, có thể có params
+  row_type?: 0 | 1 | 2 | 3 | 4 | 5; // Hiệu ứng row
+}
+
+// LOGO component
+export interface ZNSLogoComponent {
+  light: ZNSAttachment;
+  dark: ZNSAttachment;
+}
+
+// IMAGES component
+export interface ZNSImagesComponent {
+  items: ZNSAttachment[]; // 1-3 attachments
+}
+
+// BUTTONS component
+export interface ZNSButtonsComponent {
+  items: ZNSButtonItem[]; // 1-2 buttons
+}
+
+export interface ZNSButtonItem {
+  type: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9; // Button types
+  title: string; // 5-30 ký tự, chỉ text cố định
+  content: string; // URL/phone, có thể có params
+}
+
+// PAYMENT component
+export interface ZNSPaymentComponent {
+  bank_code: string; // Bank code cố định
+  account_name: string; // 1-100 ký tự, text cố định
+  bank_account: string; // 1-100 ký tự, text cố định
+  amount: string | number; // Số tiền hoặc param
+  note?: string; // 1-90 ký tự, có thể có params
+}
+
+// VOUCHER component
+export interface ZNSVoucherComponent {
+  name: string; // 1-30 ký tự, có thể có params
+  condition: string; // 1-40 ký tự, có thể có params
+  start_date?: string; // Có thể có params
+  end_date: string; // Có thể có params
+  voucher_code: string; // 1-25 ký tự, có thể có params
+  display_code?: 1 | 2 | 3; // QR code, Bar code, Text only
+}
+
+// RATING component
+export interface ZNSRatingComponent {
+  items: ZNSRatingItem[]; // Đúng 5 items
+}
+
+export interface ZNSRatingItem {
+  star: 1 | 2 | 3 | 4 | 5; // Số sao
+  title: string; // 1-50 ký tự
+  question?: string; // 1-100 ký tự
+  answers?: string[]; // 1-5 câu trả lời, mỗi câu 1-50 ký tự
+  thanks: string; // 1-100 ký tự
+  description: string; // 1-200 ký tự
+}
+
+// Union type cho tất cả các component
+export type ZNSValidationComponent = 
+  | { TITLE: ZNSTitleComponent }
+  | { PARAGRAPH: ZNSParagraphComponent }
+  | { OTP: ZNSOTPComponent }
+  | { TABLE: ZNSTableComponent }
+  | { LOGO: ZNSLogoComponent }
+  | { IMAGES: ZNSImagesComponent }
+  | { BUTTONS: ZNSButtonsComponent }
+  | { PAYMENT: ZNSPaymentComponent }
+  | { VOUCHER: ZNSVoucherComponent }
+  | { RATING: ZNSRatingComponent };
+```
+
+### 2. Cập nhật ZNS Service validation functions
+
+Tất cả các function validation trong `src/services/zns.service.ts` đã được cập nhật để sử dụng type cụ thể:
+
+- `validateLayoutStructure()`: Sử dụng `ZNSValidationComponent[]` thay vì `any[]`
+- `isHeaderComponent()`, `isBodyComponent()`, `isFooterComponent()`: Sử dụng `ZNSValidationComponent`
+- `validateComponent()`: Sử dụng `ZNSValidationComponent`
+- `validateTitleComponent()`: Sử dụng `ZNSTitleComponent`
+- `validateParagraphComponent()`: Sử dụng `ZNSParagraphComponent`
+- `validateOTPComponent()`: Sử dụng `ZNSOTPComponent`
+- `validateTableComponent()`: Sử dụng `ZNSTableComponent`
+- `validateLogoComponent()`: Sử dụng `ZNSLogoComponent`
+- `validateImagesComponent()`: Sử dụng `ZNSImagesComponent`
+- `validateButtonsComponent()`: Sử dụng `ZNSButtonsComponent`
+- `validatePaymentComponent()`: Sử dụng `ZNSPaymentComponent`
+- `validateVoucherComponent()`: Sử dụng `ZNSVoucherComponent`
+- `validateRatingComponent()`: Sử dụng `ZNSRatingComponent`
+- `validateAttachment()`: Sử dụng `ZNSAttachment`
+
+### 3. Lợi ích của việc cập nhật
+
+#### Type Safety
+- Loại bỏ hoàn toàn việc sử dụng `any` type
+- IDE có thể detect lỗi type ngay khi code
+- Autocomplete tốt hơn khi viết code
+
+#### Developer Experience
+- IntelliSense hiển thị đúng các property có sẵn
+- Validation tự động khi compile TypeScript
+- Dễ dàng refactor code mà không lo lỗi runtime
+
+#### Maintainability
+- Code dễ đọc và hiểu hơn
+- Ít bug hơn do type checking
+- Dễ dàng thêm feature mới
+
+### 4. Ví dụ sử dụng
+
+Xem file `examples/zns-validation-example.ts` để biết cách sử dụng các type mới.
+
+#### Trước khi cập nhật:
+```typescript
+// Không có type safety
+private validateTitleComponent(title: any): void {
+  if (!title.value || typeof title.value !== 'string') {
+    // Có thể có lỗi runtime nếu title không đúng cấu trúc
+  }
+}
+```
+
+#### Sau khi cập nhật:
+```typescript
+// Type safety đầy đủ
+private validateTitleComponent(title: ZNSTitleComponent): void {
+  if (!title.value || typeof title.value !== 'string') {
+    // IDE sẽ báo lỗi ngay nếu title không đúng type
+  }
+}
+```
+
+### 5. Cách sử dụng trong dự án
+
+```typescript
+import { 
+  ZNSValidationComponent,
+  ZNSTitleComponent,
+  ZNSButtonsComponent 
+} from "./src/types/zns";
+
+// Tạo component với type safety
+const titleComponent: ZNSValidationComponent = {
+  TITLE: {
+    value: "Xin chào {{customer_name}}!"
+  }
+};
+
+const buttonsComponent: ZNSValidationComponent = {
+  BUTTONS: {
+    items: [
+      {
+        type: 1, // URL
+        title: "Xem chi tiết",
+        content: "https://example.com"
+      }
+    ]
+  }
+};
+```
+
+### 6. Migration Guide
+
+Nếu bạn đang sử dụng code cũ với `any` type:
+
+1. Import các type mới từ `src/types/zns`
+2. Thay thế `any` bằng type cụ thể tương ứng
+3. TypeScript compiler sẽ báo lỗi nếu có vấn đề về type
+4. Fix các lỗi type để đảm bảo code chạy đúng
+
+### 7. Kết luận
+
+Việc cập nhật này giúp:
+- ✅ Loại bỏ hoàn toàn `any` type
+- ✅ Cải thiện type safety
+- ✅ Tăng developer experience
+- ✅ Giảm bugs và lỗi runtime
+- ✅ Code dễ maintain hơn
+
+Tất cả validation functions trong ZNS Service giờ đây đều có type safety đầy đủ và tuân thủ đúng chuẩn TypeScript best practices.

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export * from "./types/zns";
 export * from "./types/article";
 export * from "./types/broadcast";
 export * from "./types/promotion";
+export * from "./types/consultation";
 export * from "./constants/zns.constants";
 export type { BaseMessage, TextMessage, ImageMessage, FileMessage, StickerMessage, TemplateMessage as MessageTemplateMessage, ReactionMessage as MessageReactionMessage, Message, MessageRecipient, SendMessageRequest, SendMessageResponse, UploadFileResponse, MessageStatus, MessageEvent, ConsultationTextMessage, ConsultationImageMessage, ConsultationFileMessage, ConsultationStickerMessage, ConsultationQuoteMessage, ConsultationRequestInfoMessage, TransactionMessage, AnonymousTextMessage, AnonymousImageMessage, AnonymousFileMessage, AnonymousStickerMessage, MiniAppMessage, ExtendedMessage, } from "./types/message";
 export * from "./types/webhook";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -34,6 +34,7 @@ __exportStar(require("./types/zns"), exports);
 __exportStar(require("./types/article"), exports);
 __exportStar(require("./types/broadcast"), exports);
 __exportStar(require("./types/promotion"), exports);
+__exportStar(require("./types/consultation"), exports);
 // Export ZNS constants and helpers
 __exportStar(require("./constants/zns.constants"), exports);
 // Export webhook types (avoiding conflicts with message and group types)

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;;;;;;;;;;;;;;;AAEH,eAAe;AACf,iDAA+B;AAC/B,+CAA6B;AAC7B,6CAA2B;AAC3B,+CAA6B;AAC7B,8CAA4B;AAC5B,kDAAgC;AAChC,oDAAkC;AAClC,oDAAkC;AAElC,mCAAmC;AACnC,4DAA0C;AAkC1C,yEAAyE;AACzE,kDAAgC;AAEhC,yEAAyE;AACzE,mDAoB6B;AAlB3B,uHAAA,wBAAwB,OAAA;AACxB,wHAAA,yBAAyB,OAAA;AACzB,wHAAA,yBAAyB,OAAA;AACzB,wHAAA,yBAAyB,OAAA;AACzB,uHAAA,wBAAwB,OAAA;AACxB,sHAAA,uBAAuB,OAAA;AACvB,gHAAA,iBAAiB,OAAA;AACjB,iHAAA,kBAAkB,OAAA;AAClB,gHAAA,iBAAiB,OAAA;AACjB,mHAAA,oBAAoB,OAAA;AACpB,+GAAA,gBAAgB,OAAA;AAChB,qHAAA,sBAAsB,OAAA;AACtB,sHAAA,uBAAuB,OAAA;AACvB,qHAAA,sBAAsB,OAAA;AACtB,wHAAA,yBAAyB,OAAA;AACzB,oHAAA,qBAAqB,OAAA;AACrB,0GAAA,WAAW,OAAA;AACX,6GAAA,cAAc,OAAA;AAEhB,kCAAkC;AAClC,2CAMyB;AALvB,6GAAA,kBAAkB,OAAA;AAClB,8GAAA,mBAAmB,OAAA;AACnB,iHAAA,sBAAsB,OAAA;AACtB,kHAAA,uBAAuB,OAAA;AACvB,8GAAA,mBAAmB,OAAA;AAoFrB,iBAAiB;AACjB,qDAAmD;AAA1C,yGAAA,UAAU,OAAA;AACnB,qDAAmD;AAA1C,yGAAA,UAAU,OAAA;AAEnB,kBAAkB;AAClB,wDAAsD;AAA7C,2GAAA,WAAW,OAAA;AACpB,oDAAkD;AAAzC,uGAAA,SAAS,OAAA;AAClB,2GAA2G;AAC3G,wDAAsD;AAA7C,2GAAA,WAAW,OAAA;AACpB,+DAA+D;AAC/D,sDAAoD;AAA3C,yGAAA,UAAU,OAAA;AACnB,0EAAuE;AAA9D,4HAAA,mBAAmB,OAAA;AAC5B,gFAA6E;AAApE,kIAAA,sBAAsB,OAAA;AAC/B,8DAA4D;AAAnD,iHAAA,cAAc,OAAA;AACvB,wEAAqE;AAA5D,0HAAA,kBAAkB,OAAA;AAE3B,iDAAiD;AACjD,wEAAsE;AAA7D,2HAAA,mBAAmB,OAAA;AAC5B,sEAAoE;AAA3D,yHAAA,kBAAkB,OAAA;AAC3B,kEAAgE;AAAvD,qHAAA,gBAAgB,OAAA;AACzB,8EAA2E;AAAlE,gIAAA,qBAAqB,OAAA;AAC9B,oFAQ+C;AAP7C,sIAAA,wBAAwB,OAAA;AAQ1B,kEAAgE;AAAvD,qHAAA,gBAAgB,OAAA;AAEzB,wBAAwB;AACxB,uCAAqC;AAA5B,mGAAA,OAAO,OAAA;AAEhB,iBAAiB;AACjB,uCAAgD;AAAvC,mGAAA,OAAO,OAAW"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;;;;;;;;;;;;;;;AAEH,eAAe;AACf,iDAA+B;AAC/B,+CAA6B;AAC7B,6CAA2B;AAC3B,+CAA6B;AAC7B,8CAA4B;AAC5B,kDAAgC;AAChC,oDAAkC;AAClC,oDAAkC;AAClC,uDAAqC;AAErC,mCAAmC;AACnC,4DAA0C;AAkC1C,yEAAyE;AACzE,kDAAgC;AAEhC,yEAAyE;AACzE,mDAoB6B;AAlB3B,uHAAA,wBAAwB,OAAA;AACxB,wHAAA,yBAAyB,OAAA;AACzB,wHAAA,yBAAyB,OAAA;AACzB,wHAAA,yBAAyB,OAAA;AACzB,uHAAA,wBAAwB,OAAA;AACxB,sHAAA,uBAAuB,OAAA;AACvB,gHAAA,iBAAiB,OAAA;AACjB,iHAAA,kBAAkB,OAAA;AAClB,gHAAA,iBAAiB,OAAA;AACjB,mHAAA,oBAAoB,OAAA;AACpB,+GAAA,gBAAgB,OAAA;AAChB,qHAAA,sBAAsB,OAAA;AACtB,sHAAA,uBAAuB,OAAA;AACvB,qHAAA,sBAAsB,OAAA;AACtB,wHAAA,yBAAyB,OAAA;AACzB,oHAAA,qBAAqB,OAAA;AACrB,0GAAA,WAAW,OAAA;AACX,6GAAA,cAAc,OAAA;AAEhB,kCAAkC;AAClC,2CAMyB;AALvB,6GAAA,kBAAkB,OAAA;AAClB,8GAAA,mBAAmB,OAAA;AACnB,iHAAA,sBAAsB,OAAA;AACtB,kHAAA,uBAAuB,OAAA;AACvB,8GAAA,mBAAmB,OAAA;AAoFrB,iBAAiB;AACjB,qDAAmD;AAA1C,yGAAA,UAAU,OAAA;AACnB,qDAAmD;AAA1C,yGAAA,UAAU,OAAA;AAEnB,kBAAkB;AAClB,wDAAsD;AAA7C,2GAAA,WAAW,OAAA;AACpB,oDAAkD;AAAzC,uGAAA,SAAS,OAAA;AAClB,2GAA2G;AAC3G,wDAAsD;AAA7C,2GAAA,WAAW,OAAA;AACpB,+DAA+D;AAC/D,sDAAoD;AAA3C,yGAAA,UAAU,OAAA;AACnB,0EAAuE;AAA9D,4HAAA,mBAAmB,OAAA;AAC5B,gFAA6E;AAApE,kIAAA,sBAAsB,OAAA;AAC/B,8DAA4D;AAAnD,iHAAA,cAAc,OAAA;AACvB,wEAAqE;AAA5D,0HAAA,kBAAkB,OAAA;AAE3B,iDAAiD;AACjD,wEAAsE;AAA7D,2HAAA,mBAAmB,OAAA;AAC5B,sEAAoE;AAA3D,yHAAA,kBAAkB,OAAA;AAC3B,kEAAgE;AAAvD,qHAAA,gBAAgB,OAAA;AACzB,8EAA2E;AAAlE,gIAAA,qBAAqB,OAAA;AAC9B,oFAQ+C;AAP7C,sIAAA,wBAAwB,OAAA;AAQ1B,kEAAgE;AAAvD,qHAAA,gBAAgB,OAAA;AAEzB,wBAAwB;AACxB,uCAAqC;AAA5B,mGAAA,OAAO,OAAA;AAEhB,iBAAiB;AACjB,uCAAgD;AAAvC,mGAAA,OAAO,OAAW"}

package/dist/services/consultation.service.d.ts

@@ -1,152 +1,6 @@
 import { ZaloClient } from "../clients/zalo-client";
 import { MessageRecipient, SendMessageResponse, TextMessage, ConsultationQuoteMessage } from "../types/message";
-/**
- * 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?: SendMessageResponse;
-        /** 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;
-    };
-}
+import { TemplateAction, TemplateElement, TemplateButton, SendMessageSequenceRequest, SendMessageSequenceResponse, SendMessageSequenceToMultipleUsersRequest, SendMessageSequenceToMultipleUsersResponse } from "../types/consultation";
 /**
  * Service xử lý các API tin nhắn tư vấn của Zalo Official Account
  *
@@ -328,6 +182,119 @@ export declare class ConsultationService {
      * @returns Kết quả gửi tin nhắn cho tất cả users
      */
     sendMessageSequenceToMultipleUsers(request: SendMessageSequenceToMultipleUsersRequest): Promise<SendMessageSequenceToMultipleUsersResponse>;
+    /**
+     * 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