Python WhatsApp ChatBot Engine

A library for creating WhatsApp chatbots using a template-driven approach. It decouples the engine from the WhatsApp client library, allowing developers to use them independently or together.

Templates use YAML allowing you to define conversation flows and business logic in a clean and modular way.

Features

• Template-Driven Design: Use YAML templates for conversational flows.
• Hooks for Business Logic: Attach Python functions to process messages or actions.
• Easy-to-use API for WhatsApp Cloud.
• Supports dynamic messages with placeholders.
• Built-in support for WhatsApp Webhooks.

Installation

pip install pywce

WhatsApp Client Library

PyWCE provides a simple, Pythonic interface to interact with the WhatsApp Cloud API:

Note: You can use pywce as a standalone whatsapp client library. See FastApi Example

• Send messages (text, media, templates, interactive)
• Receive and process webhooks
• Media management (upload and download)
• Out of the box utilities using the WhatsApp.Utils class.

Example usage:

from pywce import WhatsAppConfig, WhatsApp

config = WhatsAppConfig(
    token="your_access_token",
    phone_number_id="your_phone_number_id",
    hub_verification_token="your_webhook_hub_verification_token"
)

whatsapp = WhatsApp(whatsapp_config=config)

# Sending a text message
response = whatsapp.send_message(
    recipient_id="recipient_number",
    message="Hello from PyWCE!"
)

# verify if request was successful, using utils
is_sent = whatsapp.util.was_request_successful(
    recipient_id="recipient_number",
    response_data=response
)

if is_sent:
    message_id = whatsapp.util.get_response_message_id(response)
    print("Request successful with msg id: ", message_id)

Template Engine ChatBot

Here's a simple example template to get you started:

Note: Checkout complete example chatbot with Fast Api here

1. Define your YAML template:

# path/to/templates
"START-MENU":
  type: button
  template: "example.hooks.name_template.username"
  message:
    title: Welcome
    body: "Hi {{ name }}, I'm your assistant, click below to start!"
    footer: pywce
    buttons:
      - Start
  routes:
    "start": "NEXT-STEP"

2. Write your hook:

# example/hooks/name_template.py
from pywce import hook, HookArg, TemplateDynamicBody

@hook
def username(arg: HookArg) -> HookArg:
    # set render payload data to match the required template dynamic var
    arg.template_body = TemplateDynamicBody(
        render_template_payload={"name": arg.user.name}
    )

    return arg

3. Start the engine:

from pywce import PywceEngine, PywceEngineConfig

config = PywceEngineConfig(
    templates_dir="path/to/templates",
    start_template_stage="START-MENU"
)
engine = PywceEngine(config=config)

Documentation

Visit the official documentation for a detailed guide.

Contributing

We welcome contributions! Please check out the Contributing Guide for details.

License

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