@warriorteam/redai-zalo-sdk/docs/API_REFERENCE.md

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

# RedAI Zalo SDK - API Reference

## Tổng quan

RedAI Zalo SDK cung cấp các API hoàn chỉnh để tích hợp với các dịch vụ của Zalo, bao gồm Official Account, ZNS, Social API, và nhiều dịch vụ khác.

## Cấu trúc SDK

```typescript
import { ZaloSDK } from "@warriorteam/redai-zalo-sdk";

const zalo = new ZaloSDK({
  appId: "your-app-id",
  appSecret: "your-app-secret",
  debug: true
});
```

---

## ZaloSDK Class

### Constructor

```typescript
constructor(config: ZaloSDKConfig)
```

#### ZaloSDKConfig

```typescript
interface ZaloSDKConfig {
  appId: string;                    // App ID từ Zalo Developer
  appSecret: string;                // App Secret từ Zalo Developer
  timeout?: number;                 // Timeout cho request (mặc định: 30000ms)
  debug?: boolean;                  // Bật chế độ debug (mặc định: false)
  apiBaseUrl?: string;              // Base URL API (mặc định: https://openapi.zalo.me)
  retry?: {
    attempts?: number;              // Số lần retry (mặc định: 3)
    delay?: number;                 // Delay giữa các retry (mặc định: 1000ms)
  };
}
```

### Quick Methods

#### getOAAccessToken()
```typescript
async getOAAccessToken(code: string, redirectUri: string): Promise<AccessToken>
```
Lấy access token cho Official Account từ authorization code.

#### getSocialAccessToken()
```typescript
async getSocialAccessToken(code: string, redirectUri: string, codeVerifier?: string): Promise<AccessToken>
```
Lấy access token cho Social API từ authorization code.

#### refreshOAAccessToken()
```typescript
async refreshOAAccessToken(refreshToken: string): Promise<AccessToken>
```
Refresh access token cho Official Account.

#### refreshSocialAccessToken()
```typescript
async refreshSocialAccessToken(refreshToken: string): Promise<AccessToken>
```
Refresh access token cho Social API.

---

## AuthService

Xử lý authentication flows và quản lý token.

### Methods

#### createOAAuthUrl()
```typescript
createOAAuthUrl(redirectUri: string, state?: string): string
```
Tạo URL authorization cho Official Account.

#### createSocialAuthUrl()
```typescript
createSocialAuthUrl(redirectUri: string, state?: string): string
```
Tạo URL authorization cho Social API.

#### getOAAccessToken()
```typescript
async getOAAccessToken(params: AuthCodeParams): Promise<AccessToken>
```

#### getSocialAccessToken()
```typescript
async getSocialAccessToken(params: AuthCodeParams): Promise<AccessToken>
```

#### getSocialUserInfo()
```typescript
async getSocialUserInfo(accessToken: string, fields?: string): Promise<SocialUserInfo>
```

#### generatePKCE()
```typescript
generatePKCE(): PKCEConfig
```
Tạo PKCE cho Social API authorization.

#### validateAccessToken()
```typescript
async validateAccessToken(accessToken: string): Promise<TokenValidation>
```

---

## OAService

Quản lý Official Account information và quota.

### Methods

#### getOAInfo()
```typescript
async getOAInfo(accessToken: string): Promise<OAInfo>
```
Lấy thông tin Official Account.

**Response:**
```typescript
interface OAInfo {
  oa_id: string;
  name: string;
  description: string;
  oa_alias: string;
  is_verified: boolean;
  oa_type: number;
  package_name: string;
  package_valid_through_date: string;
  package_auto_renew_date: string;
  linked_zca: string;
  num_follower: number;
  avatar: string;
  cover: string;
}
```

#### getMessageQuota()
```typescript
async getMessageQuota(accessToken: string): Promise<MessageQuota>
```
Lấy thông tin quota tin nhắn.

#### getQuotaSummary()
```typescript
async getQuotaSummary(accessToken: string): Promise<QuotaSummary>
```
Lấy tổng quan quota chi tiết.

#### validateOAToken()
```typescript
async validateOAToken(accessToken: string): Promise<boolean>
```

---

## ConsultationService

Gửi tin nhắn customer support trong vòng 48 giờ.

### Methods

#### sendTextMessage()
```typescript
async sendTextMessage(
  accessToken: string,
  recipient: MessageRecipient,
  message: ConsultationTextMessage
): Promise<SendMessageResponse>
```

**Ví dụ:**
```typescript
await zalo.consultation.sendTextMessage(accessToken, 
  { user_id: "user-id" },
  { type: "text", text: "Xin chào! Tôi có thể hỗ trợ gì cho bạn?" }
);
```

#### sendImageMessage()
```typescript
async sendImageMessage(
  accessToken: string,
  recipient: MessageRecipient,
  message: ConsultationImageMessage
): Promise<SendMessageResponse>
```

#### sendFileMessage()
```typescript
async sendFileMessage(
  accessToken: string,
  recipient: MessageRecipient,
  message: ConsultationFileMessage
): Promise<SendMessageResponse>
```

#### sendStickerMessage()
```typescript
async sendStickerMessage(
  accessToken: string,
  recipient: MessageRecipient,
  message: ConsultationStickerMessage
): Promise<SendMessageResponse>
```

#### sendQuoteMessage()
```typescript
async sendQuoteMessage(
  accessToken: string,
  recipient: MessageRecipient,
  message: ConsultationQuoteMessage
): Promise<SendMessageResponse>
```

#### sendRequestInfoMessage()
```typescript
async sendRequestInfoMessage(
  accessToken: string,
  recipient: MessageRecipient,
  message: ConsultationRequestInfoMessage
): Promise<SendMessageResponse>
```

---

## ZNSService

Zalo Notification Service - gửi tin nhắn thông báo qua template.

### Methods

#### sendMessage()
```typescript
async sendMessage(
  accessToken: string,
  request: ZNSMessageRequest
): Promise<ZNSMessageResponse>
```

**ZNSMessageRequest:**
```typescript
interface ZNSMessageRequest {
  phone: string;                    // Số điện thoại người nhận
  template_id: string;             // ID template được duyệt
  template_data: Record<string, any>; // Data để fill vào template
  tracking_id?: string;            // ID để tracking (tùy chọn)
  mode?: 'development' | 'production'; // Môi trường (mặc định: production)
}
```

#### getQuotaInfo()
```typescript
async getQuotaInfo(accessToken: string): Promise<ZNSQuotaInfo>
```

#### getTemplateList()
```typescript
async getTemplateList(accessToken: string, params?: ZNSTemplateListParams): Promise<ZNSTemplateListResponse>
```

#### createTemplate()
```typescript
async createTemplate(accessToken: string, template: ZNSTemplateCreate): Promise<ZNSTemplateCreateResponse>
```

#### updateTemplate()
```typescript
async updateTemplate(accessToken: string, templateId: string, template: ZNSTemplateUpdate): Promise<ZNSTemplateUpdateResponse>
```

#### getTemplateStatus()
```typescript
async getTemplateStatus(accessToken: string, templateId: string): Promise<ZNSTemplateStatus>
```

---

## UserService

Quản lý thông tin người dùng Social API.

### Methods

#### getUserInfo()
```typescript
async getUserInfo(accessToken: string, userId: string): Promise<UserInfo>
```

#### getUserList()
```typescript
async getUserList(accessToken: string, request: UserListRequest): Promise<UserListResponse>
```

#### getFollowers()
```typescript
async getFollowers(accessToken: string, params?: FollowersParams): Promise<FollowersResponse>
```

---

## UserManagementService

Quản lý user profiles và interactions.

### Methods

#### getUserProfile()
```typescript
async getUserProfile(accessToken: string, userId: string): Promise<UserManagementProfile>
```

#### updateUserProfile()
```typescript
async updateUserProfile(accessToken: string, userId: string, profile: UserProfileUpdate): Promise<UserManagementProfile>
```

#### getUserInteractions()
```typescript
async getUserInteractions(accessToken: string, userId: string, params?: InteractionParams): Promise<UserInteraction[]>
```

#### getUserAnalytics()
```typescript
async getUserAnalytics(accessToken: string, userId: string): Promise<UserAnalytics>
```

#### searchUsers()
```typescript
async searchUsers(accessToken: string, search: UserSearch): Promise<UserSearchResult>
```

#### bulkUserOperation()
```typescript
async bulkUserOperation(accessToken: string, operation: BulkUserOperation): Promise<BulkOperationResult>
```

---

## TagService

Quản lý user tags và segmentation.

### Methods

#### createTag()
```typescript
async createTag(accessToken: string, tagName: string): Promise<TagCreateResponse>
```

#### deleteTag()
```typescript
async deleteTag(accessToken: string, tagId: string): Promise<TagDeleteResponse>
```

#### tagUser()
```typescript
async tagUser(accessToken: string, userId: string, tags: string[]): Promise<TagUserResponse>
```

#### untagUser()
```typescript
async untagUser(accessToken: string, userId: string, tags: string[]): Promise<UntagUserResponse>
```

#### getUserTags()
```typescript
async getUserTags(accessToken: string, userId: string): Promise<UserTag[]>
```

#### getTagList()
```typescript
async getTagList(accessToken: string): Promise<UserTagList>
```

#### getUsersByTag()
```typescript
async getUsersByTag(accessToken: string, tagId: string, params?: TagUsersParams): Promise<TagUsersResponse>
```

---

## GroupManagementService

Quản lý groups và members.

### Methods

#### getGroupsOfOA()
```typescript
async getGroupsOfOA(accessToken: string, params?: GroupsParams): Promise<GroupsOfOAResponse>
```

#### getGroupDetail()
```typescript
async getGroupDetail(accessToken: string, groupId: string): Promise<GroupDetailResponse>
```

#### getGroupMembers()
```typescript
async getGroupMembers(accessToken: string, groupId: string, params?: GroupMembersParams): Promise<GroupMembersResponse>
```

#### getPendingMembers()
```typescript
async getPendingMembers(accessToken: string, groupId: string): Promise<GroupPendingMembersResponse>
```

#### acceptPendingMembers()
```typescript
async acceptPendingMembers(accessToken: string, request: GroupAcceptPendingMembersRequest): Promise<GroupAcceptPendingMembersResponse>
```

#### removeMembers()
```typescript
async removeMembers(accessToken: string, request: GroupRemoveMembersRequest): Promise<GroupRemoveMembersResponse>
```

---

## GroupMessageService

Gửi tin nhắn đến groups.

### Methods

#### sendTextMessage()
```typescript
async sendTextMessage(accessToken: string, groupId: string, message: GroupTextMessage): Promise<GroupMessageResult>
```

#### sendImageMessage()
```typescript
async sendImageMessage(accessToken: string, groupId: string, message: GroupImageMessage): Promise<GroupMessageResult>
```

#### sendFileMessage()
```typescript
async sendFileMessage(accessToken: string, groupId: string, message: GroupFileMessage): Promise<GroupMessageResult>
```

#### getQuotaMessage()
```typescript
async getQuotaMessage(accessToken: string, request: GroupQuotaMessageRequest): Promise<GroupQuotaMessageResponse>
```

---

## ArticleService

Quản lý articles và content.

### Methods

#### createArticle()
```typescript
async createArticle(accessToken: string, article: ArticleCreateRequest): Promise<ArticleCreateResponse>
```

#### updateArticle()
```typescript
async updateArticle(accessToken: string, articleId: string, article: ArticleUpdateRequest): Promise<ArticleUpdateResponse>
```

#### deleteArticle()
```typescript
async deleteArticle(accessToken: string, articleId: string): Promise<ArticleDeleteResponse>
```

#### getArticle()
```typescript
async getArticle(accessToken: string, articleId: string): Promise<Article>
```

#### getArticleList()
```typescript
async getArticleList(accessToken: string, params?: ArticleListParams): Promise<ArticleListResponse>
```

#### shareArticle()
```typescript
async shareArticle(accessToken: string, userId: string, articleId: string): Promise<ShareArticleResponse>
```

#### uploadImage()
```typescript
async uploadImage(accessToken: string, image: Buffer): Promise<ImageUploadResponse>
```

---

## VideoUploadService

Upload và quản lý video content.

### Methods

#### uploadVideo()
```typescript
async uploadVideo(accessToken: string, video: Buffer, filename: string): Promise<VideoUploadResponse>
```

#### getUploadStatus()
```typescript
async getUploadStatus(accessToken: string, token: string): Promise<VideoUploadStatus>
```

#### waitForUploadCompletion()
```typescript
async waitForUploadCompletion(accessToken: string, token: string, maxAttempts?: number): Promise<VideoUploadComplete>
```

#### sendVideoMessage()
```typescript
async sendVideoMessage(accessToken: string, userId: string, attachmentId: string, message?: string): Promise<SendMessageResponse>
```

---

## TransactionService

Gửi tin nhắn transaction (thanh toán, đơn hàng).

### Methods

#### sendTransactionMessage()
```typescript
async sendTransactionMessage(
  accessToken: string,
  recipient: MessageRecipient,
  message: TransactionMessage
): Promise<SendMessageResponse>
```

---

## PromotionService

Gửi tin nhắn khuyến mại.

### Methods

#### sendPromotionMessage()
```typescript
async sendPromotionMessage(
  accessToken: string,
  recipient: MessageRecipient,
  message: PromotionMessage
): Promise<SendMessageResponse>
```

---

## GeneralMessageService

Gửi tin nhắn general purpose.

### Methods

#### sendResponseMessage()
```typescript
async sendResponseMessage(
  accessToken: string,
  recipient: MessageRecipient,
  message: Message
): Promise<SendMessageResponse>
```

#### sendAnonymousMessage()
```typescript
async sendAnonymousMessage(
  accessToken: string,
  recipient: MessageRecipient,
  message: AnonymousMessage
): Promise<SendMessageResponse>
```

---

## MessageManagementService

Quản lý tin nhắn và analytics.

### Methods

#### getMessageHistory()
```typescript
async getMessageHistory(accessToken: string, params: MessageHistoryParams): Promise<MessageHistoryResponse>
```

#### getMessageAnalytics()
```typescript
async getMessageAnalytics(accessToken: string, params: MessageAnalyticsParams): Promise<MessageAnalytics>
```

#### getMessageStatus()
```typescript
async getMessageStatus(accessToken: string, messageId: string): Promise<MessageStatus>
```

---

## BroadcastService

Gửi tin truyền thông broadcast đến nhiều người dùng.

### Methods

#### sendBroadcastMessage()
```typescript
async sendBroadcastMessage(
  accessToken: string,
  recipient: BroadcastRecipient,
  attachmentId: string
): Promise<BroadcastResponse>
```

#### sendMultipleBroadcastMessages()
```typescript
async sendMultipleBroadcastMessages(
  accessToken: string,
  recipient: BroadcastRecipient,
  attachmentIds: string[],
  options?: {
    delay?: number;
    mode?: 'parallel' | 'sequential';
    onProgress?: (progress: MultipleBroadcastProgress) => void;
  }
): Promise<MultipleBroadcastResult>
```

#### createBroadcastTarget()
```typescript
createBroadcastTarget(criteria: {
  ages?: string[];
  gender?: "ALL" | "MALE" | "FEMALE";
  cities?: string[];
  locations?: ("NORTH" | "CENTRAL" | "SOUTH")[];
  platforms?: ("IOS" | "ANDROID" | "WINDOWS_PHONE")[];
}): BroadcastTarget
```

#### getCityCodes()
```typescript
getCityCodes(): typeof BROADCAST_CITY_CODES
```

#### getAgeGroupCodes()
```typescript
getAgeGroupCodes(): typeof BROADCAST_AGE_CODES
```

#### getGenderCodes()
```typescript
getGenderCodes(): typeof BROADCAST_GENDER_CODES
```

#### getLocationCodes()
```typescript
getLocationCodes(): typeof BROADCAST_LOCATION_CODES
```

#### getPlatformCodes()
```typescript
getPlatformCodes(): typeof BROADCAST_PLATFORM_CODES
```

---

## Error Handling

Tất cả methods có thể throw `ZaloSDKError`:

```typescript
class ZaloSDKError extends Error {
  code: number;         // Mã lỗi từ Zalo API
  details?: any;        // Chi tiết lỗi
  statusCode?: number;  // HTTP status code
}
```

### Common Error Codes

| Code | Description | Giải pháp |
|------|-------------|-----------|
| -216 | Invalid access token | Refresh token hoặc re-authenticate |
| -201 | Invalid parameters | Kiểm tra tham số đầu vào |
| -223 | Quota exceeded | Chờ reset quota hoặc nâng cấp gói |
| -204 | User not found | Kiểm tra user_id |
| -207 | Template not found | Kiểm tra template_id |

---

## Rate Limiting

- **OA Messages**: Theo quota package
- **ZNS Messages**: Theo quota mua
- **API Calls**: Không giới hạn cụ thể, nhưng nên có throttling

---

## Authentication Requirements

| Service | Required Token Type | Scope |
|---------|-------------------|--------|
| AuthService | N/A | N/A |
| OAService | OA Access Token | Official Account |
| ConsultationService | OA Access Token | Official Account |
| ZNSService | OA Access Token | Official Account |
| UserService | Social Access Token | Social API |
| GroupServices | OA Access Token | Official Account |
| All Message Services | OA Access Token | Official Account |

---

## Best Practices

1. **Token Management**: Luôn refresh token trước khi hết hạn
2. **Error Handling**: Implement retry logic với exponential backoff
3. **Rate Limiting**: Implement throttling để tránh hit limit
4. **Logging**: Enable debug mode trong development
5. **Security**: Không log access token hoặc sensitive data
6. **Testing**: Sử dụng development mode cho ZNS khi test

---

## Migration Notes

### From v1.1.x to v1.2.x
- Added new message services (Consultation, Transaction, Promotion)
- Deprecated MessageService, use specialized services instead
- Added VideoUploadService
- Enhanced error handling

Xem [CHANGELOG.md](../CHANGELOG.md) để biết chi tiết về các thay đổi.