Flick Bot

Ever been in the mood for a movie but can't decide what to watch? Or found a film you loved and wanted something similar? Flick Bot is a WhatsApp companion that helps you search, discover, and compare movies, all without leaving the chat.

The name "flick" comes from the early days of cinema. Low frame rates made the projected image flicker, so people started calling movies "flickers" and eventually just flicks.

Built with Chat SDK, the Kapso Chat SDK community adapter, and the TMDB API.

Commands

Command	Description
search <title>	Find a movie by title
trending	What's hot this week
best <year>	Top rated movies from a year
genre <name>	Browse by genre or sub-genre
details <id>	Full info, ratings, and streaming
recommend <id>	Similar movie recommendations
help	Show available commands

Quick Start

1. Install dependencies

pnpm install

2. Set up environment variables

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Variable	Where to get it
TMDB_API_ACCESS_TOKEN	TMDB Settings → API
TMDB_API_KEY	Same page as above
OMDB_API_KEY	OMDb API (optional — enables RT, IMDb, Metacritic scores)
KAPSO_API_KEY	Kapso Dashboard
KAPSO_PHONE_NUMBER_ID	Kapso Dashboard → Connected numbers
KAPSO_WEBHOOK_SECRET	Kapso Dashboard → Webhooks
REDIS_URL	Default: redis://localhost:6379. Use Upstash for serverless.

3. Run the dev server

pnpm dev

4. Expose via ngrok

ngrok http 3000

5. Register the webhook

In your Kapso Dashboard, set the webhook URL to:

https://<your-ngrok-url>/webhooks/whatsapp

6. Send a message

Message your WhatsApp number and you'll get the welcome message with interactive buttons. Try /search Inception to get started.

Project Structure

lib/
  bot.ts        Bot instance and event handler wiring
  commands.ts   Command parser and handler logic
  cards.ts      WhatsApp interactive button cards
  format.ts     Movie formatting helpers
  tmdb.ts       TMDB API client
app/
  page.tsx                    Landing page
  webhooks/whatsapp/route.ts  Kapso webhook endpoint