@warriorteam/zalo-webhook-types

@warriorteam/zalo-webhook-types

TypeScript types and utilities for Zalo Personal webhook events.

Overview

This SDK provides comprehensive type definitions for all 57 webhook event types from Zalo Personal API, organized into 4 main categories:

• Message Events (44 types) - Text, media, file, and social messages
• Interaction Events (5 types) - Typing, seen, delivered, reaction, undo
• Social Events (2 types) - Friend and group events
• System Events (6 types) - Connection, error, and other system events

Installation

npm install @warriorteam/zalo-webhook-types

Quick Start

import { 
  ZaloWebhookEvent,
  ZaloTextMessageEvent,
  ZaloImageMessageEvent,
  isTextMessage,
  isImageMessage,
  ZaloWebhookEventType 
} from '@warriorteam/zalo-webhook-types';

// Type-safe event handling
function handleWebhookEvent(event: ZaloWebhookEvent) {
  if (isTextMessage(event)) {
    // TypeScript knows this is ZaloTextMessageEvent
    console.log('Text message:', event.data.content);
  } else if (isImageMessage(event)) {
    // TypeScript knows this is ZaloImageMessageEvent
    console.log('Image message:', event.data.content.href);
  }
}

// Create events with proper typing
const textEvent: ZaloTextMessageEvent = {
  eventType: ZaloWebhookEventType.TEXT_MESSAGE_RECEIVED_FROM_USER,
  sessionId: 'session123',
  userUuid: 'user456',
  timestamp: Date.now(),
  data: {
    msgId: 'msg789',
    content: 'Hello world!',
    msgType: 'webchat',
    // ... other required fields
  }
};

Event Types

Message Events (44 types)

Text Category (8 events)

• TEXT_MESSAGE_SENT_TO_USER
• TEXT_MESSAGE_SENT_TO_GROUP
• TEXT_MESSAGE_RECEIVED_FROM_USER
• TEXT_MESSAGE_RECEIVED_FROM_GROUP
• LINK_MESSAGE_SENT_TO_USER
• LINK_MESSAGE_SENT_TO_GROUP
• LINK_MESSAGE_RECEIVED_FROM_USER
• LINK_MESSAGE_RECEIVED_FROM_GROUP

Media Category (20 events)

• Image messages (4 events)
• Video messages (4 events)
• Voice messages (4 events)
• GIF messages (4 events)
• Doodle messages (4 events)

File Category (4 events)

• FILE_MESSAGE_SENT_TO_USER
• FILE_MESSAGE_SENT_TO_GROUP
• FILE_MESSAGE_RECEIVED_FROM_USER
• FILE_MESSAGE_RECEIVED_FROM_GROUP

Social Category (8 events)

• Sticker messages (4 events)
• Location messages (4 events)

Generic Category (4 events)

• Fallback for unrecognized message types

Interaction Events (5 types)

• TYPING - User typing indicator
• SEEN_MESSAGES - Messages marked as read
• DELIVERED_MESSAGES - Messages delivered to recipients
• REACTION - Message reactions (like, love, etc.)
• UNDO - Message recall/deletion

Social Events (2 types)

• FRIEND_EVENT - Friend requests, adds, removes, etc.
• GROUP_EVENT - Group joins, leaves, updates, etc.

System Events (6 types)

• CONNECTION_STATUS - WebSocket connection status
• ERROR - System errors
• OLD_MESSAGES - Historical message loading
• OLD_REACTIONS - Historical reaction loading
• UPLOAD_ATTACHMENT - File upload progress
• CIPHER_KEY - Encryption key updates

Type Guards

The SDK provides comprehensive type guards for runtime type checking:

import { 
  isMessageEvent,
  isInteractionEvent,
  isSystemEvent,
  isSocialEvent,
  isTextMessage,
  isImageMessage,
  isVideoMessage,
  isTypingEvent,
  isReactionEvent
} from '@warriorteam/zalo-webhook-types';

function processEvent(event: ZaloWebhookEvent) {
  // Category-level guards
  if (isMessageEvent(event)) {
    console.log('This is a message event');
  }
  
  // Specific type guards
  if (isTextMessage(event)) {
    console.log('Text content:', event.data.content);
  }
  
  if (isImageMessage(event)) {
    console.log('Image URL:', event.data.content.href);
    console.log('Image size:', event.data.content.width, 'x', event.data.content.height);
  }
  
  if (isTypingEvent(event)) {
    console.log('User is typing:', event.data.isTyping);
  }
}

Content Types

The SDK provides specific content types for different message types:

import { 
  ZaloImageContent,
  ZaloVideoContent,
  ZaloVoiceContent,
  ZaloFileContent,
  ZaloLocationContent,
  ZaloStickerContent
} from '@warriorteam/zalo-webhook-types';

// Image content
const imageContent: ZaloImageContent = {
  href: 'https://example.com/image.jpg',
  width: 1920,
  height: 1080,
  fileSize: 2048576,
  fileName: 'image.jpg',
  checksum: 'abc123',
  caption: 'Beautiful sunset'
};

// Video content
const videoContent: ZaloVideoContent = {
  href: 'https://example.com/video.mp4',
  width: 1920,
  height: 1080,
  duration: 30000, // 30 seconds in milliseconds
  fileSize: 10485760,
  fileName: 'video.mp4',
  checksum: 'def456'
};

// Location content
const locationContent: ZaloLocationContent = {
  latitude: 10.762622,
  longitude: 106.660172,
  address: 'Ho Chi Minh City, Vietnam',
  name: 'Landmark 81'
};

Utilities

The SDK includes helpful utility functions:

import { 
  detectMessageType,
  getMessageCategory,
  createDetailedMessageEventType,
  hasAttachment,
  formatFileSize,
  formatDuration,
  sanitizeContentForLogging
} from '@warriorteam/zalo-webhook-types';

// Detect message type from SDK msgType
const messageType = detectMessageType('chat.photo'); // ZaloMessageType.PHOTO

// Get message category
const category = getMessageCategory(messageType); // ZaloMessageCategory.MEDIA

// Check if message has attachment
const hasFile = hasAttachment(messageType); // true

// Format file size
const sizeText = formatFileSize(2048576); // "2 MB"

// Format duration
const durationText = formatDuration(90000); // "1:30"

// Sanitize content for logging
const logText = sanitizeContentForLogging(imageContent); // "[Attachment: image.jpg]"

TypeScript Support

This SDK is built with TypeScript and provides full type safety:

• Strict typing - All interfaces are strictly typed
• Type guards - Runtime type checking with TypeScript inference
• Union types - Convenient type unions for different event categories
• Generic types - Flexible generic interfaces where appropriate
• JSDoc comments - Comprehensive documentation in code

Integration Example

import { 
  ZaloWebhookEvent,
  isMessageEvent,
  isTextMessage,
  isImageMessage,
  isTypingEvent,
  isConnectionStatusEvent,
  ZaloConnectionStatus
} from '@warriorteam/zalo-webhook-types';

class ZaloWebhookHandler {
  handleEvent(event: ZaloWebhookEvent) {
    console.log(`Received event: ${event.eventType}`);
    
    if (isMessageEvent(event)) {
      this.handleMessageEvent(event);
    } else if (isTypingEvent(event)) {
      this.handleTypingEvent(event);
    } else if (isConnectionStatusEvent(event)) {
      this.handleConnectionEvent(event);
    }
  }
  
  private handleMessageEvent(event: ZaloAllMessageEvents) {
    if (isTextMessage(event)) {
      console.log(`Text from ${event.data.dName}: ${event.data.content}`);
    } else if (isImageMessage(event)) {
      console.log(`Image from ${event.data.dName}: ${event.data.content.href}`);
    }
  }
  
  private handleTypingEvent(event: ZaloTypingEvent) {
    const status = event.data.isTyping ? 'started' : 'stopped';
    console.log(`${event.data.fromName} ${status} typing`);
  }
  
  private handleConnectionEvent(event: ZaloConnectionStatusEvent) {
    if (event.data.status === ZaloConnectionStatus.CONNECTED) {
      console.log('Connected to Zalo');
    } else if (event.data.status === ZaloConnectionStatus.DISCONNECTED) {
      console.log('Disconnected from Zalo');
    }
  }
}

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on GitHub.