Convo

Bring automation to your instant messaging app

Table of Contents

1. About Convo
   • Features
   • Built With
2. Usage
   • App Login
   • Plugin Manager
3. Getting Started
   • Develop / Deploy in your OS
   • Prerequisites
   • Installation
   • Develop / Deploy using Docker
   • Prerequisites
   • Deploy a Prebuilt Image
   • Build Your Own Image
   • Develop in Dev Container
   • Environment Variables
4. Roadmap
5. Contributing
6. How it works
7. Contact

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

Environment Variable	Required/Optional	Default	Description
OPENAI_API_KEY	Required	N/A	The key for OpenAI API. Doc
OPENAI_MODEL	Optional	gpt-4o-mini	The OpenAI model to use. Doc
OPENAI_PROJECT_ID	Optional	""	Project ID for OpenAI
OPENAI_TTS_VOICE	Optional	onyx	TTS Voice option: onyx, alloy, echo, fable, nova, shimmer. Doc
ASSISTANT_PROMPT_DEFAULT	Optional	""	Default prompt for default openai assistant
ASSISTANT_PROMPT_HABIT_TRACKER	Optional	""	Default prompt for openai assistant in habit tracker
WECHATY_CHATBOT_NAME	Optional, but recommended	["jarvis"]	Names of the chatbot, separated by commas ,. By default, invoke chatbot by @jarvis. eg. If you put jarvis, xqc, speed, you can invoke the chatbot by either @jarvis, @xqc or @speed.
WECHATY_GROUPCHAT_WHITELIST	Optional, but recommended	[""]	Names of group chats to be whitelisted for chatbot, separated by commas ,. By default, chatbot is disabled for all group chats. Enable the chatbot by providing names of target group chats. eg. ecorp, family, fsociety
WECHATY_CONTACT_WHITELIST	Optional, but recommended	[""]	Names of contacts to be whitelisted for chatbot, separated by commas ,. By default, chatbot is disabled for all contacts. Enable the chatbot by providing names (NOT alias) of target contacts. eg. mr.robot, elliot, white rose
LOG_LEVEL	Optional	info if in production mode, debug otherwise	error, warn, info, http, verbose, debug, silly Doc
DATABASE_URL	Optional	./localdb/default.db	Location of Sqlite3 DB file. WARNING: Use this only if you know what you're doing!

Back to Top

Roadmap

• Persist thread context locally
• Send audio message using TTS(Text to Speech)
• 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