feat: add stage2 customer gateway types

docs/06-cli.md

@@ -44,6 +44,28 @@ wasila gateway add customer webhook
 
 Enables the first generic HTTP webhook gateway for customer conversations.
 
+Now supported customer gateway types are:
+
+```bash
+wasila gateway add customer webhook
+wasila gateway add customer telegram
+wasila gateway add customer whatsapp
+```
+
+When customer gateway type is `telegram` or `whatsapp`, daemon also accepts dedicated endpoints:
+
+```bash
+POST /webhook/telegram
+POST /webhook/whatsapp
+```
+
+and fallback endpoint:
+
+```bash
+POST /webhook/customer
+POST /customer
+```
+
 ### Add Owner Gateway
 
 ```bash
@@ -60,6 +82,7 @@ wasila gateway add owner hermes
 ```
 
 OpenClaw and Hermes are configured as dedicated gateway types and currently resolve through the same webhook transport for bootstrap compatibility.
+Customer gateway expansion (`telegram`, `whatsapp`) is now supported in Stage 2 and currently shares the same webhook transport for bootstrap compatibility.
 
 ### Start Daemon
 

src/wasila/cli/main.py

@@ -72,7 +72,11 @@ def build_parser() -> argparse.ArgumentParser:
     gateway_sub = gateway_parser.add_subparsers(dest="gateway_command", required=True)
     gateway_add = gateway_sub.add_parser("add", help="Set gateway type and metadata.")
     gateway_add.add_argument("role", choices=["customer", "owner"])
-    gateway_add.add_argument("type", choices=["webhook", "openclaw", "hermes"])
+    gateway_add.add_argument(
+        "type",
+        choices=["webhook", "telegram", "whatsapp", "openclaw", "hermes"],
+        help="Gateway type to use for the selected role.",
+    )
     gateway_add.add_argument("--metadata", action="append", default=[], help="KEY=VALUE metadata")
     gateway_add.set_defaults(func=handle_gateway_add)
 
@@ -163,8 +167,10 @@ def handle_provider_set(args: argparse.Namespace) -> None:
 def handle_gateway_add(args: argparse.Namespace) -> None:
     config = _load_or_default(args.config)
     metadata = _parse_metadata_args(args.metadata)
-    if args.role == "customer" and args.type not in {"webhook"}:
-        raise SystemExit("customer gateway currently only supports webhook in Stage 1")
+    if args.role == "customer" and args.type not in {"webhook", "telegram", "whatsapp"}:
+        raise SystemExit("customer gateway only supports webhook, telegram, or whatsapp")
+    if args.role == "owner" and args.type not in {"webhook", "openclaw", "hermes"}:
+        raise SystemExit("owner gateway only supports webhook, openclaw, or hermes")
     if args.role == "customer":
         config.customer_gateway = GatewayConfig(
             type=args.type,
@@ -190,8 +196,8 @@ def handle_daemon_start(args: argparse.Namespace) -> None:
         config.customer_gateway.metadata,
     )
 
-    def process(event_payload: dict[str, Any]) -> dict[str, Any]:
-        event = gateway.normalize(event_payload)
+    def process(event_payload: dict[str, Any] | CustomerEvent) -> dict[str, Any]:
+        event = event_payload if isinstance(event_payload, CustomerEvent) else gateway.normalize(event_payload)
         result = workflow.run(event)
         return {
             "customer_response": result.customer_response,
@@ -200,7 +206,17 @@ def process(event_payload: dict[str, Any]) -> dict[str, Any]:
             "gateway": event.gateway,
         }
 
-    daemon = WebhookDaemon(handler=process, gateway=gateway, host=args.host, port=args.port)
+    route_gateways = {}
+    if gateway.name in {"telegram", "whatsapp"}:
+        route_gateways[f"/webhook/{gateway.name}"] = gateway
+
+    daemon = WebhookDaemon(
+        handler=process,
+        gateway=gateway,
+        route_gateways=route_gateways,
+        host=args.host,
+        port=args.port,
+    )
     daemon.start()
 
 

src/wasila/gateways/__init__.py

@@ -2,13 +2,179 @@
 
 from __future__ import annotations
 
-from typing import Any
-
+from wasila.core.contracts import CustomerEvent
 from wasila.core.ports import CustomerGateway, OwnerGateway
 
 from wasila.gateways.webhook import WebhookCustomerGateway, WebhookOwnerGateway
 
 
+class TelegramCustomerGateway(WebhookCustomerGateway):
+    """Customer gateway adapter for Telegram payloads.
+
+    Stage 2 keeps Telegram transport compatible with webhook payload ingestion.
+    """
+
+    def __init__(self, metadata: dict[str, str] | None = None) -> None:
+        super().__init__(metadata=metadata)
+        self.name = "telegram"
+
+    def normalize(self, payload: dict) -> CustomerEvent:
+        message = payload.get("message")
+        raw_text = message if isinstance(message, str) else (
+            message.get("text")
+            if isinstance(message, dict)
+            else ""
+        )
+        if raw_text == "" and isinstance(message, dict):
+            raw_text = message.get("body") or message.get("caption") or ""
+        if raw_text == "":
+            raw_text = payload.get("text") or payload.get("body") or ""
+
+        if not isinstance(raw_text, str):
+            raw_text = ""
+
+        sender = payload.get("from")
+        if not isinstance(sender, dict):
+            sender = payload.get("sender")
+        if not isinstance(sender, dict) and isinstance(message, dict):
+            sender = message.get("from")
+
+        event_id = payload.get("event_id")
+        if event_id is not None and not isinstance(event_id, str):
+            event_id = str(event_id)
+        sender_id = ""
+        sender_name = ""
+        if isinstance(sender, dict):
+            sender_id = str(
+                sender.get("id")
+                or sender.get("username")
+                or sender.get("first_name")
+                or ""
+            )
+            sender_name = str(sender.get("first_name") or sender.get("username") or "")
+
+        return CustomerEvent(
+            gateway=payload.get("gateway", self.metadata.get("id", "telegram")),
+            gateway_role=payload.get("gateway_role", "customer"),
+            external_conversation_id=str(
+                payload.get("external_conversation_id")
+                or (payload.get("chat") or {}).get("id")
+                or payload.get("conversation_id")
+                or ""
+            ),
+            external_customer_id=str(payload.get("external_customer_id") or payload.get("customer_id") or sender_id or ""),
+            message_text=raw_text,
+            message_timestamp=payload.get("message_timestamp") or "",
+            id=event_id,
+            customer_id=payload.get("customer_id"),
+            metadata_json={
+                "name": sender_name or payload.get("name") or payload.get("display_name"),
+                "source": "telegram",
+                "raw": payload,
+            },
+        )
+
+
+class WhatsAppCustomerGateway(WebhookCustomerGateway):
+    """Customer gateway adapter for WhatsApp payloads.
+
+    Stage 2 keeps WhatsApp transport compatible with webhook payload ingestion.
+    """
+
+    def __init__(self, metadata: dict[str, str] | None = None) -> None:
+        super().__init__(metadata=metadata)
+        self.name = "whatsapp"
+
+    def normalize(self, payload: dict) -> CustomerEvent:
+        raw_text = payload.get("message") or payload.get("body") or ""
+        raw_msg: dict | None = None
+        if isinstance(payload.get("entry"), list) and payload["entry"]:
+            first_entry = payload["entry"][0]
+            if isinstance(first_entry, dict):
+                changes = first_entry.get("changes")
+                if isinstance(changes, list) and changes:
+                    raw_msg = changes[0]
+                if isinstance(raw_msg, dict):
+                    value = raw_msg.get("value")
+                    if isinstance(value, dict):
+                        messages = value.get("messages")
+                        if isinstance(messages, list) and messages:
+                            raw_msg = messages[0]
+                if isinstance(raw_msg, dict):
+                    text_candidate = (
+                        raw_msg.get("text")
+                        if isinstance(raw_msg.get("text"), str)
+                        else (
+                            raw_msg.get("text", {}).get("body")
+                            if isinstance(raw_msg.get("text"), dict)
+                            else None
+                        )
+                    )
+                    if isinstance(text_candidate, str):
+                        raw_text = text_candidate
+                    else:
+                        raw_text = raw_msg.get("message") or raw_msg.get("body") or raw_text
+
+                    payload["from"] = raw_msg.get("from", first_entry.get("from"))
+
+        if isinstance(raw_text, dict):
+            raw_text = ""
+        if not isinstance(raw_text, str):
+            raw_text = str(raw_text)
+
+        event_id = payload.get("event_id")
+        if event_id is not None and not isinstance(event_id, str):
+            event_id = str(event_id)
+
+        sender = payload.get("from")
+        if isinstance(raw_msg, dict) and isinstance(raw_msg.get("from"), dict):
+            sender = raw_msg.get("from")
+
+        sender_id = ""
+        sender_name = ""
+        if isinstance(sender, dict):
+            sender_id = str(
+                sender.get("id")
+                or sender.get("wa_id")
+                or sender.get("phone")
+                or sender.get("username")
+                or ""
+            )
+            sender_name = str(sender.get("name") or sender.get("profile_name") or sender_id)
+        else:
+            sender_id = str(sender or "")
+
+        if event_id is None and isinstance(raw_msg, dict):
+            msg_event_id = raw_msg.get("id")
+            if msg_event_id is not None and not isinstance(msg_event_id, str):
+                msg_event_id = str(msg_event_id)
+            if msg_event_id is not None:
+                event_id = msg_event_id
+
+        return CustomerEvent(
+            gateway=payload.get("gateway", self.metadata.get("id", "whatsapp")),
+            gateway_role=payload.get("gateway_role", "customer"),
+            external_conversation_id=str(
+                payload.get("external_conversation_id")
+                or (raw_msg or {}).get("conversation")
+                or payload.get("conversation_id")
+                or payload.get("wa_id")
+                or sender_id
+                or ""
+            ),
+            external_customer_id=str(payload.get("external_customer_id") or payload.get("customer_id") or sender_id or ""),
+            message_text=raw_text,
+            message_timestamp=payload.get("message_timestamp") or "",
+            id=event_id,
+            customer_id=payload.get("customer_id"),
+            metadata_json={
+                "name": sender_name or payload.get("name") or payload.get("display_name"),
+                "source": "whatsapp",
+                "raw": payload,
+            },
+        )
+
+
 class OpenClawOwnerGateway(WebhookOwnerGateway):
     """Owner gateway adapter for OpenClaw.
 
@@ -35,6 +201,10 @@ def __init__(self, metadata: dict[str, str] | None = None) -> None:
 def build_customer_gateway(gateway_type: str, metadata: dict[str, str] | None = None) -> CustomerGateway:
     if gateway_type == "webhook":
         return WebhookCustomerGateway(metadata=metadata)
+    if gateway_type == "telegram":
+        return TelegramCustomerGateway(metadata=metadata)
+    if gateway_type == "whatsapp":
+        return WhatsAppCustomerGateway(metadata=metadata)
     raise ValueError(f"unsupported customer gateway type: {gateway_type}")
 
 
@@ -52,6 +222,8 @@ def build_owner_gateway(gateway_type: str, metadata: dict[str, str] | None = Non
 __all__ = [
     "WebhookCustomerGateway",
     "WebhookOwnerGateway",
+    "TelegramCustomerGateway",
+    "WhatsAppCustomerGateway",
     "OpenClawOwnerGateway",
     "HermesOwnerGateway",
     "build_customer_gateway",