# Python WhatsApp ChatBot Engine
A package 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.
### 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_
_Checkout complete standalone chatbot with [Fast Api here](https://github.com/DonnC/pywce/blob/master/example/standalone_chatbot/main.py)_
- **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:
```python
from pywce import WhatsAppConfig, WhatsApp
config = WhatsAppConfig(
token="your_access_token",
phone_number_id="your_phone_number_id",
hub_verification_token="your_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)
```
## Installation
Install PyWCE using pip:
```bash
pip install pywce
```
## Quick Start
Here's a simple example template to get you started:
_**Note:** Checkout complete example chatbot with [Fast Api here](https://github.com/DonnC/pywce/blob/master/example/engine_chatbot/main.py)_
1. Define your YAML template:
```yaml
"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:
```python
# example/hooks/name_template.py
from pywce import HookArg, TemplateDynamicBody
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:
```python
from pywce import PywceEngine, PywceEngineConfig
config = PywceEngineConfig(
templates_dir="path/to/templates",
start_template_stage="START-MENU"
)
engine = PywceEngine(config=config)
```
## Setting up
To get started using this package, you will need **TOKEN** and **TEST WHATSAPP NUMBER** (the library works either with a
production phone number, if you have one) which you can get from
the [Facebook Developer Portal](https://developers.facebook.com/)
Here are steps to follow for you to get started:
1. [Go to your apps](https://developers.facebook.com/apps)
2. [create an app](https://developers.facebook.com/apps/create/)
3. Select Business >> Business
4. It will prompt you to enter basic app informations
5. It will ask you to add products to your app
a. Add WhatsApp Messenger
6. Right there you will see a your **TOKEN** and **TEST WHATSAPP NUMBER** and its phone_number_id
7. Lastly verify the number you will be using for testing on the **To** field.
Once you've followed the above procedures you're ready to start your bot development journey.
## Documentation
Visit the [official documentation](https://docs.page/donnc/wce) for a detailed guide.
## Contributing
We welcome contributions! Please check out the [Contributing Guide](https://github.com/DonnC/pywce/blob/master/CONTRIBUTING.md) for details.
## License
This project is licensed under the MIT License. See the [LICENSE](https://github.com/DonnC/pywce/blob/master/LICENCE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/DonnC/pywce",
"name": "pywce",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "whatsapp, chatbot, yaml, automation, template, hooks",
"author": "Donald Chinhuru",
"author_email": "donychinhuru@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/94/24/ca2d392e70da97aec3293b6b4f4f9246df6d60053f5e3fe47bbfbb1c3da1/pywce-0.0.1.tar.gz",
"platform": null,
"description": "# Python WhatsApp ChatBot Engine\r\n\r\nA package for creating WhatsApp chatbots using a template-driven approach. It decouples \r\nthe engine from the WhatsApp client library, allowing developers to use them independently or \r\ntogether. \r\n\r\nTemplates use YAML allowing you to define conversation flows and business logic in a clean and modular\r\nway.\r\n\r\n## Features\r\n\r\n- **Template-Driven Design**: Use YAML templates for conversational flows.\r\n- **Hooks for Business Logic**: Attach Python functions to process messages or actions.\r\n- Easy-to-use API for WhatsApp Cloud.\r\n- Supports dynamic messages with placeholders.\r\n- Built-in support for WhatsApp Webhooks.\r\n\r\n### WhatsApp Client Library\r\n\r\nPyWCE provides a simple, Pythonic interface to interact with the WhatsApp Cloud API:\r\n\r\n_**Note**: You can use pywce as a standalone whatsapp client library_\r\n\r\n_Checkout complete standalone chatbot with [Fast Api here](https://github.com/DonnC/pywce/blob/master/example/standalone_chatbot/main.py)_\r\n\r\n- **Send messages** (text, media, templates, interactive)\r\n- **Receive and process webhooks**\r\n- **Media management** (upload and download)\r\n- **Out of the box utilities** using the `WhatsApp.Utils` class.\r\n\r\nExample usage:\r\n\r\n```python\r\nfrom pywce import WhatsAppConfig, WhatsApp\r\n\r\nconfig = WhatsAppConfig(\r\n token=\"your_access_token\",\r\n phone_number_id=\"your_phone_number_id\",\r\n hub_verification_token=\"your_hub_verification_token\"\r\n)\r\n\r\nwhatsapp = WhatsApp(whatsapp_config=config)\r\n\r\n# Sending a text message\r\nresponse = whatsapp.send_message(\r\n recipient_id=\"recipient_number\",\r\n message=\"Hello from PyWCE!\"\r\n)\r\n\r\n# verify if request was successful, using utils\r\nis_sent = whatsapp.util.was_request_successful(\r\n recipient_id=\"recipient_number\",\r\n response_data=response\r\n)\r\n\r\nif is_sent:\r\n message_id = whatsapp.util.get_response_message_id(response)\r\n print(\"Request successful with msg id: \", message_id)\r\n```\r\n\r\n## Installation\r\n\r\nInstall PyWCE using pip:\r\n\r\n```bash\r\npip install pywce\r\n```\r\n\r\n## Quick Start\r\n\r\nHere's a simple example template to get you started:\r\n\r\n_**Note:** Checkout complete example chatbot with [Fast Api here](https://github.com/DonnC/pywce/blob/master/example/engine_chatbot/main.py)_\r\n\r\n1. Define your YAML template:\r\n\r\n```yaml\r\n\"START-MENU\":\r\n type: button\r\n template: \"example.hooks.name_template.username\"\r\n message:\r\n title: Welcome\r\n body: \"Hi {{ name }}, I'm your assistant, click below to start!\"\r\n footer: pywce\r\n buttons:\r\n - Start\r\n routes:\r\n \"start\": \"NEXT-STEP\"\r\n```\r\n\r\n2. Write your hook:\r\n\r\n```python\r\n# example/hooks/name_template.py\r\nfrom pywce import HookArg, TemplateDynamicBody\r\n\r\n\r\ndef username(arg: HookArg) -> HookArg:\r\n # set render payload data to match the required template dynamic var\r\n arg.template_body = TemplateDynamicBody(\r\n render_template_payload={\"name\": arg.user.name}\r\n )\r\n\r\n return arg\r\n```\r\n\r\n3. Start the engine:\r\n\r\n```python\r\nfrom pywce import PywceEngine, PywceEngineConfig\r\n\r\nconfig = PywceEngineConfig(\r\n templates_dir=\"path/to/templates\",\r\n start_template_stage=\"START-MENU\"\r\n)\r\nengine = PywceEngine(config=config)\r\n```\r\n\r\n## Setting up\r\n\r\nTo get started using this package, you will need **TOKEN** and **TEST WHATSAPP NUMBER** (the library works either with a\r\nproduction phone number, if you have one) which you can get from\r\nthe [Facebook Developer Portal](https://developers.facebook.com/)\r\n\r\nHere are steps to follow for you to get started:\r\n\r\n1. [Go to your apps](https://developers.facebook.com/apps)\r\n2. [create an app](https://developers.facebook.com/apps/create/)\r\n3. Select Business >> Business\r\n4. It will prompt you to enter basic app informations\r\n5. It will ask you to add products to your app\r\n a. Add WhatsApp Messenger\r\n6. Right there you will see a your **TOKEN** and **TEST WHATSAPP NUMBER** and its phone_number_id\r\n7. Lastly verify the number you will be using for testing on the **To** field.\r\n\r\nOnce you've followed the above procedures you're ready to start your bot development journey.\r\n\r\n\r\n## Documentation\r\n\r\nVisit the [official documentation](https://docs.page/donnc/wce) for a detailed guide.\r\n\r\n## Contributing\r\n\r\nWe welcome contributions! Please check out the [Contributing Guide](https://github.com/DonnC/pywce/blob/master/CONTRIBUTING.md) for details.\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License. See the [LICENSE](https://github.com/DonnC/pywce/blob/master/LICENCE) file for details.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A template-driven engine for building WhatsApp chatbots",
"version": "0.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/DonnC/pywce/issues",
"Documentation": "https://docs.page/donnc/wce",
"Homepage": "https://github.com/DonnC/pywce",
"Source Code": "https://github.com/DonnC/pywce"
},
"split_keywords": [
"whatsapp",
" chatbot",
" yaml",
" automation",
" template",
" hooks"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f15953bcd311af90e20d31ea2120e46801178d93fd11d02b5f542f258fbac0ca",
"md5": "373fa8923c8bb36b6ef9fcd94f28f996",
"sha256": "77a4d2f2ff1967d32387ab774361dc8d0a714b2ee60d764caca4b68a81c1f07e"
},
"downloads": -1,
"filename": "pywce-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "373fa8923c8bb36b6ef9fcd94f28f996",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 33431,
"upload_time": "2025-01-13T13:57:14",
"upload_time_iso_8601": "2025-01-13T13:57:14.429944Z",
"url": "https://files.pythonhosted.org/packages/f1/59/53bcd311af90e20d31ea2120e46801178d93fd11d02b5f542f258fbac0ca/pywce-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9424ca2d392e70da97aec3293b6b4f4f9246df6d60053f5e3fe47bbfbb1c3da1",
"md5": "66a4a8c9317d24f077e9a21a2fc5d377",
"sha256": "5cd07b821b817e73f8e8c520371eaa0cae4e7517294fb7afc7e7b66fd64acae9"
},
"downloads": -1,
"filename": "pywce-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "66a4a8c9317d24f077e9a21a2fc5d377",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 29792,
"upload_time": "2025-01-13T13:57:16",
"upload_time_iso_8601": "2025-01-13T13:57:16.170755Z",
"url": "https://files.pythonhosted.org/packages/94/24/ca2d392e70da97aec3293b6b4f4f9246df6d60053f5e3fe47bbfbb1c3da1/pywce-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-13 13:57:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DonnC",
"github_project": "pywce",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "httpx",
"specs": [
[
"~=",
"0.28.1"
]
]
},
{
"name": "ruamel.yaml",
"specs": [
[
"~=",
"0.18.10"
]
]
},
{
"name": "requests-toolbelt",
"specs": [
[
"~=",
"1.0.0"
]
]
},
{
"name": "Jinja2",
"specs": [
[
"~=",
"3.1.5"
]
]
},
{
"name": "colorlog",
"specs": [
[
"~=",
"6.9.0"
]
]
},
{
"name": "python-json-logger",
"specs": [
[
"~=",
"3.2.1"
]
]
}
],
"lcname": "pywce"
}
JSON
