@warriorteam/redai-zalo-sdk 1.1.0 → 1.2.0

package/docs/WEBHOOK_EVENTS.md

@@ -0,0 +1,806 @@
+# Webhook Events Documentation
+
+This document describes the webhook event types and DTOs for Zalo Official Account webhooks.
+
+## Overview
+
+The Zalo SDK provides comprehensive TypeScript types for all webhook events sent by Zalo to your application. These events are strongly typed and include proper payload structures for each event type.
+
+## Event Categories
+
+### 1. Message Events
+
+Events triggered when users interact with your Official Account through messages.
+
+### 2. User Action Events
+
+Events triggered when users perform actions like following your Official Account.
+
+### 3. Legacy Events
+
+Backward compatibility events for existing integrations.
+
+## Message Events
+
+### User Send Text Event
+
+```typescript
+import { UserSendTextEvent } from "redai-zalo-sdk";
+
+const textEvent: UserSendTextEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "user_send_text",
+  timestamp: "1754405178258",
+  sender: { id: "4411682737790366300" },
+  recipient: { id: "579745863508352884" },
+  message: {
+    msg_id: "message_id_123",
+    text: "Hello from user",
+  },
+};
+```
+
+### User Send Image Event
+
+```typescript
+import { UserSendImageEvent } from "redai-zalo-sdk";
+
+const imageEvent: UserSendImageEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "user_send_image",
+  timestamp: "1754405178258",
+  sender: { id: "4411682737790366300" },
+  recipient: { id: "579745863508352884" },
+  message: {
+    msg_id: "message_id_123",
+    text: "Check out this image",
+    attachments: [
+      {
+        type: "image",
+        payload: {
+          thumbnail: "https://example.com/thumb.jpg",
+          url: "https://example.com/image.jpg",
+        },
+      },
+    ],
+  },
+};
+```
+
+### User Send Location Event
+
+```typescript
+import { UserSendLocationEvent } from "redai-zalo-sdk";
+
+const locationEvent: UserSendLocationEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "user_send_location",
+  timestamp: "1754405178257",
+  sender: { id: "4411682737790366300" },
+  recipient: { id: "579745863508352884" },
+  message: {
+    msg_id: "message_id_123",
+    text: "My current location",
+    attachments: [
+      {
+        type: "location",
+        payload: {
+          coordinates: {
+            latitude: "10.7642473",
+            longitude: "106.6564313999999",
+          },
+        },
+      },
+    ],
+  },
+};
+```
+
+### User Send Link Event
+
+```typescript
+import { UserSendLinkEvent } from "redai-zalo-sdk";
+
+const linkEvent: UserSendLinkEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "user_send_link",
+  timestamp: "1754405178258",
+  sender: { id: "4411682737790366300" },
+  recipient: { id: "579745863508352884" },
+  message: {
+    msg_id: "message_id_123",
+    text: "Check this link",
+    attachments: [
+      {
+        type: "link",
+        payload: {
+          thumbnail: "https://example.com/thumb.jpg",
+          description: "Interesting article",
+          url: "https://example.com/article",
+        },
+      },
+    ],
+  },
+};
+```
+
+### User Send Sticker Event
+
+```typescript
+import { UserSendStickerEvent } from "redai-zalo-sdk";
+
+const stickerEvent: UserSendStickerEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "user_send_sticker",
+  timestamp: "1754405178259",
+  sender: { id: "4411682737790366300" },
+  recipient: { id: "579745863508352884" },
+  message: {
+    msg_id: "message_id_123",
+    text: "😊",
+    attachments: [
+      {
+        type: "sticker",
+        payload: {
+          id: "sticker_123",
+          url: "https://example.com/sticker.png",
+        },
+      },
+    ],
+  },
+};
+```
+
+### User Send GIF Event
+
+```typescript
+import { UserSendGifEvent } from "redai-zalo-sdk";
+
+const gifEvent: UserSendGifEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "user_send_gif",
+  timestamp: "1754405178259",
+  sender: { id: "4411682737790366300" },
+  recipient: { id: "579745863508352884" },
+  message: {
+    msg_id: "message_id_123",
+    text: "Funny GIF",
+    attachments: [
+      {
+        type: "gif",
+        payload: {
+          thumbnail: "https://example.com/gif_thumb.jpg",
+          url: "https://example.com/funny.gif",
+        },
+      },
+    ],
+  },
+};
+```
+
+### User Send Audio Event
+
+```typescript
+import { UserSendAudioEvent } from "redai-zalo-sdk";
+
+const audioEvent: UserSendAudioEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "user_send_audio",
+  timestamp: "1754405178259",
+  sender: { id: "4411682737790366300" },
+  recipient: { id: "579745863508352884" },
+  message: {
+    msg_id: "message_id_123",
+    text: "Voice message",
+    attachments: [
+      {
+        type: "audio",
+        payload: {
+          url: "https://example.com/voice.mp3",
+        },
+      },
+    ],
+  },
+};
+```
+
+### User Send Video Event
+
+```typescript
+import { UserSendVideoEvent } from "redai-zalo-sdk";
+
+const videoEvent: UserSendVideoEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "user_send_video",
+  timestamp: "1754405178261",
+  sender: { id: "4411682737790366300" },
+  recipient: { id: "579745863508352884" },
+  message: {
+    msg_id: "message_id_123",
+    text: "Check out this video",
+    attachments: [
+      {
+        type: "video",
+        payload: {
+          thumbnail: "https://example.com/video_thumb.jpg",
+          description: "Amazing video content",
+          url: "https://example.com/video.mp4",
+        },
+      },
+    ],
+  },
+};
+```
+
+### User Send File Event
+
+```typescript
+import { UserSendFileEvent } from "redai-zalo-sdk";
+
+const fileEvent: UserSendFileEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "user_send_file",
+  timestamp: "1754405178261",
+  sender: { id: "4411682737790366300" },
+  recipient: { id: "579745863508352884" },
+  message: {
+    msg_id: "message_id_123",
+    attachments: [
+      {
+        type: "file",
+        payload: {
+          url: "https://example.com/document.pdf",
+          size: "1024000",
+          name: "important_document.pdf",
+          checksum: "abc123def456",
+          type: "application/pdf",
+        },
+      },
+    ],
+  },
+};
+```
+
+### User Received Message Event
+
+```typescript
+import { UserReceivedMessageEvent } from "redai-zalo-sdk";
+
+const receivedEvent: UserReceivedMessageEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "user_received_message",
+  timestamp: "1754405178259",
+  sender: { id: "579745863508352884" }, // OA sent
+  recipient: { id: "4411682737790366300" }, // User received
+  message: {
+    msg_id: "message_id_123",
+  },
+};
+```
+
+### User Seen Message Event
+
+```typescript
+import { UserSeenMessageEvent } from "redai-zalo-sdk";
+
+const seenEvent: UserSeenMessageEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "user_seen_message",
+  timestamp: "1754405178259",
+  sender: { id: "579745863508352884" }, // OA
+  recipient: { id: "4411682737790366300" }, // User
+  message: {
+    msg_ids: ["message_id_123", "message_id_124"],
+  },
+};
+```
+
+## User Action Events
+
+### User Follow Event
+
+```typescript
+import { UserFollowEvent } from "redai-zalo-sdk";
+
+const followEvent: UserFollowEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "follow",
+  timestamp: "1754405178260",
+  oa_id: "579745863508352884",
+  source: "testing_webhook",
+  follower: {
+    id: "4411682737790366300",
+  },
+};
+```
+
+### User Unfollow Event
+
+```typescript
+import { UserUnfollowEvent } from "redai-zalo-sdk";
+
+const unfollowEvent: UserUnfollowEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "unfollow",
+  timestamp: "1754405178260",
+  oa_id: "579745863508352884",
+  source: "testing_webhook",
+  follower: {
+    id: "4411682737790366300",
+  },
+};
+```
+
+### User Submit Info Event
+
+```typescript
+import { UserSubmitInfoEvent } from "redai-zalo-sdk";
+
+const submitInfoEvent: UserSubmitInfoEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "user_submit_info",
+  timestamp: "1754405178260",
+  sender: { id: "4411682737790366300" },
+  recipient: { id: "579745863508352884" },
+  info: {
+    address: "123 Main Street",
+    phone: "0123456789",
+    city: "Ho Chi Minh City",
+    district: "District 1",
+    name: "John Doe",
+    ward: "Ward 1",
+  },
+};
+```
+
+## Shop Events
+
+### Shop Has Order Event
+
+```typescript
+import { ShopHasOrderEvent } from "redai-zalo-sdk";
+
+const orderEvent: ShopHasOrderEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "shop_has_order",
+  timestamp: "1754405178260",
+  oa_id: "579745863508352884",
+  customer: {
+    id: "4411682737790366300",
+  },
+};
+```
+
+## OA Message Events
+
+### OA Send Text Event
+
+```typescript
+import { OASendTextEvent } from "redai-zalo-sdk";
+
+const oaTextEvent: OASendTextEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "oa_send_text",
+  timestamp: "1754405178260",
+  sender: { id: "579745863508352884" },
+  recipient: { id: "4411682737790366300" },
+  message: {
+    msg_id: "oa_message_123",
+    text: "Hello from Official Account",
+  },
+};
+```
+
+### OA Send Image Event
+
+```typescript
+import { OASendImageEvent } from "redai-zalo-sdk";
+
+const oaImageEvent: OASendImageEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "oa_send_image",
+  timestamp: "1754405178260",
+  sender: { id: "579745863508352884" },
+  recipient: { id: "4411682737790366300" },
+  message: {
+    msg_id: "oa_message_123",
+    text: "Check out our product",
+    attachments: [
+      {
+        type: "image",
+        payload: {
+          thumbnail: "https://example.com/thumb.jpg",
+          url: "https://example.com/product.jpg",
+        },
+      },
+    ],
+  },
+};
+```
+
+### OA Send List Event (Interactive Message)
+
+```typescript
+import { OASendListEvent } from "redai-zalo-sdk";
+
+const oaListEvent: OASendListEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "oa_send_list",
+  timestamp: "1754405178260",
+  sender: { id: "579745863508352884" },
+  recipient: { id: "4411682737790366300" },
+  message: {
+    msg_id: "oa_message_123",
+    text: "Choose from our options",
+    attachments: [
+      {
+        type: "link",
+        payload: {
+          thumbnail: "https://example.com/option1.jpg",
+          description: "Option 1 description",
+          url: "https://example.com/option1",
+          title: "Option 1",
+        },
+      },
+      {
+        type: "link",
+        payload: {
+          thumbnail: "https://example.com/option2.jpg",
+          description: "Option 2 description",
+          url: "https://example.com/option2",
+          title: "Option 2",
+        },
+      },
+    ],
+  },
+};
+```
+
+### OA Send File Event
+
+```typescript
+import { OASendFileEvent } from "redai-zalo-sdk";
+
+const oaFileEvent: OASendFileEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "oa_send_file",
+  timestamp: "1754405178261",
+  sender: { id: "579745863508352884" },
+  recipient: { id: "4411682737790366300" },
+  message: {
+    msg_id: "oa_message_123",
+    attachments: [
+      {
+        type: "file",
+        payload: {
+          url: "https://example.com/document.pdf",
+          size: "1024000",
+          name: "important_document.pdf",
+          checksum: "abc123def456",
+          type: "application/pdf",
+        },
+      },
+    ],
+  },
+};
+```
+
+### OA Send Sticker Event
+
+```typescript
+import { OASendStickerEvent } from "redai-zalo-sdk";
+
+const oaStickerEvent: OASendStickerEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "oa_send_sticker",
+  timestamp: "1754405178261",
+  sender: { id: "579745863508352884" },
+  recipient: { id: "4411682737790366300" },
+  message: {
+    msg_id: "oa_message_123",
+    text: "Have a great day!",
+    attachments: [
+      {
+        type: "sticker",
+        payload: {
+          id: "sticker_123",
+          url: "https://example.com/sticker.png",
+        },
+      },
+    ],
+  },
+};
+```
+
+## User Interaction Events
+
+### User Click Chat Now Event
+
+```typescript
+import { UserClickChatNowEvent } from "redai-zalo-sdk";
+
+const clickChatEvent: UserClickChatNowEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "user_click_chatnow",
+  timestamp: "1754405178261",
+  oa_id: "579745863508352884",
+  user_id: "4411682737790366300",
+};
+```
+
+### User Reacted Message Event
+
+```typescript
+import { UserReactedMessageEvent } from "redai-zalo-sdk";
+
+const userReactionEvent: UserReactedMessageEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "user_reacted_message",
+  timestamp: "1754405178261",
+  sender: { id: "4411682737790366300" },
+  recipient: { id: "579745863508352884" },
+  message: {
+    msg_id: "message_123",
+    react_icon: "👍",
+  },
+};
+```
+
+### OA Reacted Message Event
+
+```typescript
+import { OAReactedMessageEvent } from "redai-zalo-sdk";
+
+const oaReactionEvent: OAReactedMessageEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "oa_reacted_message",
+  timestamp: "1754405178261",
+  sender: { id: "579745863508352884" },
+  recipient: { id: "4411682737790366300" },
+  message: {
+    msg_id: "message_123",
+    react_icon: "❤️",
+  },
+};
+```
+
+## Consent Events
+
+### OA Send Consent Event
+
+```typescript
+import { OASendConsentEvent } from "redai-zalo-sdk";
+
+const consentEvent: OASendConsentEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "oa_send_consent",
+  timestamp: "1754405178261",
+  oa_id: "579745863508352884",
+  request_type: "SENT",
+  create_time: "1754405178261",
+  expired_time: "1754405178261",
+  phone: "84773543888",
+};
+```
+
+### User Reply Consent Event
+
+```typescript
+import { UserReplyConsentEvent } from "redai-zalo-sdk";
+
+const replyConsentEvent: UserReplyConsentEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "user_reply_consent",
+  timestamp: "1754405178261",
+  oa_id: "579745863508352884",
+  expired_time: "1754405178261",
+  confirmed_time: "1754405178261",
+  phone: "84773543888",
+};
+```
+
+## Anonymous User Events
+
+### Anonymous Send Text Event
+
+```typescript
+import { AnonymousSendTextEvent } from "redai-zalo-sdk";
+
+const anonymousTextEvent: AnonymousSendTextEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "anonymous_send_text",
+  timestamp: "1754405178261",
+  sender: { id: "4411682737790366300" },
+  recipient: { id: "579745863508352884" },
+  message: {
+    msg_id: "message_123",
+    text: "Anonymous message",
+    conversation_id: "conversation_123",
+  },
+};
+```
+
+### Anonymous Send Image Event
+
+```typescript
+import { AnonymousSendImageEvent } from "redai-zalo-sdk";
+
+const anonymousImageEvent: AnonymousSendImageEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "anonymous_send_image",
+  timestamp: "1754405178262",
+  sender: { id: "4411682737790366300" },
+  recipient: { id: "579745863508352884" },
+  message: {
+    msg_id: "message_123",
+    text: "Anonymous image",
+    conversation_id: "conversation_123",
+    attachments: [
+      {
+        type: "image",
+        payload: {
+          thumbnail: "https://example.com/thumb.jpg",
+          url: "https://example.com/image.jpg",
+        },
+      },
+    ],
+  },
+};
+```
+
+### Anonymous Send File Event
+
+```typescript
+import { AnonymousSendFileEvent } from "redai-zalo-sdk";
+
+const anonymousFileEvent: AnonymousSendFileEvent = {
+  app_id: "3482178216594085616",
+  user_id_by_app: "3216904426693862293",
+  event_name: "anonymous_send_file",
+  timestamp: "1754405178262",
+  sender: { id: "4411682737790366300" },
+  recipient: { id: "579745863508352884" },
+  message: {
+    msg_id: "message_123",
+    conversation_id: "conversation_123",
+    attachments: [
+      {
+        type: "file",
+        payload: {
+          url: "https://example.com/document.pdf",
+          size: "1024000",
+          name: "document.pdf",
+          checksum: "abc123def456",
+          type: "application/pdf",
+        },
+      },
+    ],
+  },
+};
+```
+
+## Type Guards and Utilities
+
+### Check Event Type
+
+```typescript
+import {
+  isMessageEvent,
+  isFollowEvent,
+  hasAttachments,
+  WebhookEvent,
+} from "redai-zalo-sdk";
+
+function handleWebhook(event: WebhookEvent) {
+  if (isMessageEvent(event)) {
+    console.log("Message event:", event.event_name);
+
+    if (hasAttachments(event.message)) {
+      console.log("Has attachments:", event.message.attachments.length);
+    }
+  }
+
+  if (isFollowEvent(event)) {
+    console.log("New follower:", event.follower.id);
+  }
+}
+```
+
+### Using Enums
+
+```typescript
+import { WebhookEventName, AttachmentType } from "redai-zalo-sdk";
+
+function processEvent(event: WebhookEvent) {
+  switch (event.event_name) {
+    case WebhookEventName.USER_SEND_TEXT:
+      console.log("Text message received");
+      break;
+
+    case WebhookEventName.USER_SEND_IMAGE:
+      console.log("Image message received");
+      break;
+
+    case WebhookEventName.FOLLOW:
+      console.log("User followed OA");
+      break;
+  }
+}
+```
+
+## Webhook Handler Setup
+
+```typescript
+import { WebhookHandlers, UserSendTextEvent } from "redai-zalo-sdk";
+
+const handlers: WebhookHandlers = {
+  user_send_text: async (event: UserSendTextEvent) => {
+    console.log(`User ${event.sender.id} sent: ${event.message.text}`);
+    // Handle text message
+  },
+
+  user_send_image: async (event) => {
+    console.log(`User sent image: ${event.message.attachments[0].payload.url}`);
+    // Handle image message
+  },
+
+  follow: async (event) => {
+    console.log(`New follower: ${event.follower.id}`);
+    // Handle follow event
+  },
+
+  "*": async (event) => {
+    console.log(`Unhandled event: ${event.event_name}`);
+    // Catch-all handler
+  },
+};
+```
+
+## Best Practices
+
+1. **Type Safety**: Always use the specific event types instead of generic ones
+2. **Type Guards**: Use provided type guards to safely check event types
+3. **Error Handling**: Implement proper error handling for webhook processing
+4. **Validation**: Validate webhook signatures for security
+5. **Async Processing**: Use async handlers for database operations or API calls
+
+## Migration from Legacy Types
+
+If you're migrating from the old `UserSendMessageEvent` type:
+
+```typescript
+// Old way (deprecated)
+user_send_text?: WebhookHandler<UserSendMessageEvent>;
+
+// New way (recommended)
+user_send_text?: WebhookHandler<UserSendTextEvent>;
+```
+
+The new types provide better type safety and more specific payload structures for each event type.