WA-Bot-Template

A WhatsApp bot template built with FastAPI and uv package manager, designed to be deployed with Docker.

Table of Contents

• Features
• Requirements
• Dependencies
• Quick Start
  • Local Development
    • Pre-commit(optional)
    • Nox
    • Ruff
• External References
• License

Features

• FastAPI-based REST API
• WhatsApp message handling
• Ngrok tunnel integration
• AWS Lambda compatible (via Mangum)
• Docker containerization
• Modern dependency management with uv

Requirements

• Python 3.11+
• Docker (optional)
• uv package manager

Dependencies

• boto3
• fastapi
• mangum
• ngrok
• nox
• pulumi
• requests

Quick Start

Before you begin, ensure you have uv installed. You can install it using:

winget install --id=astral-sh.uv  -e # Windows

brew install uv # macOS

curl -fsSL https://deno.land/x/install/install.sh | sh # Linux

for more information about UV installation and shell autocomplete, please visit this guide.

1. Clone the repository

git clone https://github.com/Kitsune-Studios/WA-Bot-Template.git && cd $_ # Download and navigate to the project directory

2. Install dependencies:

uv sync --all-groups --dev # Install dependencies using uv

3. Set up environment variables

cp example.env.txt .env # Copy the example environment file. Edit the .env file with your credentials

Local Development

4. Run the server:

• Using local development server:

nox -s dev # Run the development server

• Using Docker:

nox -s docker # Build and run the Docker container

Note

The server will be running on http://localhost:8000 by default on both methods.

Happy coding! 🚀

For development, additional tools are available:

• pre-commit for git hooks and code formatting (optional)
• Ruff for linting and formatting code
• Nox for automated testing and development tasks

Pre-commit (Optional)

[!IMPORTANT] > it is recommended to install pre-commit hooks if you are contributing to the project

Install pre-commit hooks on the project:

pre-commit install --install-hooks # it will add the hooks to the git repository

Tip

You can check more about pre-commit hooks here. settings can be found in .pre-commit-config.yaml

Scripts

Some out of the box scripts are available for development and testing:

uvx nox -s [name] # Run specific session. e.g. nox -s docker check available sessions using nox -l

Ruff

ruff is a tool for linting and formatting code. It is used in the format & lint session in Nox.

to run the session, use the following command:

uvx ruff check # Check code formatting

uvx ruff format # Format code

External References

Documentation:

• FastAPI Docs
• Docker Docs
• Astral
  • uv
  • ruff
• Mangum
• Pulumi
  • Pulumi AWS
  • Pulumi GCP
• Ngrok (soon to be deprecated)
• Nox

License

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