adapter.py 65 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137
  1. """WhatsApp Cloud API adapter — official Meta WhatsApp Business Platform (Graph API +
  2. aiohttp webhook). Complements the Baileys bridge plugin; both share gating / mention /
  3. formatting behavior via ``WhatsAppBehaviorMixin``.
  4. Required env: WHATSAPP_CLOUD_PHONE_NUMBER_ID, WHATSAPP_CLOUD_ACCESS_TOKEN. Optional:
  5. WHATSAPP_CLOUD_APP_ID, _APP_SECRET (HMAC key for X-Hub-Signature-256),
  6. _WABA_ID (when set, inbound webhooks must match it),
  7. _VERIFY_TOKEN (hub.verify_token), _WEBHOOK_HOST (unset → dual-stack all interfaces),
  8. _WEBHOOK_PORT (8090), _WEBHOOK_PATH (/whatsapp/webhook), _API_VERSION (v20.0)."""
  9. from __future__ import annotations
  10. import asyncio
  11. import contextlib
  12. import hashlib
  13. import hmac
  14. import importlib
  15. import json
  16. import logging
  17. import mimetypes
  18. import os
  19. import re
  20. import shutil
  21. import uuid
  22. from collections import OrderedDict
  23. from pathlib import Path
  24. from typing import Any, Dict, Optional
  25. try:
  26. from aiohttp import web
  27. AIOHTTP_AVAILABLE = True
  28. except ImportError:
  29. AIOHTTP_AVAILABLE = False
  30. web = None # type: ignore[assignment]
  31. try:
  32. import httpx
  33. HTTPX_AVAILABLE = True
  34. except ImportError:
  35. HTTPX_AVAILABLE = False
  36. httpx = None # type: ignore[assignment]
  37. from gateway.config import Platform, PlatformConfig
  38. from gateway.platforms._shared import config_connected_extra
  39. from agent.i18n import t
  40. from gateway.platforms.base import BasePlatformAdapter, ExecApprovalPrompt, SendResult, transcode_to_ogg_opus
  41. from gateway.platforms.base_exec_approval import ea_header_text
  42. from gateway.platforms.helpers import bounded_put
  43. from gateway.platforms.event import MessageEvent, MessageType
  44. from gateway.platforms.whatsapp_common import WhatsAppBehaviorMixin, _get_wsecret
  45. from gateway.platforms.access_policy_mixin import OPTIN_TRUTHY as _OPTIN_TRUTHY
  46. from gateway.platforms.media_cache import ext_for_mime
  47. from gateway import rich_sent_store
  48. from hermes_constants import get_hermes_dir
  49. logger = logging.getLogger(__name__)
  50. DEFAULT_API_VERSION = "v20.0"
  51. # ``None`` → aiohttp binds one socket per address family; "0.0.0.0" was unreachable on IPv6-only hosts.
  52. DEFAULT_WEBHOOK_HOST = None
  53. DEFAULT_WEBHOOK_PORT = 8090
  54. DEFAULT_WEBHOOK_PATH = "/whatsapp/webhook"
  55. GRAPH_API_BASE = "https://graph.facebook.com"
  56. WEBHOOK_MAX_BODY_BYTES = 3 * 1024 * 1024
  57. # Meta retries failed webhooks for up to 7 days, but the practical duplicate risk is
  58. # within minutes — 5000 FIFO entries bounds memory and covers that.
  59. WAMID_DEDUP_CACHE_SIZE = 5000
  60. INTERACTIVE_STATE_CACHE_SIZE = 1000 # interactive-button state dicts + per-chat last-wamid cache
  61. # Meta's hard per-type caps for /media (developers.facebook.com/docs/whatsapp/cloud-api/reference/media);
  62. # refuse locally instead of round-tripping to Graph just to be rejected.
  63. _MEDIA_SIZE_LIMITS = {
  64. "image": 5 * 1024 * 1024, "video": 16 * 1024 * 1024, "audio": 16 * 1024 * 1024,
  65. "document": 100 * 1024 * 1024, "sticker": 100 * 1024,
  66. }
  67. # Default mime types when we can't guess from the path's extension.
  68. _DEFAULT_MIME = {
  69. "image": "image/jpeg", "video": "video/mp4", "audio": "audio/mpeg",
  70. "document": "application/octet-stream", "sticker": "image/webp",
  71. }
  72. # None → MP3 voice falls back to an "audio file attachment" rendering in WhatsApp.
  73. _FFMPEG_PATH = shutil.which("ffmpeg")
  74. # mimetypes returns RFC-correct but uncommon extensions (audio/ogg → .oga, image/jpeg → .jpe);
  75. # downstream STT/vision whitelists the in-the-wild forms, so pin the few Meta sends.
  76. _WHATSAPP_MIME_EXTENSION_OVERRIDES: dict[str, str] = {
  77. "audio/ogg": ".ogg", "audio/x-opus+ogg": ".ogg", "audio/opus": ".ogg",
  78. "audio/mp4": ".m4a", "audio/x-m4a": ".m4a", "image/jpeg": ".jpg",
  79. }
  80. _INBOUND_MEDIA_KINDS = {"image", "video", "audio", "voice", "document", "sticker"}
  81. # ``system`` = user_changed_number / user_changed_user_id (BSUID rotation, Aug 2026);
  82. # ``reaction`` = emoji tap (extension point if emoji-approval flows ever land);
  83. # ``unsupported``/``unknown`` = payloads the Cloud API cannot render.
  84. _CONTENTLESS_KINDS = {"system", "reaction", "unsupported", "unknown"}
  85. _TEXT_INJECT_EXTS = {".txt", ".md", ".csv", ".json", ".xml", ".yaml", ".yml", ".log", ".py", ".js", ".ts", ".html", ".css"}
  86. _MAX_TEXT_INJECT_BYTES = 100 * 1024 # matches Telegram/Discord/Slack
  87. _MESSAGE_TYPE_BY_KIND = {
  88. "text": MessageType.TEXT, "image": MessageType.PHOTO, "video": MessageType.VIDEO,
  89. "audio": MessageType.VOICE, "voice": MessageType.VOICE, "document": MessageType.DOCUMENT,
  90. "sticker": MessageType.PHOTO, "button": MessageType.TEXT, "interactive": MessageType.TEXT,
  91. "location": MessageType.TEXT, "contacts": MessageType.TEXT,
  92. }
  93. _HTTP_PREFIXES = ("http://", "https://")
  94. def _interactive_inner(raw_message: dict[str, Any]) -> dict[str, Any]:
  95. """``button_reply`` (type=button) or ``list_reply`` (type=list); both carry id+title."""
  96. inter = raw_message.get("interactive") or {}
  97. return inter.get("button_reply") or inter.get("list_reply") or {}
  98. # Inbound message type → body text extractor; media kinds use the caption.
  99. _BODY_BY_KIND = {
  100. "text": lambda m: (m.get("text") or {}).get("body"),
  101. "button": lambda m: (m.get("button") or {}).get("text"),
  102. "interactive": lambda m: _interactive_inner(m).get("title"),
  103. **{kind: (lambda m, k=kind: (m.get(k) or {}).get("caption")) for kind in _INBOUND_MEDIA_KINDS},
  104. }
  105. async def _read_limited_request_body(request: Any, max_bytes: int) -> bytes:
  106. """Read at most ``max_bytes`` from an aiohttp request body."""
  107. try:
  108. body = await request.content.readexactly(max_bytes + 1)
  109. except asyncio.IncompleteReadError as exc:
  110. body = exc.partial
  111. if len(body) > max_bytes:
  112. raise ValueError("payload too large")
  113. return body
  114. def _ext_for_mime(mime: str) -> Optional[str]:
  115. """Mime → on-disk extension: WhatsApp overrides → mimetypes → None (never the shared default table)."""
  116. return ext_for_mime(mime, overrides=_WHATSAPP_MIME_EXTENSION_OVERRIDES, use_defaults=False, use_mimetypes=True, fallback=None) if mime else None
  117. def _cloud_allow_all_opted_in() -> bool:
  118. return str(_get_wsecret("WHATSAPP_CLOUD_ALLOW_ALL_USERS", default="") or "").strip().lower() in _OPTIN_TRUTHY
  119. def _reply_to_from(metadata: Optional[dict[str, Any]]) -> Optional[str]:
  120. return (metadata or {}).get("reply_to_message_id")
  121. def _optional_module(name: str, unavailable_log: str) -> Any:
  122. """Lazy-import a resolver module (tools.* may be absent in slim installs); None + warning if missing."""
  123. try:
  124. return importlib.import_module(name)
  125. except ImportError:
  126. logger.warning(unavailable_log)
  127. return None
  128. # Under the hermes dir so it survives restarts/reloads — same as the Baileys bridge.
  129. _INBOUND_MEDIA_CACHE = Path(get_hermes_dir("platforms/whatsapp_cloud/media", "whatsapp_cloud/media"))
  130. def check_whatsapp_cloud_requirements() -> bool:
  131. """aiohttp (webhook server) + httpx (Graph API) — both default deps."""
  132. return AIOHTTP_AVAILABLE and HTTPX_AVAILABLE
  133. class WhatsAppCloudAdapter(WhatsAppBehaviorMixin, BasePlatformAdapter):
  134. """Outbound: Graph ``/<api_version>/<phone_id>/messages``; inbound: aiohttp webhook
  135. server. The mixin comes first so its ``format_message`` overrides the base one."""
  136. # Answers /p/<profile>/... on the default listener for a served secondary (shared_ingress).
  137. serves_profile_prefix: bool = True
  138. splits_long_messages = True # send() chunks via truncate_message()
  139. def __init__(self, config: PlatformConfig):
  140. super().__init__(config, Platform.WHATSAPP_CLOUD)
  141. extra = config.extra or {}
  142. # `or ""`: an empty YAML value (null) is unset, not the guessable HMAC key "None".
  143. self._phone_number_id, self._access_token, self._app_id, self._app_secret, self._waba_id, self._verify_token = (
  144. str(extra.get(key) or "").strip()
  145. for key in ("phone_number_id", "access_token", "app_id", "app_secret", "waba_id", "verify_token")
  146. )
  147. # Falsy host (None/"") collapses to the dual-stack default.
  148. self._webhook_host: Optional[str] = str(extra.get("webhook_host") or DEFAULT_WEBHOOK_HOST or "") or None
  149. self._webhook_port: int = int(extra.get("webhook_port", DEFAULT_WEBHOOK_PORT))
  150. self._webhook_path: str = self._normalize_path(extra.get("webhook_path", DEFAULT_WEBHOOK_PATH))
  151. self._health_path: str = self._normalize_path(extra.get("health_path", "/health"))
  152. self._api_version: str = str(extra.get("api_version", DEFAULT_API_VERSION))
  153. # Behavior-mixin contract attributes. WHATSAPP_CLOUD_* env vars take precedence so
  154. # both adapters can run in parallel with independent policies; shared WHATSAPP_*
  155. # names remain the fallback. Allowlist: config, then legacy ALLOW_FROM, then ALLOWED_USERS.
  156. self._reply_prefix: Optional[str] = extra.get("reply_prefix")
  157. allow_raw = self._select_dm_allowlist(extra, ("WHATSAPP_CLOUD_ALLOW_FROM", "WHATSAPP_CLOUD_ALLOWED_USERS"), _get_wsecret)
  158. self._allow_from: set[str] = self._normalize_allow_ids(self._coerce_allow_list(allow_raw))
  159. # DM policy default: "open" if the operator opted into allow-all, else
  160. # "allowlist" when one is configured (so it is enforced), else "open".
  161. default_dm_policy = "allowlist" if self._allow_from and not _cloud_allow_all_opted_in() else "open"
  162. self._dm_policy: str = str(
  163. extra.get("dm_policy") or _get_wsecret("WHATSAPP_CLOUD_DM_POLICY")
  164. or _get_wsecret("WHATSAPP_DM_POLICY") or default_dm_policy
  165. ).strip().lower()
  166. self._group_policy: str = str(
  167. extra.get("group_policy") or _get_wsecret("WHATSAPP_CLOUD_GROUP_POLICY")
  168. or _get_wsecret("WHATSAPP_GROUP_POLICY", default="open") or "open"
  169. ).strip().lower()
  170. _, raw_groups = self._select_allowlist(
  171. extra, ("group_allow_from", "groupAllowFrom"), ("WHATSAPP_CLOUD_GROUP_ALLOW_FROM",), _get_wsecret)
  172. self._group_allow_from: set[str] = self._normalize_allow_ids(self._coerce_allow_list(raw_groups))
  173. self._mention_patterns = self._compile_mention_patterns()
  174. # Webhook dedup state (in-memory, FIFO-evicted) and counters.
  175. self._seen_wamids: OrderedDict[str, bool] = OrderedDict()
  176. self._duplicate_count = self._accepted_count = self._rejected_signature_count = 0
  177. self._warned_no_ffmpeg: bool = False
  178. # Latest inbound wamid per chat: Meta's typing/read-receipt API needs a
  179. # message_id to attach to, and the base send_typing contract has none.
  180. self._last_inbound_wamid_by_chat: OrderedDict[str, str] = OrderedDict()
  181. # Interactive-button state: short id (in the button payload) → session_key for
  182. # the gateway resolver. Popped on tap; FIFO-capped via bounded_put so ignored
  183. # prompts don't accumulate (an evicted tap degrades to text fallback).
  184. self._clarify_state: OrderedDict[str, str] = OrderedDict()
  185. self._exec_approval_state: OrderedDict[str, str] = OrderedDict()
  186. self._slash_confirm_state: OrderedDict[str, str] = OrderedDict()
  187. self._runner = self._http_client = None
  188. # ------------------------------------------------------------------ helpers
  189. @staticmethod
  190. def _normalize_path(path: Any) -> str:
  191. raw = str(path or "").strip() or "/"
  192. return raw if raw.startswith("/") else f"/{raw}"
  193. def _graph_url(self, path: str) -> str:
  194. """Build a Graph API URL for this adapter's phone-number scope."""
  195. return f"{GRAPH_API_BASE}/{self._api_version}/{self._phone_number_id}/{path.removeprefix('/')}"
  196. def _auth_headers(self, *, json_body: bool = True) -> dict[str, str]:
  197. headers = {"Authorization": f"Bearer {self._access_token}"}
  198. return {**headers, "Content-Type": "application/json"} if json_body else headers
  199. def _effective_reply_prefix(self) -> str:
  200. """Cloud API has no self-chat concept (a Baileys-only setting) — no default prefix."""
  201. return self._reply_prefix.replace("\\n", "\n") if self._reply_prefix is not None else ""
  202. @staticmethod
  203. def _normalize_allow_ids(ids: set[str]) -> set[str]:
  204. """Normalize allowlist entries to bare wa_id (digits): strip ``@...`` JID suffixes and non-digits."""
  205. return {re.sub(r"\D", "", entry.split("@", 1)[0]) or entry for entry in ids}
  206. def _entry_matches(self, entries, target: str) -> bool:
  207. """Bare-wa_id membership first (Cloud senders are digits), then the shared WhatsApp matcher
  208. so ``*`` and phone/LID aliases keep working for DM intake and groups as they always did."""
  209. entries = set(entries or ())
  210. bare = re.sub(r"\D", "", str(target).split("@", 1)[0]) or target
  211. return bare in self._normalize_allow_ids(entries) or super()._entry_matches(entries, target)
  212. def _webhook_identity_matches(self, entry_id: Any, metadata: Any) -> bool:
  213. """Bind a signed callback to this adapter's configured Meta identities."""
  214. metadata = metadata if isinstance(metadata, dict) else {}
  215. incoming_phone_number_id = str(metadata.get("phone_number_id") or "").strip()
  216. incoming_waba_id = str(entry_id or "").strip()
  217. return (
  218. incoming_phone_number_id == self._phone_number_id
  219. and (not self._waba_id or incoming_waba_id == self._waba_id)
  220. )
  221. def _allow_all_env_names(self) -> tuple[str, ...]:
  222. """Also honor the documented WHATSAPP_CLOUD_ALLOW_ALL_USERS opt-in."""
  223. return (*super()._allow_all_env_names(), "WHATSAPP_CLOUD_ALLOW_ALL_USERS")
  224. # ------------------------------------------------------------------ lifecycle
  225. async def connect(self, *, is_reconnect: bool = False) -> bool:
  226. for ok, code, message in (
  227. (check_whatsapp_cloud_requirements(), "whatsapp_cloud_deps_missing",
  228. "aiohttp and httpx are required for whatsapp_cloud — reinstall hermes-agent."),
  229. (self._phone_number_id and self._access_token, "whatsapp_cloud_unconfigured",
  230. "WHATSAPP_CLOUD_PHONE_NUMBER_ID and WHATSAPP_CLOUD_ACCESS_TOKEN are required."),
  231. ):
  232. if not ok:
  233. self._set_fatal_error(code, message, retryable=False)
  234. return False
  235. # Tighter keepalive so idle CLOSE_WAIT drains promptly.
  236. # Outbound HTTP client. See #18451.
  237. from gateway.platforms._http_client_limits import platform_httpx_limits
  238. self._http_client = httpx.AsyncClient(timeout=30.0, limits=platform_httpx_limits())
  239. # client_max_size backstops the bounded reader in _handle_webhook.
  240. # Inbound webhook server. client_max_size backstops the bounded reader in _handle_webhook — aiohttp
  241. # enforces the cap on request.read()/post() paths too (#58536/#58902/#59180 pattern).
  242. app = web.Application(client_max_size=WEBHOOK_MAX_BODY_BYTES)
  243. app.router.add_get(self._health_path, self._handle_health)
  244. app.router.add_get(self._webhook_path, self._handle_verify)
  245. app.router.add_post(self._webhook_path, self._handle_webhook)
  246. # Shared-listener mode (multiplex secondary): no bind; served at /p/<profile>/<webhook_path>.
  247. from gateway.platforms.shared_ingress import bind_listener
  248. self._runner = await bind_listener(self, app, self._webhook_host, self._webhook_port, self._webhook_path)
  249. self._mark_connected()
  250. if self._runner is not None:
  251. logger.info(
  252. "[whatsapp_cloud] Listening on %s:%d%s (Graph %s, phone_id=%s)",
  253. self._webhook_host, self._webhook_port, self._webhook_path, self._api_version, self._phone_number_id,
  254. )
  255. if not self._verify_token:
  256. logger.warning("[whatsapp_cloud] WHATSAPP_CLOUD_VERIFY_TOKEN is not set — the GET subscription handshake will fail until it is.")
  257. if not self._app_secret:
  258. logger.warning(
  259. "[whatsapp_cloud] WHATSAPP_CLOUD_APP_SECRET is not set — incoming webhook POSTs will be refused "
  260. "with 503. Set the app secret to enable inbound message delivery."
  261. )
  262. self._wire_plugin_handlers(None)
  263. return True
  264. async def disconnect(self) -> None:
  265. for attr, close, what in (("_runner", "cleanup", "webhook server cleanup"), ("_http_client", "aclose", "http client close")):
  266. obj = getattr(self, attr)
  267. if obj is None:
  268. continue
  269. try:
  270. await getattr(obj, close)()
  271. except Exception:
  272. logger.exception("[whatsapp_cloud] %s failed", what)
  273. setattr(self, attr, None)
  274. self._mark_disconnected()
  275. # ------------------------------------------------------------------ outbound
  276. @staticmethod
  277. def _response_error(resp: Any) -> str:
  278. """Map a non-200 Graph response to an actionable error string."""
  279. try:
  280. body = resp.json()
  281. except Exception:
  282. body = {"raw": resp.text[:500]}
  283. # Graph shape: {"error": {"message", "type", "code", "fbtrace_id"}}
  284. err = (body or {}).get("error") or {}
  285. message = err.get("message") or body.get("raw") or "unknown error"
  286. code = err.get("code")
  287. return f"graph error {code} (HTTP {resp.status_code}): {message}" if code is not None else f"HTTP {resp.status_code}: {message}"
  288. async def _post_messages(self, payload: dict[str, Any], *, fail_log: str, reject_log: str, reject_args: tuple = ()) -> tuple[list, Optional[str]]:
  289. """POST one /messages payload. Returns ``(response messages[], None)`` or ``([], error)``."""
  290. try:
  291. resp = await self._http_client.post(self._graph_url("messages"), headers=self._auth_headers(), json=payload)
  292. except Exception as exc:
  293. logger.exception(fail_log)
  294. return [], str(exc) or type(exc).__name__
  295. if resp.status_code != 200:
  296. error_msg = self._response_error(resp)
  297. logger.warning(reject_log, resp.status_code, *reject_args, error_msg)
  298. return [], error_msg
  299. try:
  300. return resp.json().get("messages") or [], None
  301. except Exception:
  302. return [], None
  303. async def _post_message_result(self, payload: dict[str, Any], **log_kwargs) -> SendResult:
  304. """``_post_messages`` → SendResult with the first returned message id; guards disconnected state."""
  305. if self._http_client is None:
  306. return SendResult(success=False, error="Not connected")
  307. ids, err = await self._post_messages(payload, **log_kwargs)
  308. return SendResult(success=False, error=err) if err is not None else SendResult(success=True, message_id=ids[0].get("id") if ids else None)
  309. @staticmethod
  310. def _outbound_payload(chat_id: str, kind: str, block: Any, reply_to: Optional[str]) -> dict[str, Any]:
  311. """Common ``/messages`` envelope; ``context`` quotes ``reply_to`` when given."""
  312. payload: dict[str, Any] = {"messaging_product": "whatsapp", "recipient_type": "individual", "to": chat_id, "type": kind, kind: block}
  313. if reply_to:
  314. payload["context"] = {"message_id": reply_to}
  315. return payload
  316. async def send(self, chat_id: str, content: str, reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None) -> SendResult:
  317. """Send a text message via Graph API. ``chat_id`` is the recipient's ``wa_id``."""
  318. if self._http_client is None:
  319. return SendResult(success=False, error="Not connected")
  320. if not content or not content.strip():
  321. return SendResult(success=True, message_id=None)
  322. formatted = self.format_message(content)
  323. last_message_id: Optional[str] = None
  324. for idx, chunk in enumerate(self.truncate_message(formatted, self._outgoing_chunk_limit())):
  325. # Quote the user's message on the first chunk only.
  326. payload = self._outbound_payload(
  327. chat_id, "text", {"body": chunk, "preview_url": True}, reply_to if idx == 0 else None
  328. )
  329. ids, err = await self._post_messages(
  330. payload,
  331. fail_log="[whatsapp_cloud] send failed",
  332. reject_log="[whatsapp_cloud] send rejected (status=%d): %s",
  333. )
  334. if err is not None:
  335. return SendResult(success=False, error=err)
  336. last_message_id = ids[0].get("id") if ids else last_message_id
  337. # Index (chat_id, wamid) → text: Meta's inbound ``context`` carries only the
  338. # quoted message's id, so this is how replies to our messages resolve text.
  339. if last_message_id:
  340. await rich_sent_store.record_async(chat_id, last_message_id, formatted)
  341. return SendResult(success=True, message_id=last_message_id)
  342. # ------------------------------------------------------------------ typing indicator + read receipts
  343. async def send_typing(self, chat_id: str, metadata=None) -> None:
  344. """Mark the latest inbound message read AND show a typing indicator. Meta couples
  345. both into one POST; the indicator auto-dismisses on reply or after 25s. Best-effort:
  346. every error is swallowed so the main reply path is never blocked."""
  347. wamid = self._last_inbound_wamid_by_chat.get(chat_id)
  348. if self._http_client is None or not wamid:
  349. return # not connected, or no inbound yet for this chat (cache cleared on restart)
  350. payload = {"messaging_product": "whatsapp", "status": "read", "message_id": wamid, "typing_indicator": {"type": "text"}}
  351. try:
  352. resp = await self._http_client.post(self._graph_url("messages"), headers=self._auth_headers(), json=payload)
  353. except Exception:
  354. return
  355. if resp.status_code == 200:
  356. return
  357. try:
  358. code = ((resp.json() or {}).get("error") or {}).get("code")
  359. except Exception:
  360. code = None
  361. # 131009 = "Parameter value is not valid" (typically wamid > 30 days old) — common
  362. # after a long-quiet conversation, so log at info.
  363. if code == 131009:
  364. logger.info("[whatsapp_cloud] typing/read indicator rejected: wamid %s likely older than 30 days", wamid)
  365. else:
  366. logger.debug("[whatsapp_cloud] typing/read indicator returned %d (%s)", resp.status_code, code)
  367. # ------------------------------------------------------------------ interactive messages
  368. async def _send_interactive(
  369. self, chat_id: str, interactive: dict[str, Any], metadata: Optional[dict[str, Any]],
  370. state: OrderedDict[str, str], state_id: str, session_key: str,
  371. ) -> SendResult:
  372. """POST an ``interactive`` message (caller supplies ``type``/``body``/``action``) and, on
  373. success, remember ``state_id → session_key`` for the tap. Free-form interactives need no
  374. Meta approval but are only valid inside the 24h window — fine, all senders here reply to a user."""
  375. result = await self._post_message_result(
  376. self._outbound_payload(chat_id, "interactive", interactive, _reply_to_from(metadata)),
  377. fail_log="[whatsapp_cloud] interactive send failed",
  378. reject_log="[whatsapp_cloud] interactive rejected (status=%d): %s",
  379. )
  380. if result.success:
  381. bounded_put(state, state_id, session_key, INTERACTIVE_STATE_CACHE_SIZE)
  382. return result
  383. @staticmethod
  384. def _truncate_button_label(text: str, limit: int = 20) -> str:
  385. """Button titles cap at 20 chars, list-row titles at 24; the ellipsis counts."""
  386. text = str(text or "").strip()
  387. return text if len(text) <= limit else text[: max(1, limit - 1)] + "…"
  388. @staticmethod
  389. def _truncate_body(text: str, limit: int = 1024) -> str:
  390. """``interactive.body.text`` caps at 1024 chars."""
  391. text = str(text or "")
  392. return text if len(text) <= limit else text[: limit - 3] + "..."
  393. @staticmethod
  394. def _reply_buttons(*buttons: tuple[str, str]) -> list[dict[str, Any]]:
  395. return [{"type": "reply", "reply": {"id": bid, "title": title}} for bid, title in buttons]
  396. @classmethod
  397. def _button_interactive(cls, body_text: str, *buttons: tuple[str, str]) -> dict[str, Any]:
  398. """``interactive.type=button`` body: ≤3 quick-reply buttons (id ≤256 chars, title ≤20)."""
  399. return {"type": "button", "body": {"text": body_text}, "action": {"buttons": cls._reply_buttons(*buttons)}}
  400. async def send_clarify(
  401. self, chat_id: str, question: str, choices: Optional[list], clarify_id: str,
  402. session_key: str, metadata: Optional[dict[str, Any]] = None,
  403. ) -> SendResult:
  404. """Clarify as native buttons: 1–3 choices → buttons, 4+ → list (+ "Other" row that flips
  405. the entry into text-capture mode), 0 → plain text question. Button ``id`` carries
  406. ``cl:<clarify_id>:<idx|other>``; inbound dispatches on it."""
  407. question = (question or "").strip()
  408. if not choices:
  409. return await self.send(chat_id, f"❓ {question}", reply_to=_reply_to_from(metadata))
  410. # Full choice text goes in the body so long options aren't lost to the
  411. # 20-char label cap; labels are just the option number.
  412. choices_list = [str(c).strip() for c in choices[:10] if str(c).strip()]
  413. body_text = self._truncate_body(f"❓ {question}\n\n" + "\n".join(f"{i + 1}. {c}" for i, c in enumerate(choices_list)))
  414. if len(choices_list) <= 3:
  415. interactive = self._button_interactive(
  416. body_text, *((f"cl:{clarify_id}:{idx}", self._truncate_button_label(str(idx + 1))) for idx in range(len(choices_list)))
  417. )
  418. else:
  419. # List rows: id + title (≤24) + description (≤72) with the choice text.
  420. rows = [
  421. {"id": f"cl:{clarify_id}:{idx}", "title": self._truncate_button_label(f"{idx + 1}", limit=24),
  422. "description": self._truncate_button_label(choice_text, limit=72)}
  423. for idx, choice_text in enumerate(choices_list)
  424. ]
  425. rows.append({
  426. "id": f"cl:{clarify_id}:other",
  427. "title": self._truncate_button_label(t("platform.whatsapp.clarify_other_title"), limit=24),
  428. "description": self._truncate_button_label(t("platform.whatsapp.clarify_other_description"), limit=72),
  429. })
  430. interactive = {
  431. "type": "list", "body": {"text": body_text},
  432. "action": {"button": self._truncate_button_label(t("platform.whatsapp.clarify_list_button")),
  433. "sections": [{"title": t("platform.whatsapp.clarify_list_section"), "rows": rows}]},
  434. }
  435. return await self._send_interactive(chat_id, interactive, metadata, self._clarify_state, clarify_id, session_key)
  436. @property
  437. def _EA_HEADER(self) -> str:
  438. return f"⚠️ *{ea_header_text()}*\n\n"
  439. _EA_CODE_CLOSE = "\n```\n\n"
  440. _EA_CMD_BUDGET = 800 # body caps at 1024; leave room for the framing prose
  441. def _approval_request_ids(self) -> OrderedDict[str, str]:
  442. """approval_id → ``tools.approval`` request id; created on first use, like Telegram's
  443. ``_approval_counter``, so adapters assembled without ``__init__`` still resolve."""
  444. return self.__dict__.setdefault("_exec_approval_request_ids", OrderedDict())
  445. async def _send_exec_approval_prompt(self, prompt: ExecApprovalPrompt) -> SendResult:
  446. """Approve / Deny buttons only (a 3-button cap leaves no room for the session/always
  447. tiers); a tap resolves via ``tools.approval.resolve_gateway_approval``."""
  448. approval_id = uuid.uuid4().hex[:12]
  449. interactive = self._button_interactive(
  450. self._truncate_body(prompt.text),
  451. (f"appr:{approval_id}:approve", self._truncate_button_label(t("platform.whatsapp.approve_button"))),
  452. (f"appr:{approval_id}:deny", self._truncate_button_label(t("platform.whatsapp.deny_button"))))
  453. result = await self._send_interactive(
  454. prompt.chat_id, interactive, prompt.metadata, self._exec_approval_state, approval_id, prompt.session_key)
  455. if result.success and prompt.request_id:
  456. bounded_put(self._approval_request_ids(), approval_id, prompt.request_id, INTERACTIVE_STATE_CACHE_SIZE)
  457. return result
  458. async def send_slash_confirm(
  459. self, chat_id: str, title: str, message: str, session_key: str, confirm_id: str, metadata: Optional[dict[str, Any]] = None,
  460. ) -> SendResult:
  461. """Approve Once / Always / Cancel buttons; ``confirm_id`` is caller-supplied."""
  462. interactive = self._button_interactive(
  463. self._truncate_body(f"*{title}*\n\n{message}"),
  464. (f"sc:once:{confirm_id}", self._truncate_button_label(t("platform.whatsapp.slash_confirm_once"))),
  465. (f"sc:always:{confirm_id}", self._truncate_button_label(t("platform.whatsapp.slash_confirm_always"))),
  466. (f"sc:cancel:{confirm_id}", self._truncate_button_label(t("platform.whatsapp.slash_confirm_cancel"))),
  467. )
  468. return await self._send_interactive(chat_id, interactive, metadata, self._slash_confirm_state, confirm_id, session_key)
  469. async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
  470. # No chat-info endpoint; profile name arrives via webhook contacts[].
  471. return {"name": chat_id, "type": "dm"}
  472. # ------------------------------------------------------------------ outbound media
  473. async def _upload_media(self, file_path: str, media_kind: str, mime_type: Optional[str] = None) -> tuple[Optional[str], Optional[str]]:
  474. """Upload a local file to Graph /media. Returns ``(media_id, None)`` or ``(None, error)``."""
  475. if self._http_client is None:
  476. return None, "Not connected"
  477. if not os.path.exists(file_path):
  478. return None, f"File not found: {file_path}"
  479. size, cap = os.path.getsize(file_path), _MEDIA_SIZE_LIMITS.get(media_kind, _MEDIA_SIZE_LIMITS["document"])
  480. if size > cap:
  481. return None, f"File {os.path.basename(file_path)} is {size} bytes; Cloud API {media_kind} cap is {cap} bytes"
  482. mime_type = mime_type or mimetypes.guess_type(file_path)[0] or _DEFAULT_MIME.get(media_kind, "application/octet-stream")
  483. try:
  484. with open(file_path, "rb") as fh: # noqa: ASYNC230 -- file handle is streamed to the upload; a local open() is non-blocking in practice
  485. files = {"file": (os.path.basename(file_path), fh, mime_type), "messaging_product": (None, "whatsapp"), "type": (None, mime_type)}
  486. resp = await self._http_client.post(self._graph_url("media"), headers=self._auth_headers(json_body=False), files=files)
  487. except Exception as exc:
  488. logger.exception("[whatsapp_cloud] media upload failed")
  489. return None, str(exc)
  490. if resp.status_code != 200:
  491. return None, self._response_error(resp)
  492. try:
  493. media_id = resp.json().get("id")
  494. except Exception:
  495. media_id = None
  496. return (media_id, None) if media_id else (None, "Upload response missing 'id'")
  497. async def _send_media(
  498. self, chat_id: str, media_kind: str, *, media_id: Optional[str] = None,
  499. media_link: Optional[str] = None, caption: Optional[str] = None,
  500. filename: Optional[str] = None, reply_to: Optional[str] = None,
  501. ) -> SendResult:
  502. """POST a media message referencing exactly one of an uploaded ``media_id`` or a public
  503. ``link``. Caption is accepted on image/video/document; filename on document only."""
  504. if self._http_client is None:
  505. return SendResult(success=False, error="Not connected")
  506. if bool(media_id) == bool(media_link):
  507. return SendResult(success=False, error="Exactly one of media_id or media_link must be set")
  508. media_block: dict[str, Any] = {"id": media_id} if media_id else {"link": media_link}
  509. if caption and media_kind in {"image", "video", "document"}:
  510. media_block["caption"] = caption
  511. if filename and media_kind == "document":
  512. media_block["filename"] = filename
  513. return await self._post_message_result(
  514. self._outbound_payload(chat_id, media_kind, media_block, reply_to),
  515. fail_log="[whatsapp_cloud] media send failed",
  516. reject_log="[whatsapp_cloud] media send rejected (status=%d, kind=%s): %s",
  517. reject_args=(media_kind,),
  518. )
  519. async def _send_media_from_path_or_link(
  520. self, chat_id: str, source: str, media_kind: str, *, caption: Optional[str] = None,
  521. filename: Optional[str] = None, reply_to: Optional[str] = None,
  522. mime_type: Optional[str] = None,
  523. ) -> SendResult:
  524. """HTTPS URL → ``link`` send (one fewer round trip); local path → upload + ``id`` send.
  525. Local sends are indexed in ``rich_sent_store`` so a later quote of the attachment can be
  526. resolved (Meta's inbound ``context`` carries only the quoted id)."""
  527. ref: dict[str, Optional[str]] = {"media_link": source}
  528. if not source.startswith(_HTTP_PREFIXES):
  529. media_id, err = await self._upload_media(source, media_kind, mime_type)
  530. if err:
  531. return SendResult(success=False, error=err)
  532. ref = {"media_id": media_id}
  533. result = await self._send_media(chat_id, media_kind, caption=caption, filename=filename, reply_to=reply_to, **ref)
  534. if result.success and result.message_id and "media_id" in ref:
  535. mime = mime_type or mimetypes.guess_type(source)[0] or _DEFAULT_MIME.get(media_kind, "application/octet-stream")
  536. await rich_sent_store.record_media_async(chat_id, result.message_id, [(source, mime)])
  537. if caption:
  538. await rich_sent_store.record_async(chat_id, result.message_id, caption)
  539. return result
  540. # ``**kwargs`` absorbs base-class args (e.g. ``metadata``) the Cloud API has no use for.
  541. async def send_image(self, chat_id: str, image_url: str, caption: Optional[str] = None, reply_to: Optional[str] = None, **kwargs) -> SendResult:
  542. return await self._send_media_from_path_or_link(chat_id, image_url, "image", caption=caption, reply_to=reply_to)
  543. async def send_image_file(self, chat_id: str, image_path: str, caption: Optional[str] = None, reply_to: Optional[str] = None, **kwargs) -> SendResult:
  544. return await self._send_media_from_path_or_link(chat_id, image_path, "image", caption=caption, reply_to=reply_to)
  545. async def send_video(self, chat_id: str, video_path: str, caption: Optional[str] = None, reply_to: Optional[str] = None, **kwargs) -> SendResult:
  546. return await self._send_media_from_path_or_link(chat_id, video_path, "video", caption=caption, reply_to=reply_to)
  547. async def send_document(
  548. self, chat_id: str, file_path: str, caption: Optional[str] = None, file_name: Optional[str] = None, reply_to: Optional[str] = None, **kwargs,
  549. ) -> SendResult:
  550. return await self._send_media_from_path_or_link(
  551. chat_id, file_path, "document", caption=caption, filename=file_name or os.path.basename(file_path), reply_to=reply_to,
  552. )
  553. async def send_voice(self, chat_id: str, audio_path: str, caption: Optional[str] = None, reply_to: Optional[str] = None,
  554. is_voice: Optional[bool] = None, **kwargs) -> SendResult:
  555. """Voice message: ``audio/ogg; codecs=opus`` renders as a voice bubble, so a
  556. local MP3 (Hermes TTS output) is converted via ffmpeg first; other audio is sent as-is.
  557. A plain audio MEDIA file (``is_voice=False``) is never converted into a voice bubble."""
  558. mime_type: Optional[str] = None
  559. if is_voice is False and audio_path.lower().endswith(".mp3"):
  560. mime_type = "audio/mpeg"
  561. elif (not audio_path.startswith(_HTTP_PREFIXES) and audio_path.lower().endswith(".mp3")
  562. and await asyncio.to_thread(os.path.exists, audio_path)):
  563. opus_path = await self._convert_to_opus(audio_path)
  564. if opus_path:
  565. try:
  566. return await self._send_media_from_path_or_link(
  567. chat_id, opus_path, "audio", caption=caption, reply_to=reply_to, mime_type="audio/ogg; codecs=opus",
  568. )
  569. finally:
  570. with contextlib.suppress(OSError): # the .ogg is a transient artifact next to the source MP3
  571. os.unlink(opus_path)
  572. # No ffmpeg (warn-once logged in _convert_to_opus) → MP3 attachment.
  573. mime_type = "audio/mpeg"
  574. return await self._send_media_from_path_or_link(chat_id, audio_path, "audio", caption=caption, reply_to=reply_to, mime_type=mime_type)
  575. async def _convert_to_opus(self, mp3_path: str) -> Optional[str]:
  576. """MP3 → ``audio/ogg; codecs=opus`` sibling file; None if ffmpeg is missing or fails. The
  577. missing-ffmpeg warning fires once per adapter: it is an install hint, not a per-message error."""
  578. if not _FFMPEG_PATH:
  579. if not self._warned_no_ffmpeg:
  580. self._warned_no_ffmpeg = True
  581. logger.warning(
  582. "[whatsapp_cloud] ffmpeg not found on PATH — voice messages will be delivered as MP3 audio "
  583. "attachments instead of native voice notes (green waveform bubble). Install ffmpeg to enable: "
  584. "Windows `winget install Gyan.FFmpeg`, macOS `brew install ffmpeg`, Linux package manager."
  585. )
  586. return None
  587. return await asyncio.to_thread(transcode_to_ogg_opus, mp3_path, output_path=mp3_path.rsplit(".", 1)[0] + ".ogg")
  588. # ------------------------------------------------------------------ inbound media
  589. async def _graph_get(self, url: str, headers: dict[str, str], what: str, media_id: str) -> Any:
  590. """GET with the download path's uniform failure logging; None on exception or non-200."""
  591. try:
  592. resp = await self._http_client.get(url, headers=headers)
  593. except Exception:
  594. logger.exception("[whatsapp_cloud] media %s fetch raised (id=%s)", what, media_id)
  595. return None
  596. if resp.status_code != 200:
  597. logger.warning("[whatsapp_cloud] media %s fetch failed (id=%s, status=%d)", what, media_id, resp.status_code)
  598. return None
  599. return resp
  600. async def _download_media_to_cache(self, media_id: str, *, ext_hint: Optional[str] = None) -> tuple[Optional[str], Optional[str]]:
  601. """Two-step Graph download: ``GET /<id>`` → signed temp URL (~5 min) → bytes.
  602. Returns ``(local_path, mime_type)`` or ``(None, None)`` on any failure (logged)."""
  603. if self._http_client is None:
  604. return None, None
  605. # media_id is interpolated into a Graph URL and a cache filename — refuse
  606. # anything that isn't a plain Meta-style id so a hostile payload can't traverse.
  607. media_id = str(media_id).strip()
  608. if not re.fullmatch(r"[A-Za-z0-9._-]+", media_id):
  609. logger.warning("[whatsapp_cloud] refusing malformed media id %r", media_id[:64])
  610. return None, None
  611. headers = self._auth_headers(json_body=False)
  612. meta_resp = await self._graph_get(f"{GRAPH_API_BASE}/{self._api_version}/{media_id}", headers, "metadata", media_id)
  613. if meta_resp is None:
  614. return None, None
  615. try:
  616. meta = meta_resp.json()
  617. except Exception:
  618. meta = {}
  619. temp_url, mime = meta.get("url"), meta.get("mime_type") or ""
  620. if not temp_url:
  621. return None, None
  622. # Auth is required even though the URL is signed (Meta documents this).
  623. blob_resp = await self._graph_get(temp_url, headers, "bytes", media_id)
  624. if blob_resp is None:
  625. return None, None
  626. _INBOUND_MEDIA_CACHE.mkdir(parents=True, exist_ok=True)
  627. out_path = _INBOUND_MEDIA_CACHE / f"{media_id}{ext_hint or _ext_for_mime(mime) or '.bin'}"
  628. try:
  629. out_path.write_bytes(blob_resp.content)
  630. except OSError:
  631. logger.exception("[whatsapp_cloud] failed to write cached media (id=%s)", media_id)
  632. return None, None
  633. return str(out_path), mime or None
  634. # ------------------------------------------------------------------ inbound
  635. async def _handle_health(self, request: web.Request) -> web.Response:
  636. return web.json_response({
  637. "status": "ok", "platform": self.platform.value, "phone_number_id": self._phone_number_id,
  638. "webhook_path": self._webhook_path, "verify_token_configured": bool(self._verify_token),
  639. "app_secret_configured": bool(self._app_secret), "ffmpeg_present": _FFMPEG_PATH is not None,
  640. "accepted": self._accepted_count, "duplicates": self._duplicate_count,
  641. "rejected_signature": self._rejected_signature_count,
  642. })
  643. async def _handle_verify(self, request: web.Request) -> web.Response:
  644. """Meta subscription handshake: echo ``hub.challenge`` iff mode is
  645. ``subscribe`` and ``hub.verify_token`` matches (constant-time)."""
  646. if not self._verify_token:
  647. # Refuse rather than accept any token, which would let an attacker subscribe.
  648. return web.Response(status=503, text="verify_token not configured")
  649. q = request.query
  650. if q.get("hub.mode", "") != "subscribe":
  651. return web.Response(status=400, text="bad mode")
  652. # Compare as bytes: compare_digest raises TypeError on non-ASCII str.
  653. if not hmac.compare_digest(q.get("hub.verify_token", "").encode(), self._verify_token.encode()):
  654. return web.Response(status=403, text="verify_token mismatch")
  655. if not q.get("hub.challenge", ""):
  656. return web.Response(status=400, text="missing challenge")
  657. return web.Response(text=q["hub.challenge"], content_type="text/plain")
  658. async def _handle_webhook(self, request: web.Request) -> web.Response:
  659. """Inbound webhook POST: raw bytes → HMAC verify → JSON → dispatch. Signature is over
  660. the raw body, so JSON parsing must come after verification. Always 200 once a valid
  661. request is ack'd — Meta retries non-200 for up to 7 days and would multiply agent work."""
  662. # Read one byte past Meta's 3MB max so oversized chunked bodies are rejected before buffering.
  663. try:
  664. raw = await _read_limited_request_body(request, WEBHOOK_MAX_BODY_BYTES)
  665. except ValueError:
  666. return web.Response(status=413)
  667. except Exception:
  668. return web.Response(status=400)
  669. # Without app_secret the sender can't be authenticated → refuse (same
  670. # posture as the GET handshake refusing without verify_token).
  671. if not self._app_secret:
  672. logger.error("[whatsapp_cloud] webhook POST refused: app_secret unset. Set WHATSAPP_CLOUD_APP_SECRET to enable inbound delivery.")
  673. return web.Response(status=503, text="app_secret not configured")
  674. signature_header = request.headers.get("X-Hub-Signature-256", "")
  675. if not self._verify_signature(raw, signature_header):
  676. self._rejected_signature_count += 1
  677. logger.warning("[whatsapp_cloud] rejected webhook: invalid X-Hub-Signature-256 (header=%r, body_len=%d)", signature_header, len(raw))
  678. return web.Response(status=401)
  679. try:
  680. payload = json.loads(raw)
  681. except Exception:
  682. logger.warning("[whatsapp_cloud] webhook body is not valid JSON")
  683. payload = None
  684. if not isinstance(payload, dict):
  685. return web.Response(status=400)
  686. await self._dispatch_payload(payload)
  687. return web.Response(status=200)
  688. def _verify_signature(self, raw_body: bytes, header: str) -> bool:
  689. """Verify ``sha256=<hex>`` HMAC of the raw body keyed by ``app_secret`` (constant-time)."""
  690. if not (self._app_secret and header and header.startswith("sha256=") and (expected_hex := header[7:].strip())):
  691. return False
  692. computed = hmac.new(self._app_secret.encode("utf-8"), raw_body, hashlib.sha256).hexdigest()
  693. # Compare as bytes: compare_digest raises TypeError on non-ASCII str.
  694. return hmac.compare_digest(computed.lower().encode(), expected_hex.lower().encode())
  695. # ------------------------------------------------------------------ dispatch
  696. def _dedup_wamid(self, wamid: str) -> bool:
  697. """True if this wamid is new; False (and count a duplicate) if already seen."""
  698. if wamid in self._seen_wamids:
  699. self._duplicate_count += 1
  700. return False
  701. if wamid: # can't dedup without an id — let it through
  702. bounded_put(self._seen_wamids, wamid, True, WAMID_DEDUP_CACHE_SIZE)
  703. return True
  704. async def _dispatch_payload(self, payload: dict[str, Any]) -> None:
  705. """Walk ``entry[].changes[].value.{messages, contacts, statuses}`` and dispatch each message.
  706. ``statuses`` (sent/delivered/read/failed) are only logged — the agent doesn't consume receipts."""
  707. if payload.get("object") != "whatsapp_business_account":
  708. logger.debug("[whatsapp_cloud] ignoring non-WABA payload (object=%r)", payload.get("object"))
  709. return
  710. for entry in payload.get("entry") or []:
  711. for change in (entry.get("changes") or []) if isinstance(entry, dict) else []:
  712. if not isinstance(change, dict) or change.get("field") != "messages":
  713. continue # account_alerts, template_status_update, … — not message ingress
  714. value = change.get("value") or {}
  715. if not isinstance(value, dict):
  716. continue
  717. metadata = value.get("metadata") or {}
  718. if not self._webhook_identity_matches(entry.get("id"), metadata):
  719. # A shared Meta app delivers sibling numbers' status receipts here too;
  720. # only a foreign *message* is worth an operator-visible warning.
  721. logger.log(
  722. logging.WARNING if value.get("messages") else logging.DEBUG,
  723. "[whatsapp_cloud] ignoring signed webhook for waba=%r phone_number_id=%r "
  724. "(configured waba=%s phone_number_id=%r)",
  725. entry.get("id"),
  726. metadata.get("phone_number_id") if isinstance(metadata, dict) else None,
  727. self._waba_id or "<any>",
  728. self._phone_number_id,
  729. )
  730. continue
  731. contacts_by_waid = {
  732. wa_id: str((contact.get("profile") or {}).get("name") or "").strip()
  733. for contact in value.get("contacts") or []
  734. if isinstance(contact, dict) and (wa_id := str(contact.get("wa_id") or "").strip())
  735. }
  736. for raw_message in value.get("messages") or []:
  737. if isinstance(raw_message, dict):
  738. await self._ingest_message(raw_message, contacts_by_waid, metadata)
  739. for status in value.get("statuses") or []:
  740. if isinstance(status, dict):
  741. logger.debug("[whatsapp_cloud] status %s for %s", status.get("status"), status.get("id"))
  742. async def _ingest_message(self, raw_message: dict[str, Any], contacts_by_waid: dict[str, str], metadata: dict[str, Any]) -> None:
  743. """Dedup → build event → handle_message. Neither build nor dispatch errors may
  744. bubble out: the wamid is already dedup-marked, so a 500 would make Meta retry
  745. the batch and every message in it would then be dropped as a duplicate."""
  746. wamid = str(raw_message.get("id") or "").strip()
  747. if not self._dedup_wamid(wamid):
  748. logger.debug("[whatsapp_cloud] duplicate wamid %s, skipping", wamid)
  749. return
  750. try:
  751. event = await self._build_message_event_from_cloud(raw_message, contacts_by_waid, metadata)
  752. except Exception:
  753. logger.exception("[whatsapp_cloud] failed to build event for wamid %s", wamid)
  754. return
  755. if event is None:
  756. return
  757. self._accepted_count += 1
  758. try:
  759. await self.handle_message(event)
  760. except Exception:
  761. logger.exception("[whatsapp_cloud] handle_message raised for wamid %s", wamid)
  762. async def _dispatch_interactive_reply(self, raw_message: dict[str, Any], contacts_by_waid: dict[str, str]) -> bool:
  763. """Route an inbound button tap to its resolver (see ``_INTERACTIVE_HANDLERS``). True = claimed.
  764. False (unknown prefix, no live state, or no waiter) makes the caller fall back to text
  765. dispatch with the button title — covers stale taps."""
  766. inner = _interactive_inner(raw_message)
  767. button_id = str(inner.get("id") or "").strip()
  768. sender_id = str(raw_message.get("from") or "").strip()
  769. if not button_id:
  770. return False
  771. # Taps bypass ``_should_process_message``; re-check the strict DM gate so a stale
  772. # prompt can't be answered after the sender leaves the allowlist.
  773. if not (sender_id and self._is_dm_allowed(sender_id)):
  774. logger.warning("[whatsapp_cloud] Rejected unauthorized interactive tap from %s (button_id=%r)", sender_id or "<unknown>", button_id)
  775. return True # claim so the tap isn't re-dispatched as plain text
  776. parts = button_id.split(":", 2)
  777. handler = next((h for prefix, h in self._INTERACTIVE_HANDLERS.items() if button_id.startswith(prefix)), None)
  778. # Unknown prefix (maybe a plugin-defined adapter's) — text dispatch is the safe default.
  779. if handler is None or len(parts) != 3:
  780. return False
  781. return await handler(self, str(raw_message.get("from") or ""), inner, parts)
  782. async def _reply_best_effort(self, to: str, text: str, fail_log: str) -> None:
  783. try:
  784. await self.send(to, text)
  785. except Exception:
  786. logger.exception(fail_log)
  787. @staticmethod
  788. def _pop_tap_state(
  789. state: OrderedDict[str, str], key: str, stale_log: str, choice: str = "", valid: tuple = (),
  790. ) -> Optional[str]:
  791. """Pop the session_key for a tapped prompt. None (info-logged) when nothing is live — likely
  792. a stale tap; an unrecognised ``choice`` keeps the prompt live and also yields None."""
  793. session_key = state.pop(key, None)
  794. if not session_key:
  795. logger.info(stale_log, key)
  796. elif valid and choice not in valid:
  797. state[key] = session_key
  798. return None
  799. return session_key
  800. async def _handle_clarify_tap(self, to: str, inner: dict[str, Any], parts: list) -> bool:
  801. _, clarify_id, choice = parts
  802. session_key = self._pop_tap_state(
  803. self._clarify_state, clarify_id,
  804. "[whatsapp_cloud] clarify tap with no matching state (clarify_id=%s) — likely stale; falling back to text",
  805. )
  806. if not session_key:
  807. return False
  808. clarify_gateway = _optional_module(
  809. "tools.clarify_gateway", "[whatsapp_cloud] clarify resolver unavailable; falling back to text dispatch"
  810. )
  811. if clarify_gateway is None:
  812. return False
  813. if choice == "other":
  814. # Flip the entry into text-capture mode so the gateway's text intercept resolves the
  815. # clarify with the next message; otherwise that text would hit the agent path while
  816. # it's still blocked in clarify ("Interrupting current task" loop).
  817. try:
  818. flipped = clarify_gateway.mark_awaiting_text(clarify_id)
  819. except Exception:
  820. logger.exception("[whatsapp_cloud] mark_awaiting_text failed for %s", clarify_id)
  821. flipped = False
  822. if not flipped:
  823. # Entry vanished (timeout, /new, restart) — fall through to text.
  824. logger.info("[whatsapp_cloud] clarify 'Other' tap but entry missing (clarify_id=%s); falling back to text", clarify_id)
  825. return False
  826. # Keep the mapping live for further taps on the same prompt.
  827. self._clarify_state[clarify_id] = session_key
  828. await self._reply_best_effort(to, t("platform.whatsapp.clarify_type_answer"), "[whatsapp_cloud] clarify other-prompt failed")
  829. return True
  830. try:
  831. idx = int(choice)
  832. except ValueError:
  833. logger.warning("[whatsapp_cloud] clarify tap had non-int choice: %r", choice)
  834. self._clarify_state[clarify_id] = session_key # a follow-up text can still resolve
  835. return False
  836. # Title is the numeric label; the agent has the prompt in context to interpret it.
  837. if not clarify_gateway.resolve_gateway_clarify(clarify_id, str(inner.get("title") or str(idx + 1))):
  838. logger.info("[whatsapp_cloud] clarify resolver reported no waiter (clarify_id=%s) — falling back to text", clarify_id)
  839. return False
  840. return True
  841. async def _handle_approval_tap(self, to: str, inner: dict[str, Any], parts: list) -> bool:
  842. _, approval_id, choice = parts
  843. session_key = self._pop_tap_state(
  844. self._exec_approval_state, approval_id,
  845. "[whatsapp_cloud] approval tap with no matching state (approval_id=%s) — likely stale; falling back to text",
  846. choice, ("approve", "deny"),
  847. )
  848. if not session_key:
  849. return False
  850. request_id = self._approval_request_ids().pop(approval_id, None)
  851. approval = _optional_module("tools.approval", "[whatsapp_cloud] approval resolver unavailable")
  852. if approval is None:
  853. return False
  854. count = approval.resolve_gateway_approval_card(session_key, choice, request_id)
  855. # A tap after the wait timed out (count == 0) must not claim approval:
  856. # the command was already denied fail-closed.
  857. if count:
  858. confirm_text = t("platform.whatsapp.approved" if choice == "approve" else "platform.whatsapp.denied")
  859. else:
  860. logger.info("[whatsapp_cloud] approval resolver reported no waiter (session_key=%s) — likely already resolved", session_key)
  861. confirm_text = t("platform.whatsapp.approval_expired")
  862. await self._reply_best_effort(to, confirm_text, "[whatsapp_cloud] approval confirm failed")
  863. return True
  864. async def _handle_slash_confirm_tap(self, to: str, inner: dict[str, Any], parts: list) -> bool:
  865. _, choice, confirm_id = parts
  866. session_key = self._pop_tap_state(
  867. self._slash_confirm_state, confirm_id,
  868. "[whatsapp_cloud] slash_confirm tap with no matching state (confirm_id=%s) — likely stale",
  869. choice, ("once", "always", "cancel"),
  870. )
  871. if not session_key:
  872. return False
  873. slash_confirm = _optional_module("tools.slash_confirm", "[whatsapp_cloud] slash_confirm resolver unavailable")
  874. if slash_confirm is None:
  875. return False
  876. try:
  877. result_text = await slash_confirm.resolve(session_key, confirm_id, choice)
  878. except Exception:
  879. logger.exception("[whatsapp_cloud] slash_confirm.resolve failed")
  880. return True # still claim the tap; surfacing it as text wouldn't help
  881. if result_text:
  882. await self._reply_best_effort(to, result_text, "[whatsapp_cloud] slash_confirm reply failed")
  883. return True
  884. _INTERACTIVE_HANDLERS = {"cl:": _handle_clarify_tap, "appr:": _handle_approval_tap, "sc:": _handle_slash_confirm_tap}
  885. async def _collect_inbound_media(self, msg_type_str: str, raw_message: dict[str, Any], body: str) -> tuple[list[str], list[str], str]:
  886. """Download inbound media by ``media_id``; returns ``(media_urls, media_types, body)``."""
  887. inner = raw_message.get(msg_type_str) or {}
  888. media_id, inbound_mime = str(inner.get("id") or "").strip(), str(inner.get("mime_type") or "").strip()
  889. if not media_id:
  890. return [], [], body
  891. local_path, dl_mime = await self._download_media_to_cache(media_id, ext_hint=_ext_for_mime(inbound_mime))
  892. if local_path:
  893. logger.info("[whatsapp_cloud] cached inbound %s media: %s", msg_type_str, local_path)
  894. else:
  895. logger.warning(
  896. "[whatsapp_cloud] failed to download inbound %s (id=%s) — agent will see message metadata but not the binary",
  897. msg_type_str, media_id,
  898. )
  899. fname = str(inner.get("filename") or "").strip() if msg_type_str == "document" else ""
  900. body = body or (f"[Document: {fname}]" if fname else body)
  901. if not local_path:
  902. return [], [], body
  903. return [local_path], [dl_mime or inbound_mime or "application/octet-stream"], body
  904. @staticmethod
  905. def _inject_document_text(media_urls: list[str], body: str) -> tuple[str, list[bool]]:
  906. """Prepend text-readable document contents (≤100KB) to the body; returns
  907. ``(body, media_text_inlined)`` with one flag per ``media_urls`` entry (True = injected)."""
  908. inlined = [False] * len(media_urls)
  909. for i, doc in enumerate(map(Path, media_urls)):
  910. if doc.suffix.lower() not in _TEXT_INJECT_EXTS:
  911. continue
  912. try:
  913. file_size = doc.stat().st_size
  914. if file_size > _MAX_TEXT_INJECT_BYTES:
  915. logger.info("[whatsapp_cloud] skipping text injection for %s (%d bytes > %d)", doc, file_size, _MAX_TEXT_INJECT_BYTES)
  916. continue
  917. injection = f"[Content of {doc.name}]:\n{doc.read_text(encoding='utf-8-sig', errors='replace')}"
  918. body = f"{injection}\n\n{body}" if body else injection
  919. inlined[i] = True
  920. except OSError:
  921. logger.exception("[whatsapp_cloud] failed to read document text: %s", doc)
  922. return body, inlined
  923. async def _build_message_event_from_cloud(
  924. self, raw_message: dict[str, Any], contacts_by_waid: dict[str, str], metadata: dict[str, Any],
  925. ) -> Optional[MessageEvent]:
  926. """Convert a Cloud-API message object into a MessageEvent, or None if gated out."""
  927. msg_type_str = str(raw_message.get("type") or "text").lower()
  928. # Contentless envelopes arrive on the same ``messages`` webhook field and carry no
  929. # user utterance; falling through would start a blank agent turn (#90157).
  930. if msg_type_str in _CONTENTLESS_KINDS:
  931. logger.debug("[whatsapp_cloud] skipping contentless %s envelope (wamid=%s)", msg_type_str, raw_message.get("id"))
  932. return None
  933. # Button taps route to the gateway resolver BEFORE text dispatch — the
  934. # resolver unblocks the waiting agent, so don't also start a fresh turn.
  935. if msg_type_str == "interactive" and await self._dispatch_interactive_reply(raw_message, contacts_by_waid):
  936. return None
  937. extract = _BODY_BY_KIND.get(msg_type_str)
  938. body = str(extract(raw_message) or "") if extract else ""
  939. chat_id = sender_id = str(raw_message.get("from") or "").strip()
  940. sender_name = contacts_by_waid.get(sender_id, "")
  941. # DMs only: chat_id == sender wa_id. A ``chat`` field marks a group-shaped
  942. # payload (capability-gated by Meta) — refuse rather than treat as a DM.
  943. if raw_message.get("chat"):
  944. logger.warning(
  945. "[whatsapp_cloud] received group-shaped message (chat=%s, wamid=%s) — group support is not yet "
  946. "implemented; dropping. Use the Baileys whatsapp adapter for group chats.",
  947. raw_message.get("chat"), raw_message.get("id"),
  948. )
  949. return None
  950. if not self._should_process_message({"chatId": chat_id, "senderId": sender_id, "isGroup": False, "body": body}):
  951. return None
  952. media_urls, media_types, media_text_inlined = [], [], []
  953. if msg_type_str in _INBOUND_MEDIA_KINDS:
  954. media_urls, media_types, body = await self._collect_inbound_media(msg_type_str, raw_message, body)
  955. if msg_type_str == "document" and media_urls:
  956. body, media_text_inlined = self._inject_document_text(media_urls, body)
  957. # Meta's ``context`` gives only the quoted message's id (+ author), never its text or
  958. # bytes; resolve both from rich_sent_store so run.py can build "[Replying to: ...]" and
  959. # the quoted attachment reaches the vision/audio pipeline like a direct one.
  960. context = raw_message.get("context") or {}
  961. reply_to_id = str(context.get("id") or "").strip() or None
  962. reply_to_text = rich_sent_store.lookup(chat_id, reply_to_id) if reply_to_id else None
  963. # context.from == our business number → user replied to the bot.
  964. quoted_from = str(context.get("from") or "").strip()
  965. our_number = str(metadata.get("display_phone_number") or "").strip()
  966. reply_to_is_own = bool(reply_to_id and quoted_from and our_number) and quoted_from == our_number
  967. wamid = str(raw_message.get("id") or "") or None
  968. if wamid and chat_id:
  969. # Done AFTER gating so filtered messages don't leak typing/read receipts.
  970. bounded_put(self._last_inbound_wamid_by_chat, chat_id, wamid, INTERACTIVE_STATE_CACHE_SIZE)
  971. if body:
  972. await rich_sent_store.record_async(chat_id, wamid, body)
  973. if msg_type_str in _INBOUND_MEDIA_KINDS and media_urls:
  974. await rich_sent_store.record_media_async(chat_id, wamid, list(zip(media_urls, media_types)))
  975. if reply_to_id:
  976. for path, mime in rich_sent_store.lookup_media(chat_id, reply_to_id):
  977. if path not in media_urls:
  978. media_urls.append(path)
  979. media_types.append(mime)
  980. return MessageEvent(
  981. text=body, message_type=_MESSAGE_TYPE_BY_KIND.get(msg_type_str, MessageType.TEXT),
  982. source=self.build_source(
  983. chat_id=chat_id, chat_name=sender_name or chat_id, chat_type="dm",
  984. user_id=sender_id, user_name=sender_name or None,
  985. ),
  986. raw_message=raw_message, message_id=wamid, reply_to_message_id=reply_to_id,
  987. reply_to_text=reply_to_text, reply_to_is_own_message=reply_to_is_own,
  988. media_urls=media_urls, media_types=media_types, media_text_inlined=media_text_inlined,
  989. )
  990. # ---------------------------------------------------------------------------
  991. # Plugin registration
  992. # ---------------------------------------------------------------------------
  993. def _is_connected(config) -> bool:
  994. """Phone-number id + access token, from ``PlatformConfig.extra`` (YAML / env seeding) or the
  995. scope-aware env reader (``hermes_cli.gateway.get_env_value`` so setup-status patches see it)."""
  996. extra = (getattr(config, "extra", None) or {}) if config is not None else {}
  997. if extra.get("phone_number_id") and extra.get("access_token"):
  998. return True
  999. import hermes_cli.gateway as gateway_mod
  1000. return all((gateway_mod.get_env_value(name) or "").strip()
  1001. for name in ("WHATSAPP_CLOUD_PHONE_NUMBER_ID", "WHATSAPP_CLOUD_ACCESS_TOKEN"))
  1002. def _interactive_setup() -> None:
  1003. """``hermes gateway setup`` entry: the same wizard ``hermes whatsapp-cloud`` runs."""
  1004. from .setup_wizard import run_whatsapp_cloud_setup
  1005. run_whatsapp_cloud_setup()
  1006. # System-prompt platform hint (PlatformEntry.platform_hint); cached-prompt bytes, keep stable.
  1007. _PLATFORM_HINT = (
  1008. "You are on WhatsApp (Meta Business Cloud API). Standard markdown auto-converts to WhatsApp syntax "
  1009. "\u2014 write markdown freely. No tables \u2014 use bullets or labeled lines. "
  1010. "You can send files natively: write MEDIA:/absolute/path/to/file in your response. "
  1011. "Images (.jpg, .png) send as photos, videos (.mp4) inline, audio as voice/audio, other files as "
  1012. "documents; ![alt](url) works. NOTE: Meta refuses free-form replies when the user hasn't messaged in "
  1013. "24h (error 131047) \u2014 relevant only for delayed/scheduled sends."
  1014. )
  1015. def register(ctx) -> None:
  1016. """Plugin entry point — called by the Hermes plugin system.
  1017. No ``validate_config``: an unconfigured adapter still reaches ``connect()``, which records the
  1018. ``whatsapp_cloud_unconfigured`` fatal error (same outcome as the former core wiring). No
  1019. ``standalone_sender_fn`` / ``max_message_length``: out-of-process ``send_message`` had no
  1020. WhatsApp Cloud sender in core either, and ``send()`` chunks itself."""
  1021. from . import gateway_env # env -> GatewayConfig bridge (gateway.config_env)
  1022. ctx.register_platform(
  1023. name="whatsapp_cloud", label="WhatsApp Business (Cloud)", adapter_factory=WhatsAppCloudAdapter,
  1024. dashboard_label="WhatsApp Cloud API",
  1025. dashboard_description="Use Hermes via Meta's hosted WhatsApp Cloud API (no local bridge).",
  1026. docs_url="https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp-cloud",
  1027. check_fn=check_whatsapp_cloud_requirements, is_connected=_is_connected,
  1028. config_connected_fn=config_connected_extra("phone_number_id", "access_token"),
  1029. required_env=["WHATSAPP_CLOUD_PHONE_NUMBER_ID", "WHATSAPP_CLOUD_ACCESS_TOKEN"],
  1030. install_hint="aiohttp/httpx missing — reinstall hermes-agent", setup_fn=_interactive_setup,
  1031. cron_deliver_env_var="WHATSAPP_CLOUD_HOME_CHANNEL", emoji="📱", allow_update_command=False,
  1032. platform_hint=_PLATFORM_HINT,
  1033. # Adapter lacks edit_message; promote once it lands.
  1034. display_tier="low",
  1035. env_overrides=gateway_env.ENV_OVERRIDES,
  1036. env_enable_credentials=gateway_env.ENV_ENABLE_CREDENTIALS, **gateway_env.AUTHZ,
  1037. )