{"id":24178737,"url":"https://github.com/donnc/pywce","last_synced_at":"2025-03-02T18:16:08.411Z","repository":{"id":271116409,"uuid":"912445812","full_name":"DonnC/pywce","owner":"DonnC","description":"A template-driven WhatsApp ChatBot development framework","archived":false,"fork":false,"pushed_at":"2025-02-22T21:02:58.000Z","size":27590,"stargazers_count":7,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-22T22:19:16.160Z","etag":null,"topics":["chatbot","framework","hooks","pywce","template","whatsapp"],"latest_commit_sha":null,"homepage":"https://docs.page/donnc/wce","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DonnC.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yaml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":["https://www.paypal.me/donnclab","https://wise.com/pay/me/donaldc156"]}},"created_at":"2025-01-05T15:45:55.000Z","updated_at":"2025-02-15T05:57:54.000Z","dependencies_parsed_at":"2025-02-05T20:37:58.242Z","dependency_job_id":"ca176ad4-dbb3-4f15-b7ee-f14aa172b570","html_url":"https://github.com/DonnC/pywce","commit_stats":null,"previous_names":["donnc/pywce"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DonnC%2Fpywce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DonnC%2Fpywce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DonnC%2Fpywce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DonnC%2Fpywce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DonnC","download_url":"https://codeload.github.com/DonnC/pywce/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241549134,"owners_count":19980476,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbot","framework","hooks","pywce","template","whatsapp"],"created_at":"2025-01-13T05:13:18.162Z","updated_at":"2025-03-02T18:16:08.362Z","avatar_url":"https://github.com/DonnC.png","language":"Python","funding_links":["https://www.paypal.me/donnclab","https://wise.com/pay/me/donaldc156"],"categories":[],"sub_categories":[],"readme":"# WhatsApp ChatBot Engine\n\nA framework for creating WhatsApp chatbots of any scale using a template-driven approach - \nallowing you to define conversation flows and business logic in a clean and modular way. \n\n\u003e [!NOTE]\n\u003e Template engine and WhatsApp client library are decoupled - allowing you to use them independently or together. \n\n\n## Features\n\n- **Template-Driven Design**: Use YAML templates for conversational flows.\n- **Hooks for Business Logic**: Attach Python functions to process messages or actions.\n- Easy-to-use API for WhatsApp Cloud.\n- Supports dynamic messages with placeholders.\n- Built-in support for WhatsApp Webhooks.\n- Starter templates\n- Live Support / Human interaction portal template\n\n## Installation\n```bash\n\npip install pywce\n```\n\n\n---\n\n## Why pywce\nMost WhatsApp chatbot tutorials or libraries just scraps the surface, only sending a few message or handling simple logic or are client libraries only.\n\nThis 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.\n\n---\n\n## Setup\n### WhatsApp\nFollow the complete step by step WhatsApp Cloud API guide below. \n\n[![WhatsApp Cloud API Complete Setup Guide](https://img.youtube.com/vi/Y8kihPdCI_U/0.jpg)](https://www.youtube.com/watch?v=Y8kihPdCI_U)\n\nImportant settings needed for this framework\n1. Phone number ID (be it test number or live number)\n2. Access Token (Temporary or permanent)\n3. Webhook callback verification token of your choice\n\nCreate a `.env `with the below settings in your project or test folder (be it `example` or `portal` folders)\n\n```\nACCESS_TOKEN        = \u003cyour-whatsapp-access-token\u003e\nPHONE_NUMBER_ID     = \u003cyour-number-phone-id\u003e\nWEBHOOK_HUB_TOKEN   = \u003cyour-webhook-verification-token\u003e\n\n# path to your templates \u0026 triggers folders\nTEMPLATES_DIR       = portal/chatbot/templates\nTRIGGERS_DIR        = portal/chatbot/triggers\n\n# your templates initial or start stage\nSTART_STAGE         = START-MENU\n```\n\n### Engine\nYou can either use `.env` or add your credentials directly to the WhatsAppConfig class\n```python\nimport os\nfrom dotenv import load_dotenv\nfrom pywce import client, Engine, EngineConfig\n\nload_dotenv()\n\nwhatsapp_config = client.WhatsAppConfig(\n    token=os.getenv(\"ACCESS_TOKEN\"),\n    phone_number_id=os.getenv(\"PHONE_NUMBER_ID\"),\n    hub_verification_token=os.getenv(\"WEBHOOK_HUB_TOKEN\")\n)\n\nwhatsapp = client.WhatsApp(whatsapp_config=whatsapp_config)\n\nengine_config = EngineConfig(\n    whatsapp=whatsapp,\n    templates_dir=os.getenv(\"TEMPLATES_DIR\"),\n    trigger_dir=os.getenv(\"TRIGGERS_DIR\"),\n    start_template_stage=os.getenv(\"START_STAGE\")\n)\n\nengine_instance = Engine(config=engine_config)\n```\n\n## Example ChatBot\nHere's a simple example template to get you started:\n\n\u003e [!NOTE]\n\u003e _Checkout complete working example of [e-hailing chatbot](https://github.com/DonnC/pywce/blob/master/example/engine_chatbot/main.py)_\n\n\n1. Define YAML template (Conversation Flow💬):\n\n```yaml\n# path/to/templates\n\"START-MENU\":\n  type: button\n  template: \"example.hooks.name_template.username\"\n  message:\n    title: Welcome\n    body: \"Hi {{ name }}, I'm your assistant, click below to start!\"\n    footer: pywce\n    buttons:\n      - Start\n  routes:\n    \"start\": \"NEXT-STEP\"\n\n\"NEXT-STEP\":\n  type: text\n  message: Great, lets get you started quickly. What is your age?\n  routes:\n    \"re://d{1,}\": \"NEXT-STEP-FURTHER\"\n```\n\n2. Write your hook (Supercharge⚡):\n```python\n# example/hooks/name_template.py\nfrom pywce import hook, HookArg, TemplateDynamicBody\n\n@hook\ndef username(arg: HookArg) -\u003e HookArg:\n    # set render payload data to match the required template dynamic var\n    \n    # greet user by their whatsapp name 😎\n    arg.template_body = TemplateDynamicBody(\n        render_template_payload={\"name\": arg.user.name}\n    )\n\n    return arg\n```\n\n3. Engine client:\n\nUse `fastapi` or `flask` or any python library to create endpoint to receive whatsapp webhooks\n\n```python\n# ~ fastapi snippet ~\n\nasync def webhook_event(payload: Dict, headers: Dict) -\u003e None:\n    \"\"\"\n    Process webhook event in the background using pywce engine.\n    \"\"\"\n    await engine_instance.process_webhook(payload, headers)\n\n@app.post(\"/chatbot/webhook\")\nasync def process_webhook(request: Request, background_tasks: BackgroundTasks):\n    \"\"\"\n    Handle incoming webhook events from WhatsApp \n    and process them in the background.\n    \"\"\"\n    payload = await request.json()\n    headers = dict(request.headers)\n\n    # handle event in the background\n    background_tasks.add_task(webhook_event, payload, headers)\n\n    # Immediately respond to WhatsApp with acknowledgment\n    return Response(content=\"ACK\", status_code=200)\n```\n\n### Run ChatBot\nIf you run your project or the example projects successfully, your webhook url will be available on `localhost:port/chatbot/webhook`.\n\n_You can use `ngrok` or any service to tunnel your local service_\n\nYou can then configure the endpoint in Webhook section on  Meta developer portal.\n\n## Live Support \nEngine comes with a default basic live support /  human interaction portal out-of-the-box powered by [Reflex](https://reflex.dev/)\n\nCheck out [Live Support Portal](https://github.com/DonnC/pywce/tree/feat/live-support/portal)\n\n## WhatsApp Client Library\n\u003e [!NOTE]\n\u003e _You can use pywce as a standalone whatsapp client library. See [Example](https://github.com/DonnC/pywce/blob/master/example/standalone_chatbot/main.py)_\n\nPyWCE provides a simple, Pythonic interface to interact with the WhatsApp Cloud API:\n\n- **Send messages** (text, media, templates, interactive)\n- **Receive and process webhooks**\n- **Media management** (upload and download)\n- **Out of the box utilities** using the `WhatsApp.Utils` class.\n\nExample usage:\n\n```python\nfrom pywce import client\n\nconfig = client.WhatsAppConfig(\n    token=\"your_access_token\",\n    phone_number_id=\"your_phone_number_id\",\n    hub_verification_token=\"your_webhook_hub_verification_token\"\n)\n\nwhatsapp = client.WhatsApp(whatsapp_config=config)\n\n# Sending a text message\nresponse = whatsapp.send_message(\n    recipient_id=\"recipient_number\",\n    message=\"Hello from PyWCE!\"\n)\n\n# verify if request was successful, using utils\nis_sent = whatsapp.util.was_request_successful(\n    recipient_id=\"recipient_number\",\n    response_data=response\n)\n\nif is_sent:\n    message_id = whatsapp.util.get_response_message_id(response)\n    print(\"Request successful with msg id: \", message_id)\n```\n\n\n## Documentation\n\nVisit the [official documentation](https://docs.page/donnc/wce) for a detailed guide.\n\n## Changelog\n\nVisit the [changelog list](https://github.com/DonnC/pywce/blob/master/CHANGELOG.md)  for a full list of changes.\n\n## Contributing\n\nWe welcome contributions! Please check out the [Contributing Guide](https://github.com/DonnC/pywce/blob/master/CONTRIBUTING.md) for details.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](https://github.com/DonnC/pywce/blob/master/LICENCE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonnc%2Fpywce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdonnc%2Fpywce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonnc%2Fpywce/lists"}