Convo

About Convo

Automate conversations, services and more in your instant messaging apps!

Currently supported app: Wechat

Features

• Plugin System: Easily view and manage plugins directly within the app.
• Conversational Chatbot:
  • Remembers conversation context for both private and group chats.
  • Responds in both text and audio formats.
• Habit Tracker Plugin:
  • Motivates users with positive messages each time they track a habit.
• Holiday Blessing Plugin:
  • Sends holiday greetings and well wishes.
• Upcoming Features: More exciting features on the way (See roadmap)

Built With

Back to Top

Usage

App Login

Once the project is deployed/started, a QR Code will show up in standard output.

Scan it to log into your app.

Plugin Manager

A CLI-like tool for managing plugins.

Use it within your instant messaging apps (Wechat, WhatsApp, etc).

Plugin Manager
• Usage: /plugin [OPTION]
• Option:
-l | --list     list all plugins
-e | --enable  [N] enable plugin number N
-d | --disable [N] disable plugin number N
-h | --help     display help message
• Example:
/plugin --list
/plugin --disable 2
/plugin -e 1
/plugin -h

• Send /plugin --list or /plugin -l to explore plugins and their usage!

• /plugin --enable [N] and /plugin --disable [N] are admin commands. Admin is the currently logged-in user.

Back to Top

Getting Started

For end-users, deploy using prebuilt image is highly recommended.

Develop / Deploy in your OS

Prerequisites

• Node.js >= v20.x.x. Installation Guide

• PNPM. Run corepack enable pnpm && corepack install or see instructions here.

• GNU Make. Windows Installation

Installation

1. Install and build

   make

   No GNU Make? No worries. Just run pnpm install && pnpm migrate:prod && pnpm build

2. Configuration

   cp .env.example .env

   Edit .env and fill out all required fields. See this section for more.

3. Start

   pnpm start

   Optional: Set NODE_ENV=production to get a production deployment. eg. NODE_ENV=production pnpm start

[!NOTE] If you see any error related to "Chrome" or "Puppeteer", there might be some missing dependencies(shared objects) required for the chrome binary, which can be verified using the ldd command. Try running make fixdeps and start again. For now make fixdeps only supports Debian based linux distros and Alpine Linux. If your OS isn't supported, consider using Docker/Dev Container instead.

Back to Top

Develop / Deploy using Docker

Prerequisites

• Docker Engine. Installation Guide

Deploy a Prebuilt Image

1. Configuration

   cp .env.example .env

   Edit .env and fill out all required fields. See this section for more.

2. Deploy

   sudo docker compose up -d
   sudo docker compose logs -f

Build Your Own Image

1. Option 1. Build a new image only.

   make image

   Or sudo docker build -t convo:devbuild .

2. Option 2. Build and deploy the new image.

   sudo docker compose -f docker-compose-dev.yaml up --build

Develop in Dev Container

1. Open this project in VS Code or Github Codespaces. Instructions

2. Configuration

   cp .env.example .env

   Edit .env and fill out all required fields. See this section for more.

3. Install and Build

   make

4. Start

   pnpm start

Back to Top

Environment Variables

Back to Top

Roadmap

• [x] Persist thread context locally
• [x] Send audio message using TTS(Text to Speech)
• [x] Plugin Manager
• [ ] Task Scheduler
• [ ] REST API + Websocket server for modifying configuration/states and receiving/sending messages
• [ ] Web UI for better user experience
  • [ ] User authentication
  • [ ] Configuration Editor
  • [ ] Plugin Management
  • [ ] Task Editor
  • [ ] Realtime interface for receiving/sending msgs
  • [ ] Better command line interface (auto complete, hints, validation, etc)

Back to Top

How it works

  +-------------------------------------------------------+      
  |                    Convo UI (Todo)                    |
  +-------------------------------------------------------+      
  +-------------------------------------------------------+      
  |                     Convo Server                      |
  +-------------------------------------------------------+      
  +-------------------------------------------------------+
  |                      Wechaty SDK                      |
  +-------------------------------------------------------+
  +-------------------------------------------------------+
  |                 Wechaty Puppet Service                |
  +-------------------------------------------------------+
+---------------------  wechaty_grpc  ----------------------+
  +-------------------------------------------------------+
  |                    Wechaty Puppet                     |
  +-------------------------------------------------------+
  +-------------------------------------------------------+
  |                     Web Protocol                      |
  |                (wechaty-puppet-wechat)                | <--- Puppeteer, based on Chromium
  +-------------------------------------------------------+

Wechaty is a third-party, open-source conversational RPA SDK.

Web Protocol implementation for Wechat is provided by wechaty-puppet-wechat.

* Architecture Reference

Back to Top

Contributing

Any bug fix, new feature, etc are greatly appreciated!

1. Fork the Project
2. Create your Branch (git checkout -b feature/someFeature)
3. Commit your Changes (git commit -m 'feat: Add some feature')
4. Push to the Branch (git push origin feature/someFeature)
5. Open a Pull Request

To develop new plugins, simply extend PluginBase and register your plugin in src/services/wechatyService/plugins/pluginRegistration.ts

Contact

Josh Lin - joshlin.dev@gmail.com

Back to Top