Over Party Lab Chatbot

An intelligent LINE chatbot for cocktail discovery and recommendations

Features • Quick Start • Documentation • Contributing

Overview

Over Party Lab Chatbot is a production-ready LINE messaging bot built for Over Party Lab, leveraging Google Apps Script and TypeScript to deliver an interactive cocktail discovery experience. The bot intelligently searches cocktail recipes and provides personalized recommendations based on ingredients.

Features

Core Capabilities

🔍 Multilingual Search: Query cocktail recipes in English or Chinese with fuzzy matching
🎯 Smart Recommendations: AI-powered ingredient-based suggestions when exact matches aren't found
🎨 Rich Interactive UI: Button templates and carousel cards for enhanced user experience
📊 Analytics Integration: Comprehensive user interaction logging to Google Sheets
🚀 Serverless Architecture: Zero-maintenance deployment with Google Apps Script

Technical Highlights

Type-safe development with TypeScript
Modular service architecture for maintainability
Automated deployment pipeline with clasp
Real-time webhook integration with LINE Messaging API
Scalable data storage with Google Sheets

Tech Stack

Category	Technology
Runtime	Google Apps Script
Language	TypeScript 5.7+
Messaging Platform	LINE Messaging API
Data Storage	Google Sheets
Build Tool	clasp (Command Line Apps Script Projects)
Type Definitions	@types/google-apps-script

Architecture

The bot follows a serverless, event-driven architecture:

┌─────────────────┐
│   LINE User     │
│   (Client)      │
└────────┬────────┘
         │ Message
         ▼
┌─────────────────────────────────────────┐
│         LINE Messaging API              │
│         (Webhook Trigger)               │
└────────┬────────────────────────────────┘
         │ HTTP POST
         ▼
┌─────────────────────────────────────────┐
│     Google Apps Script (Server)         │
│  ┌─────────────────────────────────┐   │
│  │  doPost() - Webhook Handler     │   │
│  └──────────┬──────────────────────┘   │
│             │                            │
│  ┌──────────▼──────────┐                │
│  │  Message Processing │                │
│  │  - Parse input      │                │
│  │  - Search logic     │                │
│  │  - Response builder │                │
│  └──────────┬──────────┘                │
│             │                            │
│  ┌──────────▼──────────┐                │
│  │  Service Layer      │                │
│  │  - lineService      │                │
│  │  - sheetService     │                │
│  │  - logService       │                │
│  └──────────┬──────────┘                │
└─────────────┼──────────────────────────┘
              │
              ▼
┌──────────────────────────────────────────┐
│        Google Sheets (Database)          │
│  ┌────────────┐  ┌──────────────────┐   │
│  │ DRINK_LIST │  │ ELEMENT_MAPPING  │   │
│  └────────────┘  └──────────────────┘   │
│  ┌────────────┐                          │
│  │USER_ACTION │  (Analytics)             │
│  └────────────┘                          │
└──────────────────────────────────────────┘

Prerequisites

Before you begin, ensure you have the following:

Node.js: v12.0.0 or later (Download)
Package Manager: npm (comes with Node.js) or yarn
Google Account: For Google Apps Script and Sheets access
LINE Developer Account: Register here
LINE Messaging API Channel: Create a channel

Quick Start

# Clone the repository
git clone https://github.com/sean1093/over-party-lab-chatbot.git
cd over-party-lab-chatbot

# Install dependencies
npm install

# Install clasp globally
npm install -g @google/clasp

# Login to Google Account
clasp login

# Create config file
cp config.ts.example config.ts
# Edit config.ts with your credentials

# Deploy to Google Apps Script
clasp create --type webapp --title "Over Party Lab Chatbot"
clasp push
clasp deploy

Installation

1. Install Dependencies

# Install clasp globally
npm install -g @google/clasp

# Install project dependencies
npm install

2. Setup Google Apps Script

# Login to Google Account
clasp login

# Create a new Apps Script project (or clone existing one)
clasp create --type webapp --title "Over Party Lab Chatbot"

# Or clone existing project
clasp clone <SCRIPT_ID>

3. Configure Environment

Create a config.ts file in the root directory with your credentials:

const CONFIG = {
  LINE: {
    // Get this from LINE Developers Console > Your Channel > Messaging API
    CHANNEL_ACCESS_TOKEN: 'YOUR_LINE_CHANNEL_ACCESS_TOKEN',
    URL_LINE: 'https://api.line.me/v2/bot/message/'
  },
  GOOGLE_SHEET: {
    // Your Google Sheet ID (from the spreadsheet URL)
    // https://docs.google.com/spreadsheets/d/{SHEET_ID}/edit
    API_KEY: 'YOUR_GOOGLE_SHEET_ID'
  },
  COLUMN_KEY_MAPPING: {
    name: 1,          // Chinese name column
    nameen: 2,        // English name column
    link: 3,          // Recipe link column
    detail: 4,        // Cocktail details column
    recommendation: 5 // Recommendation column
  },
  OVERPARTYLAB: {
    IG: 'https://www.instagram.com/over.party.lab/'
  },
  CONFIG_DEBUG: {
    // Your LINE User ID for testing (optional)
    // Get it by sending a message to the bot and checking webhook logs
    USERID: 'YOUR_LINE_USER_ID_FOR_TESTING'
  }
};

export default CONFIG;

Note: Never commit config.ts to version control. It's already in .gitignore.

4. Setup Google Sheets

Create a new Google Sheet
Create three tabs with the following structure:

Tab 1: DRINK_LIST

Stores cocktail recipes and information.

Column	Type	Description	Example
name	Text	Chinese cocktail name	瑪格麗特
nameen	Text	English cocktail name	Margarita
link	URL	Recipe link	https://...
detail	Text	Cocktail description	經典龍舌蘭調酒...

Tab 2: ELEMENT_MAPPING

Maps ingredients to recommended cocktails.

Column	Type	Description	Example
name	Text	Chinese ingredient name	龍舌蘭
nameen	Text	English ingredient name	Tequila
recommendation	Text	Recommended cocktail names (comma-separated)	瑪格麗特,龍舌蘭日出

Tab 3: USER_ACTION

Automatically logs user interactions (no manual setup needed).

Column	Type	Description
index	Number	Auto-increment ID
search	Text	User search query
user	Text	LINE User ID
time	Datetime	Timestamp

Copy the Google Sheet ID from the URL and add it to your config.ts

5. Deploy

# Push code to Google Apps Script
clasp push

# Deploy as web app
clasp deploy

6. Configure LINE Webhook

After deployment, get your web app URL:

clasp deploy
# Copy the Web app URL from the output

Configure LINE Messaging API:
- Go to LINE Developers Console
- Select your Messaging API channel
- Navigate to Messaging API tab
- Set Webhook URL to your Google Apps Script web app URL
- Enable Use webhook
- Disable Auto-reply messages (optional, recommended)
Verify webhook:
- Click Verify button in LINE Console
- Should return success message

Development

Available Scripts

# Push code to Google Apps Script
npm run push

# Pull code from Google Apps Script
npm run pull

# Deploy new version
npm run deploy

# Watch mode - auto-push on file changes
npm run watch

Development Workflow

Make local changes to TypeScript files
Push to Google Apps Script:
```
npm run push
```
Test in LINE: Send messages to your bot
View logs: Check Google Apps Script editor > Executions

Testing

The project includes testing utilities in debug.ts:

// Test webhook POST endpoint
function test_post() {
  // Simulates a LINE webhook message
  // Useful for testing message parsing and response logic
}

// Test sending messages
function test_send() {
  // Tests LINE API message delivery
  // Requires CONFIG_DEBUG.USERID to be set
}

Run tests:

Open Google Apps Script editor
Select the test function
Click Run
Check Execution log for results

Local Development Tips

Type checking: Run tsc --noEmit to check for TypeScript errors before pushing
Auto-formatting: Use Prettier or similar formatter for consistent code style
Watch mode: Use npm run watch during active development for automatic deployment

Project Structure

over-party-lab-chatbot/
│
├── 📄 Core Application Files
│   ├── app.ts                 # Main webhook handler and message processing logic
│   ├── config.ts              # Configuration file (not in repo, see config.ts.example)
│   └── appsscript.json        # Google Apps Script manifest
│
├── 🔧 Service Layer
│   ├── lineService.ts         # LINE Messaging API integration
│   ├── sheetService.ts        # Google Sheets data operations
│   ├── logService.ts          # User activity logging
│   └── timeService.ts         # Timestamp formatting utilities
│
├── 📝 Resources
│   ├── wording.ts             # Message templates and response texts
│   └── debug.ts               # Testing and debugging utilities
│
├── ⚙️ Configuration
│   ├── package.json           # Node.js dependencies and scripts
│   ├── tsconfig.json          # TypeScript compiler configuration
│   ├── .claspignore           # Files to exclude from clasp push
│   └── .gitignore             # Git ignore rules
│
└── 📁 Other
    └── image/                 # Project assets (logo, screenshots)

Key Files Explained

File	Purpose
`app.ts`	Entry point with `doPost()` webhook handler
`lineService.ts`	Handles LINE API calls (push messages, buttons, carousels)
`sheetService.ts`	CRUD operations for Google Sheets data
`wording.ts`	Centralized message templates for consistency
`debug.ts`	Testing functions for local development

How It Works

Message Flow

1. User sends message (e.g., "Margarita")
   ↓
2. LINE Platform receives message
   ↓
3. Webhook POST → doPost(e) in app.ts
   ↓
4. Parse message and extract search query
   ↓
5. Search DRINK_LIST sheet for exact match
   ↓
6a. ✅ Match found                    6b. ❌ No match found
    → Return cocktail details              → Search ELEMENT_MAPPING
    → Include recipe link                  → Find ingredient recommendations
    → Send text message                    → Send button template with options
   ↓
7. Log user action to USER_ACTION sheet
   ↓
8. Response delivered to user

Search Logic

The bot implements a two-tier search strategy:

Exact Match Search (Primary):
- Searches both name (Chinese) and nameen (English) columns
- Case-insensitive matching
- Returns full cocktail details with recipe link
Ingredient-Based Recommendations (Fallback):
- Searches ELEMENT_MAPPING for partial matches
- Returns up to 5 recommended cocktails
- Presented as interactive buttons for easy selection

API Reference

Core Functions

`doPost(e: GoogleAppsScript.Events.DoPost)`

Webhook handler that processes incoming LINE messages.

function doPost(e: GoogleAppsScript.Events.DoPost): GoogleAppsScript.Content.TextOutput

Parameters:

e: Event object containing the POST request data from LINE

Returns: TextOutput with status 200

`lineService.pushMsg(config: PushMessageConfig)`

Sends messages to LINE users via Messaging API.

interface PushMessageConfig {
  to: string;           // LINE User ID
  messages: Message[];  // Array of message objects
}

`sheetService.query(params: QueryParams)`

Queries Google Sheets for cocktail or ingredient data.

interface QueryParams {
  sheetName: string;    // Sheet tab name (e.g., 'DRINK_LIST')
  searchValue: string;  // Search query
  searchColumn?: number; // Column index to search
}

`sheetService.save(params: SaveParams)`

Logs user actions to the USER_ACTION sheet.

interface SaveParams {
  search: string;       // User's search query
  user: string;         // LINE User ID
  timestamp: string;    // Formatted timestamp
}

Configuration

appsscript.json

Configuration for Google Apps Script deployment:

{
  "timeZone": "Asia/Hong_Kong",
  "webapp": {
    "access": "ANYONE_ANONYMOUS",  // Allow public webhook access
    "executeAs": "USER_DEPLOYING"  // Run as deploying user
  },
  "exceptionLogging": "STACKDRIVER"  // Enable Google Cloud logging
}

Key Settings:

timeZone: Adjust for your region (affects timestamp logging)
access: Must be ANYONE_ANONYMOUS for LINE webhook
executeAs: USER_DEPLOYING ensures proper permissions

Troubleshooting

Common Issues

Webhook Not Receiving Messages

✅ Verify webhook URL is correct in LINE Console
✅ Ensure web app is deployed (not just saved)
✅ Check access is set to ANYONE_ANONYMOUS in appsscript.json
✅ Test webhook using LINE Console's verification tool

"Cannot find module 'config'" Error

✅ Ensure config.ts exists in root directory
✅ Copy from config.ts.example if missing
✅ Verify config.ts is not in .claspignore

Bot Not Responding

✅ Check Google Apps Script execution logs for errors
✅ Verify LINE Channel Access Token is valid
✅ Confirm Google Sheet ID is correct
✅ Ensure sheet tab names match exactly (case-sensitive)

TypeScript Compilation Errors

# Check for errors before pushing
npx tsc --noEmit

# Common fix: Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Debugging Tips

View Execution Logs:
- Open Google Apps Script editor
- Click View > Executions
- Check recent execution logs for errors
Test Locally:
- Use debug.ts functions to test without LINE
- Run test_post() to simulate webhook
- Run test_send() to test message sending
Enable Verbose Logging:
- Add console.log() statements in your code
- View output in Apps Script Executions panel

Contributing

Contributions are welcome! Here's how you can help:

How to Contribute

Fork the repository

git clone https://github.com/YOUR_USERNAME/over-party-lab-chatbot.git

Create a feature branch
```
git checkout -b feature/amazing-feature
```
Make your changes
- Follow existing code style
- Add comments for complex logic
- Update documentation if needed
Test your changes
- Test locally using debug functions
- Ensure no TypeScript errors: npx tsc --noEmit
Commit with clear messages
```
git commit -m "feat: add amazing feature"
```
Follow Conventional Commits
Push and create Pull Request
```
git push origin feature/amazing-feature
```

Contribution Guidelines

Write clean, readable code
Maintain type safety (avoid any types)
Add JSDoc comments for public functions
Keep dependencies minimal
Test thoroughly before submitting PR

Areas for Contribution

🌐 Add more language support
🎨 Improve message templates and UI
📊 Enhanced analytics and reporting
🧪 Add unit tests
📝 Improve documentation
🐛 Bug fixes and performance improvements

License

This project is licensed under the MIT License - see the LICENSE file for details.

FAQ

Can I use this for other types of data besides cocktails?

Yes! The architecture is generic. Simply modify:

Google Sheets structure for your data
Search logic in app.ts
Message templates in wording.ts

How much does it cost to run?

$0 - Both Google Apps Script and LINE Messaging API offer free tiers sufficient for most small to medium bots.

Can I add image/video responses?

Yes! LINE Messaging API supports rich media. See LINE Message Types for implementation details.

How do I scale for more users?

Google Apps Script has daily quotas. For high-traffic bots, consider:

Using Google Cloud Functions
Implementing caching
Optimizing Sheets queries
Migrating to a database (Firebase, MongoDB)

Can I deploy multiple bots from this code?

Yes! Clone the project, use different:

LINE channels
Google Sheets
Apps Script deployments

Resources

Author

Sean Chou

GitHub: @sean1093
Medium: @sean1093

Acknowledgments

🍸 Over Party Lab - Cocktail community and inspiration
💚 LINE Corporation - LINE Messaging API
☁️ Google - Apps Script platform and infrastructure
💙 TypeScript Team - Type-safe development tools
🙏 All contributors and users of this project

⬆ Back to Top

Made with ❤️ for cocktail enthusiasts

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
image		image
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
app.ts		app.ts
appsscript.json		appsscript.json
config.ts.example		config.ts.example
debug.ts		debug.ts
lineService.ts		lineService.ts
logService.ts		logService.ts
package-lock.json		package-lock.json
package.json		package.json
sheetService.ts		sheetService.ts
timeService.ts		timeService.ts
tsconfig.json		tsconfig.json
wording.ts		wording.ts

Folders and files

Latest commit

History

Repository files navigation

Over Party Lab Chatbot

Overview

Features

Core Capabilities

Technical Highlights

Tech Stack

Architecture

Prerequisites

Quick Start

Installation

1. Install Dependencies

2. Setup Google Apps Script

3. Configure Environment

4. Setup Google Sheets

Tab 1: DRINK_LIST

Tab 2: ELEMENT_MAPPING

Tab 3: USER_ACTION

5. Deploy

6. Configure LINE Webhook

Development

Available Scripts

Development Workflow

Testing

Local Development Tips

Project Structure

Key Files Explained

How It Works

Message Flow

Search Logic

API Reference

Core Functions

doPost(e: GoogleAppsScript.Events.DoPost)

lineService.pushMsg(config: PushMessageConfig)

sheetService.query(params: QueryParams)

sheetService.save(params: SaveParams)

Configuration

appsscript.json

Troubleshooting

Common Issues

Webhook Not Receiving Messages

"Cannot find module 'config'" Error

Bot Not Responding

TypeScript Compilation Errors

Debugging Tips

Contributing

How to Contribute

Contribution Guidelines

Areas for Contribution

License

FAQ

Can I use this for other types of data besides cocktails?

How much does it cost to run?

Can I add image/video responses?

How do I scale for more users?

Can I deploy multiple bots from this code?

Resources

Tutorials

Official Documentation

Related Projects

Author

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`doPost(e: GoogleAppsScript.Events.DoPost)`

`lineService.pushMsg(config: PushMessageConfig)`

`sheetService.query(params: QueryParams)`

`sheetService.save(params: SaveParams)`

Packages