`gjWdZddlmZddlZddlZddlZddlmZddZddZ ddZ ddZ dd Z ddd Z ddd d  dd ZddZy)u$ Interactive setup wizard for the WhatsApp Cloud API adapter. Entry point: ``hermes whatsapp-cloud`` (dispatched from ``cmd_whatsapp_cloud`` in ``hermes_cli/main.py``). Walks the user through the 6 credentials Meta requires + recipient allowlist, auto-generates the verify token, and prints exact follow-up instructions for the parts that can't happen inside the wizard process (starting cloudflared, starting the gateway, configuring Meta's webhook dashboard, adding their phone to the recipient list). Heavy emphasis on field-shape validation to catch the most common configuration mistakes: - Putting the actual phone number in ``WHATSAPP_CLOUD_PHONE_NUMBER_ID`` (the field expects Meta's 15-17 digit internal ID, not a phone number). This is the #1 trap — caught us during Phase 3 live testing. - Pasting tokens with trailing whitespace. - Pasting an OpenAI / Slack / GitHub key by mistake. - Confusing App ID with WABA ID with Phone Number ID. Each prompt has contextual help showing exactly where to find the value in Meta's App Dashboard, with a one-line description and the field's expected shape ("starts with EAA", "15-17 digits", "32 hex chars", etc.). The wizard intentionally does NOT smoke-test the webhook itself — the Hermes gateway and the cloudflared tunnel both run in separate processes the user starts AFTER this wizard exits, so any in-wizard probe would fail by design. Instead the final SETUP COMPLETE block prints the exact curl command the user can run from a third terminal to verify the loop end-to-end once everything's running. ) annotationsN)Optionalc|sy|j}|jsydt|cxkrdkryt|dkryt|dkDry y ) u'Phone Number ID is a 15-17 digit numeric ID assigned by Meta. It's NOT a phone number. The #1 setup mistake is pasting the actual phone number (e.g. ``15556422442``) into this field — that's only 10-11 digits and gets rejected by Graph as "Object with ID does not exist." )FzPhone Number ID is required)Fz;Phone Number ID must be numeric (no '+', spaces, or dashes) )FuThat looks like a phone number — but this field needs the Phone Number ID (Meta's internal ID, 15-17 digits, e.g. '7794189252778687'). Look just BELOW the 'From' dropdown in API Setup → it's labelled 'Phone number ID'. )Fz7Phone Number ID looks too short (expected 13-18 digits))Fz6Phone Number ID looks too long (expected 13-18 digits)TNstripisdigitlenvaluess R/root/.hermes/venv/lib/python3.12/site-packages/hermes_cli/setup_whatsapp_cloud.py_validate_phone_number_idr4s_ 3 A 99;S  SVr  1v{O 1v{N c|sy|j}|jsyt|dkst|dkDryy)zTUUU rFc, |rd|dnd}|rHtjjr*ddl}|j||dj }|St ||dj } |S#t tf$r tYywxYw)uRead one line of input. Returns "" on EOF / Ctrl+C / empty input. The ``default`` parameter is shown to the user but NOT auto-applied on empty input — callers handle the "user kept existing" case explicitly so they can distinguish between a real value and a display preview (e.g. ``"abc12345..."`` for masked secrets). ``secret=True`` reads via ``getpass`` so credentials are not echoed to the terminal (or left in scrollback).  []rNz (input hidden): : ) sysstdinisattygetpassr inputEOFErrorKeyboardInterruptprint)messagedefaultsecretsuffixr0raws r_promptr:s $+2gYa cii&&( //WIfX5F"GHNNPC J 7)F82./557C J ' ( sAA7A77BB)current help_textr7cj|r1|jjD]}td|d} |dz }td|||}|sy||\}} |r|jStd| |dk\r t d j} | syd}i#t t f$rYywxYw) a Repeat the prompt until the user enters a valid value or aborts. Returns the validated value, or None if the user gave up (empty response after an error, or Ctrl+C). ``current`` is shown as a default for re-runs of the wizard with existing config. z ru → )r6r7Nu ✗ z' Try again, or press Enter to skip: )r splitlinesr4r:r1r2r3) r5 validatorr;r<r7lineattemptsrokreasonconts r_prompt_validatedrGsOO%002 D Btf+  H A & *GFKu% F ;;=  !" q= FGMMOH! /0  sB B21B2cddlm}m}ttdtdttdtdttdtdtd td td ttd td ttdtdtdtdtdt t dj }ttdtdtd|dxsd}tdt|d}|s|r|}td|n#tdy|d|td|ttdtd td|d!xsd}|r|dd"d#znd}td$t|d%d&'}|s|r|}td(n td)y|d!|td*ttdtd+td|d,xsd}|r|dd-d#znd} td.t| d%d/'} | s'|r|} td0n+td1td2n|d,| td3ttdtd4td|d5xsd} td6d7| d8} | r|d5| td| n| rtd| |d9xsd} td:d;| d<}|r|d9|td|n| rtd| ttdtd=td|d>xsd}|rytd?|dd-d@ t dAj j}|dCvr-tjdD}|d>|tdE|n:|}tdFn,tjdD}|d>|tdG|ttdHtdIttdtdJtdttdKtdLtdMtdNt|dOxsd}|r|nd} t dP|rdQ|zdRzndSdTj xs|xsdS}|r?dUjdV|j!dUD}|dO|td|ntdWtdXttdtdYtdttdZtd[td\ttd]td^td_td`ttdatdbttdctddtdettdftdgttdhtdittdjtdk|dltdmttdntdotdpttdqtdrtdstdt|tdutdvttdwtdxtdyttdzttdtd{tdttd|td}td~tdt|xs| }|rtdtd|n!tdtdtdtdttdtdttdtdtdttdtdty#t tf$rtdYywxYw#t tf$rdB}YwxYw#t tf$rdS}YwxYw)zInteractive wizard for the WhatsApp Cloud API adapter. Returns 0 on full success, 1 on user abort, 2 on partial completion (some fields written but the user bailed before finishing). r) get_env_valuesave_env_valueu%⚕ WhatsApp Business Cloud API Setupz2==================================================zu──────────────────────────────────────────────────uSTEP 1 — Phone Number IDWHATSAPP_CLOUD_PHONE_NUMBER_IDNzPhone Number IDu8Found in: App Dashboard → WhatsApp → API Setup, in the 'Send and receive messages' section. Look BELOW the 'From' dropdown — there's a 'Phone number ID' line with the value (15-17 digits, e.g. '7794189252778687'). It is NOT the phone number itself (+1 555-...). That's the single most common setup mistake.)r;r<u ✓ Keeping existing: u+ ✗ Phone Number ID is required. Aborting.u ✓ Saved: uSTEP 2 — Access TokenWHATSAPP_CLOUD_ACCESS_TOKENz...z Access TokenTuTwo options for getting one: (a) TEMP — App Dashboard → WhatsApp → API Setup → 'Generate access token' button. Lasts 24 hours. Fine for testing today; you'll have to regenerate tomorrow. (b) PERMANENT (production) — System User token. One-time setup, never expires: • business.facebook.com → Settings → System users → Add → Admin role • Assign Assets → your app (Manage app), your WhatsApp account (Manage WABAs) • Generate token → expiration: Never → permissions: business_management, whatsapp_business_messaging, whatsapp_business_management Tokens start with 'EAA'.)r;r7r<u ✓ Keeping existing tokenu( ✗ Access Token is required. Aborting.u ✓ Saved (token hidden)uCSTEP 3 — App Secret (required for webhook signature verification)WHATSAPP_CLOUD_APP_SECRETz App SecretuUFound in: App Dashboard → Settings → Basic → 'App secret' field (click 'Show', enter your Facebook password). If 'Show' doesn't appear, you may need Admin role on the app. It's a 32-character lowercase hex string. Without the App Secret, inbound webhook POSTs are refused with HTTP 503 (we can't verify they actually came from Meta).u! ✓ Keeping existing App Secretu= ⚠ Skipping App Secret — inbound webhooks will be refusedz4 until you set WHATSAPP_CLOUD_APP_SECRET manually.u ✓ Saved (secret hidden)u5STEP 4 — App ID & WABA ID (optional, for analytics)WHATSAPP_CLOUD_APP_IDz&App ID (optional, press Enter to skip)c |sdSt|SNr )rvs rz*run_whatsapp_cloud_setup..xsa,-=a-@ruFound in: App Dashboard → Settings → Basic → 'App ID' at the top of the page. Numeric, ~15-16 digits. Not required for messaging — useful only for analytics later.WHATSAPP_CLOUD_WABA_IDz'WABA ID (optional, press Enter to skip)c |sdSt|SrR)rrSs rrUz*run_whatsapp_cloud_setup..sa,->q-AruWhatsApp Business Account ID. Found in: App Dashboard → WhatsApp → API Setup, near the top — 'WhatsApp Business Account ID'. Numeric, ~15+ digits. Not required for messaging — useful for analytics.u(STEP 5 — Verify Token (auto-generated)WHATSAPP_CLOUD_VERIFY_TOKENz+ An existing verify token is already set (z...).z Generate a new one? [y/N]: n>yyesru ✓ New verify token: u# ✓ Keeping existing verify tokenu ✓ Generated: u> → COPY THIS TOKEN NOW. You'll paste it into Meta's webhookz% configuration dialog (next step).uSTEP 6 — Recipient Allowlistz; Who is allowed to message the bot? (Comma-separated phonez> numbers with country code, no '+' / spaces / dashes. Use '*'u@ to allow anyone — only safe if you've also configured Meta'sz0 recipient whitelist for app-development mode.)WHATSAPP_CLOUD_ALLOWED_USERSu → Allowed usersr)r*r+r,,c3lK|],}|jstjdd|.yw)z[\s\-+]r+N)r rsub).0parts r z+run_whatsapp_cloud_setup..s* -14:: Alternatives: ngrok, or your own domain + reverse proxyz with TLS.z/ 2. Start the tunnel in a separate terminal:z7 cloudflared tunnel --url http://localhost:8090z? Note the printed https://.trycloudflare.com URL.z4 3. Start the Hermes gateway in another terminal:z hermes gatewayz: 4. Verify your local config is reachable. From a thirdz1 terminal, with the tunnel URL substituted:zG curl 'https://YOUR-TUNNEL.trycloudflare.com/whatsapp/webhook?\z3 hub.mode=subscribe&hub.verify_token=z&\z# hub.challenge=hello'z, Expected: HTTP 200 with body 'hello'.zB Also try: curl https://YOUR-TUNNEL.trycloudflare.com/healthz? (should return JSON with verify_token_configured: true).z. 5. Configure Meta to point at your tunnel:uF App Dashboard → WhatsApp → Configuration → Edit webhookz4 Callback URL: /whatsapp/webhookz Verify Token: u$ → Click 'Verify and save'uE → Then 'Manage' webhook fields → subscribe to 'messages'z/ 6. Add your phone to Meta's recipient list:u> App Dashboard → WhatsApp → API Setup → 'To' →z# 'Manage phone number list'z0 7. DM the bot's test number from your phone.z,Optional: polish your bot's WhatsApp profilez@ WhatsApp shows a display name and profile picture for your botz@ in every chat header and contact list. These are set in Meta'suB Business Manager, not via this wizard — but here's where to doz it once you're up and running:u' • Display name + profile picture:zG https://business.facebook.com/wa/manage/phone-numbers/?waba_id=z> https://business.facebook.com/wa/manage/phone-numbers/z< (select your WhatsApp Business Account on that page)z> Display-name changes go through a ~24-48h Meta review.u> • About, description, website, hours, business category:uA Same page → click your phone number → 'Edit profile'.u) • Verified badge (the green check):u9 Requires Meta's business verification process —uD Business Manager → Security Center → Start Verification.z> Docs: https://hermes-agent.nousresearch.com/docs/user-guide/z messaging/whatsapp-cloud)hermes_cli.configrIrJr4r1r r2r3rGrr'r rsecrets token_urlsafejoinsplit)rIrJproceedcurrent_phone_idphone_id current_tokencurrent_displaytokencurrent_secretcurrent_secret_display app_secretcurrent_app_idapp_idcurrent_waba_idwaba_idcurrent_verifyregen verify_token current_allow allow_defaultallowedeffective_wabas rrun_whatsapp_cloud_setupr|s( @ G 12 (O G HI ?@ G ;< ;< CD HI 34 G GH 9: G DE >? 9: IJ FG GIJPPR  G * &' *$%EFN$ !  0 H  'H ,XJ7 8 @ A7B hZ() G * #$ *!"?@HDM6C}Sb)E1O  '  E0  !E 0 1 = >4e< *+ G * OP *"#>?G4N=KnRa058QU"& L J  'J 5 6 R S H I2J? +, G * AB *"#:;CtN 0@ N F.7 fX&'  ((89:#$<=EO1A C G/9 gY'(  ((9:; G * 45 *"#@AITN ;N2A G TU ? ~S QR /0 G 89 NO KL G :; RS @A #L> 23 01 QR G ;< JK /0 G <= G * 89 * G LM LM NO ,- G/N 78 ()+ , 78 NO LM JK G JK MN G 56 EF PQ G JK ,- G k ' ( "#r+, E B ' (s66b1'b6!/cb32b36c  c c#"c#)rstrreturnztuple[bool, Optional[str]])NF)r5r}r6 Optional[str]r7boolr~r}) r5r}r;rr<rr7rr~r)r~int)__doc__ __future__rrrdr-typingrrrrr r'r:rGr|rrrs D#  >    "T:"# " " "  "  ""Tu r