pywce 1.0.2

A template-driven framework for building WhatsApp chatbots

Python WhatsApp ChatBot Engine

A framework for creating WhatsApp chatbots using a template-driven approach - allowing you to define conversation flows and business logic in a clean and modular way.

It decouples the engine from the WhatsApp client library, allowing developers to use them independently or together.

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

Why pywce

Most WhatsApp chatbot tutorials or libraries just scraps the surface, only sending a few message or handling simple logic or are client libraries only.

This library gives you a full-blown framework for chatbots of any scale allowing you access to full package of whatsapp client library and chatbot development framework.

Example ChatBot

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

Note: Checkout complete example chatbot with Fast Api here

1. Define YAML template (Conversation Flow💬):

# 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"

"NEXT-STEP":
  type: text
  message: Great, lets get you started quickly. What is your age?
  routes:
    "re://d{1,}": "NEXT-STEP-FURTHER"

2. Write your hook (Supercharge⚡):

# 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
    
    # greet user by their whatsapp name 😎
    arg.template_body = TemplateDynamicBody(
        render_template_payload={"name": arg.user.name}
    )

    return arg

3. Start the engine:

from pywce import Engine, EngineConfig

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

WhatsApp Client Library

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

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

• 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)

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.