{"id":13825328,"url":"https://github.com/david-lev/pywa","last_synced_at":"2026-04-11T21:48:48.843Z","repository":{"id":175405443,"uuid":"652347566","full_name":"david-lev/pywa","owner":"david-lev","description":"🤖 Hey there! I am using PyWa.","archived":false,"fork":false,"pushed_at":"2026-03-26T12:58:46.000Z","size":7462,"stargazers_count":522,"open_issues_count":2,"forks_count":90,"subscribers_count":12,"default_branch":"master","last_synced_at":"2026-03-27T05:07:07.765Z","etag":null,"topics":["pywa","whatsapp-business-api","whatsapp-calling","whatsapp-chatbot","whatsapp-cloud-api","whatsapp-flows","whatsapp-groups","whatsapp-library","whatsapp-messages","whatsapp-python","whatsapp-qr","whatsapp-templates","whatsapp-webhook-server"],"latest_commit_sha":null,"homepage":"https://pywa.readthedocs.io","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/david-lev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"david-lev","patreon":"davidlev","buy_me_a_coffee":"davidlev","ko_fi":"davidlev","custom":["https://paypal.me/davidlev"]}},"created_at":"2023-06-11T21:23:12.000Z","updated_at":"2026-03-26T22:25:15.000Z","dependencies_parsed_at":"2023-09-26T00:38:41.308Z","dependency_job_id":"70fbdb95-7f47-445e-813a-d561d342c0c8","html_url":"https://github.com/david-lev/pywa","commit_stats":{"total_commits":567,"total_committers":8,"mean_commits":70.875,"dds":0.1164021164021164,"last_synced_commit":"b8c066e94bcbfa37cfcff7c4742543642ff7c973"},"previous_names":["david-lev/pywa"],"tags_count":90,"template":false,"template_full_name":null,"purl":"pkg:github/david-lev/pywa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/david-lev%2Fpywa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/david-lev%2Fpywa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/david-lev%2Fpywa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/david-lev%2Fpywa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/david-lev","download_url":"https://codeload.github.com/david-lev/pywa/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/david-lev%2Fpywa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31312895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["pywa","whatsapp-business-api","whatsapp-calling","whatsapp-chatbot","whatsapp-cloud-api","whatsapp-flows","whatsapp-groups","whatsapp-library","whatsapp-messages","whatsapp-python","whatsapp-qr","whatsapp-templates","whatsapp-webhook-server"],"created_at":"2024-08-04T09:01:18.590Z","updated_at":"2026-04-11T21:48:48.832Z","avatar_url":"https://github.com/david-lev.png","language":"Python","readme":"[//]: # (Logo design by @nyatitilkesh https://github.com/nyatitilkesh | Telegram: @nyatitilkesh)\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/david-lev/pywa\"\u003e\n    \u003cimg src=\"https://pywa.readthedocs.io/en/latest/_static/pywa-logo.png\" width=\"200\" height=\"200\" alt=\"PyWa Logo\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e🚀 Build WhatsApp Bots in Python • Fast. Effortless. Powerful.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csmall\u003e\u003cem\u003e🤖 Hey there! I am using PyWa.\u003c/em\u003e\u003c/small\u003e\n\u003c/p\u003e\n\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/pywa/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/pywa.svg\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/pywa/\"\u003e\u003cimg src=\"https://static.pepy.tech/badge/pywa\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/david-lev/pywa/actions/workflows/tests.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/david-lev/pywa/tests.yml?label=Tests\" /\u003e\u003c/a\u003e\n \u003ca href=\"https://pywa.readthedocs.io\"\u003e\u003cimg src=\"https://readthedocs.org/projects/pywa/badge/?version=latest\u0026\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/david-lev/pywa/blob/master/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/david-lev/pywa\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.codefactor.io/repository/github/david-lev/pywa/overview/master\"\u003e\u003cimg src=\"https://www.codefactor.io/repository/github/david-lev/pywa/badge/master\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://t.me/py_wa\"\u003e\u003cimg src=\"https://badges.aleen42.com/src/telegram.svg\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n**💫 PyWa is an all-in-one Python framework for the WhatsApp Cloud API.**\n\nSend **rich media messages**, use **interactive buttons**, listen to **real-time events**, build and send **flows**, design and send **template messages**, and enjoy **blazing-fast async support** with full integration for **FastAPI, Flask**, and more.\nFully **typed**, **documented**, and **production-ready** — build powerful bots in minutes.\n\n---\n\n\u003e [!IMPORTANT]\n\u003e **Action Required: WhatsApp BSUID Migration**\n\u003e\n\u003e WhatsApp is transitioning to [Business-Scoped User IDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids) (BSUID). This is a breaking change in how user IDs are handled and will be rolled out by Meta in the near future.\n\u003e\n\u003e pywa `4.0.0` (Beta) includes full support for BSUID and is required to ensure compatibility once the change takes effect.\n\u003e\n\u003e * **Install Beta:** `pip install -U pywa --pre`\n\u003e * **Migration Guide:** https://pywa.readthedocs.io/en/dev/content/migration.html#migration-from-3-x-to-4-x\n\u003e * **Issues:** Please report any BSUID-related bugs: https://github.com/david-lev/pywa/issues\n\u003e\n\u003e We recommend upgrading and testing your integration ahead of the official rollout.\n\n---\n\n\n📄 **Quick Documentation Index**\n--------------------------------\n\n\u003e [Get Started](https://pywa.readthedocs.io/en/latest/content/getting-started.html)\n• [Client](https://pywa.readthedocs.io/en/latest/content/client/overview.html)\n• [Handlers](https://pywa.readthedocs.io/en/latest/content/handlers/overview.html)\n• [Listeners](https://pywa.readthedocs.io/en/latest/content/listeners/overview.html)\n• [Updates](https://pywa.readthedocs.io/en/latest/content/updates/overview.html)\n• [Filters](https://pywa.readthedocs.io/en/latest/content/filters/overview.html)\n• [Templates](https://pywa.readthedocs.io/en/latest/content/templates/overview.html)\n• [Flows](https://pywa.readthedocs.io/en/latest/content/flows/overview.html)\n• [Calls](https://pywa.readthedocs.io/en/latest/content/calls/overview.html)\n\n------------------------\n\n⚡ **Why PyWa?**\n---------------\n- **🚀 Fast \u0026 Simple** – Focus on building, not boilerplate.\n- **💬 Rich Messaging** – Text, images, files, audio, locations, contacts, buttons \u0026 more.\n- **📩 Real-Time Updates** – Messages, callbacks, delivery/read receipts, account updates, and more.\n- **🔔 Listeners** – Wait for user replies, clicks, or reactions with ease.\n- **📄 Templates** – Create and send powerful WhatsApp templates.\n- **♻️ Flows** – Build interactive WhatsApp flows effortlessly.\n- **📞 Calls Support** – Receive and handle call events.\n- **🔄 Webhook-Ready** – Native support for Flask, FastAPI, and more.\n- **🔬 Filters** – Advanced filtering for incoming updates.\n- **✅ Production-Ready** – Typed, documented, and fully tested.\n\n------------------------\n\n👨‍💻 **How to Use**\n------------------\n\n- **Send a message**\n\u003e See [WhatsApp Client](https://pywa.readthedocs.io/en/latest/content/client/overview.html) for all the options.\n\n```python\nfrom pywa import WhatsApp, types\n\n# Create a WhatsApp client\nwa = WhatsApp(\n    phone_id=\"100458559237541\",\n    token=\"EAAEZC6hUxkTIB\"\n)\n\n# Send a text message with buttons\nwa.send_message(\n    to=\"9876543210\",\n    text=\"Hello from PyWa!\",\n    buttons=[\n        types.Button(title=\"Menu\", callback_data=\"menu\"),\n        types.Button(title=\"Help\", callback_data=\"help\")\n    ]\n)\n\n# Send a image message from URL\nwa.send_image(\n    to=\"9876543210\",\n    image=\"https://example.com/image.jpg\",\n    caption=\"Check out this image!\",\n)\n```\n\n- **Handle incoming updates** (with [FastAPI](https://fastapi.tiangolo.com/) in this example)\n\u003e See [Handlers](https://pywa.readthedocs.io/en/latest/content/handlers/overview.html) for fully detailed guide.\n\n```python\n# wa.py\nfrom pywa import WhatsApp, filters, types\nfrom fastapi import FastAPI\n\nfastapi_app = FastAPI() # FastAPI server\n\n# Create a WhatsApp client\nwa = WhatsApp(\n    phone_id=1234567890,\n    token=\"************\",\n    server=fastapi_app, # the server to listen to incoming updates\n    callback_url=\"https://yourdomain.com/\",  # the public URL of your server\n    verify_token=\"xyz123\", # some random string to verify the webhook\n    app_id=123456, # your app id\n    app_secret=\"*******\" # your app secret\n)\n\n# Register callback to handle incoming messages\n@wa.on_message(filters.matches(\"Hello\", \"Hi\")) # Filter to match text messages that contain \"Hello\" or \"Hi\"\ndef hello(client: WhatsApp, msg: types.Message):\n    msg.react(\"👋\") # React to the message with a wave emoji\n    msg.reply_text( # Short reply to the message\n        text=f\"Hello {msg.from_user.name}!\", # Greet the user\n        buttons=[ # Add buttons to the reply\n            types.Button(\n                title=\"About me\",\n                callback_data=\"about_me\" # Callback data to identify the click\n            )\n        ]\n    )\n    # Use the `wait_for_reply` listener to wait for a reply from the user\n    age = msg.reply(text=\"What's your age?\").wait_for_reply(filters=filters.text).text\n    msg.reply_text(f\"Your age is {age}.\")\n\n# Register another callback to handle incoming button clicks\n@wa.on_callback_button(filters.matches(\"about_me\")) # Filter to match the button click\ndef click_me(client: WhatsApp, clb: types.CallbackButton):\n    clb.reply_text(f\"Hello {clb.from_user.name}, I am a WhatsApp bot built with PyWa!\") # Reply to the button click\n```\n\n- To run the server, use [fastapi-cli](https://fastapi.tiangolo.com/#run-it) (`pip install \"fastapi[standard]\"`):\n\n```bash\nfastapi dev wa.py  # see uvicorn docs for more options (port, host, etc.)\n```\n\n- **Async Usage**\n\n- PyWa also supports async usage with the same API. This is useful if you want to use async/await in your code. To use the async version, replace **all** the imports from `pywa` to `pywa_async`:\n\n```python\n# wa.py\nimport fastapi\nfrom pywa_async import WhatsApp, types  # Same API, just different imports\n\nfastapi_app = fastapi.FastAPI()\nwa = WhatsApp(..., server=fastapi_app)\n\nasync def main():\n    await wa.send_message(...) # async call\n\n@wa.on_message\nasync def hello(_: WhatsApp, msg: types.Message): # async callback\n    await msg.react(\"👋\")\n    await msg.reply(\"Hello from PyWa Async!\")\n```\n\n- **Create and send template messages**\n\u003e See [Templates](https://pywa.readthedocs.io/en/latest/content/templates/overview.html) for more details and examples.\n\n```python\nfrom pywa import WhatsApp\nfrom pywa.types.templates import *\n\nwa = WhatsApp(..., business_account_id=123456)\n\n# Create a template\nwa.create_template(\n    template=Template(\n        name=\"buy_new_iphone_x\",\n        category=TemplateCategory.MARKETING,\n        language=TemplateLanguage.ENGLISH_US,\n        parameter_format=ParamFormat.NAMED,\n        components=[\n            ht := HeaderText(\"The New iPhone {{iphone_num}} is here!\", iphone_num=15),\n            bt := BodyText(\"Buy now and use the code {{code}} to get {{per}}% off!\", code=\"WA_IPHONE_15\", per=15),\n            FooterText(text=\"Powered by PyWa\"),\n            Buttons(\n                buttons=[\n                    url := URLButton(text=\"Buy Now\", url=\"https://example.com/shop/{{1}}\", example=\"iphone15\"),\n                    PhoneNumberButton(text=\"Call Us\", phone_number=\"1234567890\"),\n                    qrb1 := QuickReplyButton(text=\"Unsubscribe from marketing messages\"),\n                    qrb2 := QuickReplyButton(text=\"Unsubscribe from all messages\"),\n                ]\n            ),\n\n        ]\n    ),\n)\n\n# Send the template message\nwa.send_template(\n    to=\"9876543210\",\n    name=\"buy_new_iphone_x\",\n    language=TemplateLanguage.ENGLISH_US,\n    params=[\n        ht.params(iphone_num=30),\n        bt.params(code=\"WA_IPHONE_30\", per=30),\n        url.params(url_variable=\"iphone30\", index=0),\n        qrb1.params(callback_data=\"unsubscribe_from_marketing_messages\", index=1),\n        qrb2.params(callback_data=\"unsubscribe_from_all_messages\", index=2),\n    ]\n)\n```\n\n- **Create and send flows**\n\u003e See [Flows](https://pywa.readthedocs.io/en/latest/content/flows/overview.html) for much more details and examples.\n\n```python\nfrom pywa import WhatsApp, types\nfrom pywa.types.flows import *\n\n# Create a WhatsApp client\nwa = WhatsApp(..., business_account_id=123456)\n\n# Build a flow\nmy_flow_json = FlowJSON(\n    screens=[\n        Screen(\n            id=\"NEWSLETTER\",\n            title=\"PyWa Newsletter\",\n            layout=Layout(\n                children=[\n                    TextHeading(text=\"Subscribe to our newsletter\"),\n                    name := TextInput(\n                        name=\"name\",\n                        label=\"Name\",\n                        input_type=InputType.TEXT,\n                        required=False,\n                    ),\n                    email := TextInput(\n                        name=\"email\",\n                        label=\"Email\",\n                        input_type=InputType.EMAIL,\n                        required=True,\n                    ),\n                    Footer(\n                        label=\"Subscribe\",\n                        on_click_action=CompleteAction(\n                            payload={ # Payload to send to the server\n                                \"name\": name.ref,\n                                \"email\": email.ref,\n                            }\n                        )\n                    )\n                ]\n            )\n        )\n    ]\n)\n\n# Create the flow\nwa.create_flow(\n    name=\"subscribe_to_newsletter\",\n    categories=[FlowCategory.SIGN_UP, FlowCategory.OTHER],\n    flow_json=my_flow_json,\n    publish=True\n)\n\n# Send the flow to a user\nwa.send_text(\n    to=\"9876543210\",\n    text=\"Hello from PyWa!\",\n    buttons=types.FlowButton(\n        title=\"Subscribe to our newsletter!\",\n        flow_name=\"subscribe_to_newsletter\",\n    )\n)\n\n# Handle the flow response\n@wa.on_flow_completion\ndef handle_flow_response(_: WhatsApp, flow: types.FlowCompletion):\n    flow.reply(\n        text=f\"Thank you for subscribing to our newsletter, {flow.response['name']}! \"\n             f\"We will send you updates to {flow.response['email']}.\",\n        buttons=[types.Button(title=\"Unsubscribe\", callback_data=\"unsubscribe\")]\n    )\n```\n\n🎛 **Installation**\n--------------------\n\n- **Install using pip3:**\n\n```bash\npip3 install -U pywa\n```\n\n- **Install from source (the bleeding edge):**\n\n```bash\npip3 install -U git+https://github.com/david-lev/pywa.git\n```\n\n- **If you going to use the webhook features, here is shortcut to install the required dependencies:**\n\n```bash\npip3 install -U \"pywa[fastapi]\"\npip3 install -U \"pywa[flask]\"\n```\n\n- **If you going to use the Flow features and want to use the default FlowRequestDecryptor and the default FlowResponseEncryptor, here is shortcut to install the required dependencies:**\n\n```bash\npip3 install -U \"pywa[cryptography]\"\n```\n\n💾 **Requirements**\n--------------------\n\n- Python 3.10 or higher - https://www.python.org\n\n📖 **Setup and Usage**\n-----------------------\n\nSee the [Documentation](https://pywa.readthedocs.io/) for detailed instructions\n\n\n⚖️ **License**\n---------------\n\nThis project is licensed under the MIT License - see the\n[LICENSE](https://github.com/david-lev/pywa/blob/master/LICENSE) file for details\n\n\n🔱 **Contributing**\n--------------------\n\nContributions are welcome! Please see the [Contributing Guide](https://github.com/david-lev/pywa/blob/master/CONTRIBUTING.md) for more information.\n\n🗣 **Community**\n--------------------\n\nJoin the [Telegram Group](https://t.me/pywachat) to discuss, ask questions, and share your projects built with PyWa!\n","funding_links":["https://github.com/sponsors/david-lev","https://patreon.com/davidlev","https://buymeacoffee.com/davidlev","https://ko-fi.com/davidlev","https://paypal.me/davidlev"],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavid-lev%2Fpywa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavid-lev%2Fpywa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavid-lev%2Fpywa/lists"}