[server] update docs

README.md

@@ -14,7 +14,7 @@ ________________________
 
 ________________________
 
-**PyWa is a Fast, Simple, Modern and easy-to-use Python framework for building WhatsApp bots using the WhatsApp Cloud API.**
+**PyWa is a Fast, Simple, Modern and easy-to-use asynchronous Python framework for building WhatsApp bots using the WhatsApp Cloud API.**
 
 📄 **Quick Documentation Index**
 --------------------------------
@@ -63,6 +63,7 @@ wa.send_message(
 ```
 
 - To listen to updates, create a `WhatsApp` client, pass a web server app ([Flask](https://flask.palletsprojects.com/) in this example) and register callbacks:
+
 > See [Handlers](https://pywa.readthedocs.io/en/latest/content/handlers/overview.html) for more information.
 
 ```python
@@ -142,8 +143,9 @@ See the [Documentation](https://pywa.readthedocs.io/) for detailed instructions
 ☑️ **TODO**
 ------------
 
-- Add support for async
-- Add support for more web frameworks (``Django``, ``Starlette``, etc.)
+- ~~Add support for async~~
+- ~~Add support for more web frameworks (Django, aiohttp, etc.)~~
+- ~~Add support for flows~~
 - Add support for more types of updates (``account_alerts``, ``phone_number_quality_updates``, ``template_category_updates``, etc.)
 - Add more examples and guides
 

docs/source/content/client/overview.rst

@@ -17,6 +17,31 @@ The :class:`~WhatsApp` client has 3 main responsibilities:
 for sending messages and the other API calls, you will need to provide an phone number id that connects to the WhatsApp Cloud API.
 for listening to incoming messages and events, you will need to tell WhatsApp to send the events to a webhook that you provide.
 
+.. tip::
+    :class: note
+
+    Pywa provides two clients, synchronous and asynchronous, you can choose the one that fits your needs.
+
+    .. code-block:: python
+        :emphasize-lines: 1
+
+        from pywa import WhatsApp, types
+        wa = WhatsApp(...)
+
+        @wa.on_message()
+        def on_message(_: WhatsApp, msg: types.Message):
+            msg.reply("Hello!")
+
+    .. code-block:: python
+        :emphasize-lines: 1
+
+        from pywa_async import WhatsApp, types
+        wa = WhatsApp(...)
+
+        @wa.on_message()
+        async def on_message(_: WhatsApp, msg: types.Message):
+            await msg.reply("Hello!")
+
 .. autoclass:: WhatsApp()
     :members: __init__
 
@@ -69,6 +94,10 @@ The available methods are:
    * - Commerce
      - :meth:`~WhatsApp.get_commerce_settings`,
        :meth:`~WhatsApp.update_commerce_settings`
+   * - Server
+     - :meth:`~WhatsApp.webhook_update_handler`,
+       :meth:`~WhatsApp.webhook_challenge_handler`,
+       :meth:`~WhatsApp.get_flow_request_handler`
 
 .. toctree::
     client_reference

docs/source/content/handlers/overview.rst

@@ -233,13 +233,17 @@ is received from WhatsApp.
 
     A callback function can be both a synchronous or an asynchronous function.
 
+    .. code-block:: python
+        :emphasize-lines: 1
+
+        from pywa import WhatsApp
 
-.. attention::
-    :class: warning
+        wa = WhatsApp(...)
 
-    The callback function must finish within ~25 seconds. Otherwise, WhatsApp will consider it as a timeout and will retry sending the update.
+        @wa.on_message()
+        async def handle_message(client: WhatsApp, message: Message):
+            print(message)
 
-    If you need to do a long operation, you may want to run it in a separate thread or process, or use an task queue.
 
 
 A callback function is a function that takes two (positional) arguments:

pywa/server.py

@@ -169,6 +169,9 @@ async def my_challenge_handler(req: web.Request) -> web.Response:
                 app = web.Application()
                 app.add_routes([web.get("/my_webhook", my_challenge_handler)])
 
+                if __name__ == "__main__":
+                    web.run_app(app, port=...)
+
         Args:
             vt: The verify token param (utils.HUB_VT).
             ch: The challenge param (utils.HUB_CH).
@@ -209,6 +212,12 @@ async def my_webhook_handler(req: web.Request) -> web.Response:
                         res, status_code = await wa.webhook_update_handler(await req.json())
                         return web.Response(text=res, status=status_code)
 
+                    app = web.Application()
+                    app.add_routes([web.post("/my_webhook", my_webhook_handler)])
+
+                    if __name__ == "__main__":
+                        web.run_app(app, port=...)
+
         Args:
             update: The incoming update from the webhook.
 
@@ -304,7 +313,7 @@ async def fastapi_webhook(req: fastapi.Request) -> fastapi.Response:
 
             case _:
                 raise ValueError(
-                    f"The `server` must be one of {utils.ServerType.protocols_names()}"
+                    f"The `server` must be one of {utils.ServerType.protocols_names()} or None for a custom server"
                 )
 
     async def _call_handlers(self: "WhatsApp", update: dict) -> None:
@@ -476,7 +485,36 @@ def get_flow_request_handler(
         Get a function that handles the incoming flow requests.
 
         - Use this function only if you are using a custom server (e.g. Django, aiohttp, etc.), else use the
-            :meth:`WhatsApp.on_flow_request` decorator.
+          :meth:`WhatsApp.on_flow_request` decorator.
+
+
+        Example:
+
+            .. code-block:: python
+
+                from aiohttp import web
+                from pywa import WhatsApp, flows
+
+                wa = WhatsApp(..., server=None, business_private_key="...", business_private_key_password="...")
+
+                async def my_flow_callback(wa: WhatsApp, request: flows.FlowRequest) -> flows.FlowResponse:
+                    ...
+
+                flow_handler = wa.get_flow_request_handler(
+                    endpoint="/flow",
+                    callback=my_flow_callback,
+                )
+
+                async def my_flow_endpoint(req: web.Request) -> web.Response:
+                    response, status_code = await flow_handler(await req.json())
+                    return web.Response(text=response, status=status_code)
+
+                app = web.Application()
+                app.add_routes([web.post("/flow", my_flow_endpoint)])
+
+                if __name__ == "__main__":
+                    web.run_app(app, port=...)
+
 
         Args:
             endpoint: The endpoint to listen to (The endpoint uri you set to the flow. e.g ``/feedback_flow``).