@warriorteam/redai-zalo-sdk/docs/BUTTON_TYPES_GUIDE.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

# Button Types Guide - Zalo Promotion API v3.0

## Tổng quan

Zalo Promotion API v3.0 hỗ trợ 5 loại button với payload format khác nhau. Mỗi button type có cấu trúc payload riêng biệt và giới hạn cụ thể.

## Button Types được hỗ trợ

### 1. **Open URL Button** (`oa.open.url`)

Mở URL trong ứng dụng Zalo khi người dùng bấm vào.

```typescript
interface OpenUrlButton {
  title: string; // Max 100 characters
  image_icon?: string;
  type: "oa.open.url";
  payload: {
    url: string; // URL to open
  };
}
```

**Example:**
```typescript
{
  title: "Mua ngay",
  type: "oa.open.url",
  payload: {
    url: "https://shop.example.com/product/123"
  }
}
```

### 2. **Query Show Button** (`oa.query.show`)

Gửi tin nhắn từ user đến OA, tin nhắn **hiển thị** trên chat.

```typescript
interface QueryShowButton {
  title: string; // Max 100 characters
  image_icon?: string;
  type: "oa.query.show";
  payload: string; // Max 1000 characters
}
```

**Example:**
```typescript
{
  title: "Xem thêm sản phẩm",
  type: "oa.query.show",
  payload: "#xem_san_pham"
}
```

### 3. **Query Hide Button** (`oa.query.hide`)

Gửi tin nhắn từ user đến OA, tin nhắn **ẩn** trên chat.

```typescript
interface QueryHideButton {
  title: string; // Max 100 characters
  image_icon?: string;
  type: "oa.query.hide";
  payload: string; // Max 1000 characters
}
```

**Example:**
```typescript
{
  title: "Liên hệ tư vấn",
  type: "oa.query.hide",
  payload: "#tu_van"
}
```

### 4. **Open SMS Button** (`oa.open.sms`)

Mở ứng dụng SMS với nội dung và số điện thoại có sẵn.

```typescript
interface OpenSmsButton {
  title: string; // Max 100 characters
  image_icon?: string;
  type: "oa.open.sms";
  payload: {
    content: string; // Max 160 characters
    phone_code: string; // Phone number
  };
}
```

**Example:**
```typescript
{
  title: "Gửi SMS",
  type: "oa.open.sms",
  payload: {
    content: "Tôi muốn tư vấn về sản phẩm",
    phone_code: "84919018791"
  }
}
```

### 5. **Open Phone Button** (`oa.open.phone`)

Mở ứng dụng gọi điện với số điện thoại có sẵn.

```typescript
interface OpenPhoneButton {
  title: string; // Max 100 characters
  image_icon?: string;
  type: "oa.open.phone";
  payload: {
    phone_code: string; // Phone number
  };
}
```

**Example:**
```typescript
{
  title: "Gọi ngay",
  type: "oa.open.phone",
  payload: {
    phone_code: "84919018791"
  }
}
```

## Union Type cho TypeScript

```typescript
type PromotionButton = 
  | OpenUrlButton 
  | QueryShowButton 
  | QueryHideButton 
  | OpenSmsButton 
  | OpenPhoneButton;
```

## Flexible Input Interface

Để dễ sử dụng, SDK cung cấp interface linh hoạt:

```typescript
interface PromotionButtonInput {
  title: string; // Max 100 characters
  imageIcon?: string; // camelCase style
  type: "oa.open.url" | "oa.query.show" | "oa.query.hide" | "oa.open.sms" | "oa.open.phone";
  payload: any; // Flexible payload, will be converted internally
}
```

## Cách sử dụng trong SDK

### Basic Usage

```typescript
const buttons: PromotionButtonInput[] = [
  {
    title: "Mua ngay",
    type: "oa.open.url",
    payload: { url: "https://shop.example.com" }
  },
  {
    title: "Tư vấn",
    type: "oa.query.hide",
    payload: "#tu_van"
  },
  {
    title: "Gọi hotline",
    type: "oa.open.phone",
    payload: { phone_code: "1900123456" }
  }
];

await promotionService.sendCustomPromotion(
  accessToken,
  { user_id: "user_id" },
  {
    // ... other promotion data
    buttons
  }
);
```

### All Button Types Example

```typescript
const allButtonTypes: PromotionButtonInput[] = [
  // Open URL
  {
    title: "Mở website",
    type: "oa.open.url",
    payload: { url: "https://example.com" }
  },
  
  // Query Show (visible message)
  {
    title: "Xem menu",
    type: "oa.query.show",
    payload: "#menu"
  },
  
  // Query Hide (hidden message)
  {
    title: "Liên hệ support",
    type: "oa.query.hide",
    payload: "#support"
  },
  
  // Open SMS
  {
    title: "Gửi SMS",
    type: "oa.open.sms",
    payload: {
      content: "Tôi cần hỗ trợ",
      phone_code: "84919018791"
    }
  },
  
  // Open Phone
  {
    title: "Gọi điện",
    type: "oa.open.phone",
    payload: { phone_code: "84919018791" }
  }
];
```

## Giới hạn và Lưu ý

### Giới hạn chung
- **Tối đa 4 buttons** per message
- **Title**: Tối đa 100 ký tự
- **Image icon**: URL, attachment_id, hoặc "default"

### Giới hạn theo type
- **Query payload**: Tối đa 1000 ký tự
- **SMS content**: Tối đa 160 ký tự
- **Phone code**: Format quốc tế (VD: 84919018791)

### Best Practices

1. **Button Order**: Đặt button quan trọng nhất đầu tiên
2. **Title Length**: Giữ title ngắn gọn, dễ hiểu
3. **Query Payload**: Sử dụng prefix # để dễ phân biệt
4. **Phone Format**: Luôn sử dụng mã quốc gia
5. **URL Validation**: Đảm bảo URL hợp lệ và accessible

### Error Handling

SDK tự động convert và validate button format. Các lỗi thường gặp:

- **Invalid type**: Type không được hỗ trợ
- **Missing payload**: Payload bị thiếu hoặc sai format
- **Length exceeded**: Title hoặc payload vượt quá giới hạn
- **Invalid URL**: URL không hợp lệ cho oa.open.url

## Migration từ Generic Button

Nếu bạn đang sử dụng generic button format:

```typescript
// Cũ (vẫn hoạt động)
{
  title: "Button",
  type: "oa.open.url",
  payload: { url: "https://example.com" }
}

// Mới (recommended)
{
  title: "Button",
  type: "oa.open.url" as const, // Type assertion for better typing
  payload: { url: "https://example.com" }
}
```

SDK sẽ tự động convert và validate tất cả button formats để đảm bảo tương thích với Zalo API v3.0.