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

# Webhook Message Helper Functions

Tài liệu này mô tả các hàm helper để phân biệt các loại sự kiện tin nhắn trong Zalo webhook.

## Tổng quan

RedAI Zalo SDK cung cấp các hàm helper để dễ dàng phân biệt các loại sự kiện tin nhắn:

1. **Tin nhắn từ người dùng cá nhân** - `isUserMessageEvent()`
2. **Tin nhắn từ group** - `isGroupMessageEvent()`  
3. **Tin nhắn OA gửi cho cá nhân** - `isOAToUserMessageEvent()`
4. **Tin nhắn OA gửi tới group** - `isOAToGroupMessageEvent()`
5. **Xác định hướng và đích của tin nhắn** - `getMessageDirection()`

## Import

```typescript
import {
  isUserMessageEvent,
  isGroupMessageEvent,
  isOAToUserMessageEvent,
  isOAToGroupMessageEvent,
  getMessageDirection,
  WebhookEvent,
} from '@warriorteam/redai-zalo-sdk';
```

## Sử dụng

### 1. Phân biệt tin nhắn từ người dùng cá nhân

```typescript
function handleWebhook(event: WebhookEvent) {
  if (isUserMessageEvent(event)) {
    console.log('Nhận được tin nhắn từ người dùng cá nhân');
    console.log('Sender:', event.sender.id);
    console.log('Content:', event.message.text);
    
    // Xử lý tin nhắn từ user cá nhân
    handleUserMessage(event);
  }
}
```

### 2. Phân biệt tin nhắn từ group

```typescript
function handleWebhook(event: WebhookEvent) {
  if (isGroupMessageEvent(event)) {
    console.log('Nhận được tin nhắn từ group');
    console.log('Group ID:', event.recipient.id);
    console.log('Sender:', event.sender.id);
    console.log('Content:', event.message.text);
    
    // Xử lý tin nhắn từ group
    handleGroupMessage(event);
  }
}
```

### 3. Phân biệt tin nhắn OA gửi cho cá nhân

```typescript
function handleWebhook(event: WebhookEvent) {
  if (isOAToUserMessageEvent(event)) {
    console.log('OA đã gửi tin nhắn cho người dùng cá nhân');
    console.log('Recipient:', event.recipient.id);
    console.log('Content:', event.message.text);
    
    // Xử lý tin nhắn OA gửi cho user
    handleOAToUserMessage(event);
  }
}
```

### 4. Phân biệt tin nhắn OA gửi tới group

```typescript
function handleWebhook(event: WebhookEvent) {
  if (isOAToGroupMessageEvent(event)) {
    console.log('OA đã gửi tin nhắn tới group');
    console.log('Group ID:', event.recipient.id);
    console.log('Content:', event.message.text);
    
    // Xử lý tin nhắn OA gửi tới group
    handleOAToGroupMessage(event);
  }
}
```

### 5. Xác định hướng và đích của tin nhắn

```typescript
function handleWebhook(event: WebhookEvent) {
  const messageInfo = getMessageDirection(event);
  
  console.log('Direction:', messageInfo.direction); // 'incoming' | 'outgoing' | 'unknown'
  console.log('Target:', messageInfo.target);       // 'user' | 'group' | 'unknown'
  console.log('Description:', messageInfo.description);
  
  // Xử lý dựa trên hướng và đích
  switch (`${messageInfo.direction}-${messageInfo.target}`) {
    case 'incoming-user':
      handleIncomingUserMessage(event);
      break;
    case 'incoming-group':
      handleIncomingGroupMessage(event);
      break;
    case 'outgoing-user':
      handleOutgoingUserMessage(event);
      break;
    case 'outgoing-group':
      handleOutgoingGroupMessage(event);
      break;
    default:
      console.log('Unknown message type');
  }
}
```

## Ví dụ tổng hợp

```typescript
import {
  isUserMessageEvent,
  isGroupMessageEvent,
  isOAToUserMessageEvent,
  isOAToGroupMessageEvent,
  getMessageDirection,
  WebhookEvent,
} from '@warriorteam/redai-zalo-sdk';

class ZaloWebhookHandler {
  handleWebhook(event: WebhookEvent) {
    // Cách 1: Sử dụng các hàm kiểm tra riêng lẻ
    if (isUserMessageEvent(event)) {
      this.handleUserMessage(event);
    } else if (isGroupMessageEvent(event)) {
      this.handleGroupMessage(event);
    } else if (isOAToUserMessageEvent(event)) {
      this.handleOAToUserMessage(event);
    } else if (isOAToGroupMessageEvent(event)) {
      this.handleOAToGroupMessage(event);
    }

    // Cách 2: Sử dụng getMessageDirection
    const messageInfo = getMessageDirection(event);
    this.logMessageInfo(messageInfo);
  }

  private handleUserMessage(event: UserMessageWebhookEvent) {
    console.log('Processing user message:', event.message.text);
    // Logic xử lý tin nhắn từ user cá nhân
  }

  private handleGroupMessage(event: GroupWebhookEvent) {
    console.log('Processing group message:', event.message.text);
    // Logic xử lý tin nhắn từ group
  }

  private handleOAToUserMessage(event: OAMessageWebhookEvent) {
    console.log('Processing OA to user message:', event.message.text);
    // Logic xử lý tin nhắn OA gửi cho user
  }

  private handleOAToGroupMessage(event: GroupWebhookEvent) {
    console.log('Processing OA to group message:', event.message.text);
    // Logic xử lý tin nhắn OA gửi tới group
  }

  private logMessageInfo(messageInfo: ReturnType<typeof getMessageDirection>) {
    console.log(`Message: ${messageInfo.direction} -> ${messageInfo.target}`);
    console.log(`Description: ${messageInfo.description}`);
  }
}
```

## Các loại sự kiện được hỗ trợ

### User Message Events (Tin nhắn từ người dùng cá nhân)
- `user_send_text`
- `user_send_image`
- `user_send_location`
- `user_send_link`
- `user_send_sticker`
- `user_send_gif`
- `user_send_audio`
- `user_send_video`
- `user_send_file`
- `user_received_message`
- `user_seen_message`
- `user_send_business_card`

### Group Message Events (Tin nhắn từ group)
- `user_send_group_text`
- `user_send_group_link`
- `user_send_group_audio`
- `user_send_group_location`
- `user_send_group_video`
- `user_send_group_business_card`
- `user_send_group_sticker`
- `user_send_group_gif`
- `user_send_group_file`

### OA to User Events (OA gửi cho cá nhân)
- `oa_send_text`
- `oa_send_image`
- `oa_send_gif`
- `oa_send_list`
- `oa_send_file`
- `oa_send_sticker`
- `oa_send_template`

### OA to Group Events (OA gửi tới group)
- `oa_send_group_text`
- `oa_send_group_image`
- `oa_send_group_link`
- `oa_send_group_audio`
- `oa_send_group_location`
- `oa_send_group_video`
- `oa_send_group_business_card`
- `oa_send_group_sticker`
- `oa_send_group_gif`
- `oa_send_group_file`

## Lưu ý

1. Các hàm helper này chỉ hoạt động với các sự kiện tin nhắn, không áp dụng cho các sự kiện khác như follow/unfollow.
2. Sử dụng TypeScript để có type safety tốt nhất.
3. Các hàm này đã được test kỹ lưỡng và an toàn để sử dụng trong production.