Descrizione
Avvia il workflow quando un cliente scrive al tuo numero WhatsApp Business (Meta Cloud API ufficiale, Graph v18+). Ogni messaggio in arrivo = una run del workflow con payload GIÀ normalizzato: mittente E.164, nome profilo, tipo messaggio (text, interactive button/list reply, image, document, audio, video, sticker, location, contacts, reaction), testo o caption, riferimenti media (id, mimeType, sha256, filename) da scaricare via Graph API, e context di reply per i thread. L'URL callback da incollare nel pannello Meta Business → WhatsApp → Configurazione → Webhook è https://<dominio-del-tuo-workspace>/webhooks/whatsapp/<workflow-id> — l'id del workflow compare nel path dell'editor dopo il primo salvataggio. Sicurezza fail-closed su entrambi i flussi del protocollo Meta: (a) il verification handshake GET risponde al hub.challenge SOLO se hub.verify_token combacia (confronto timing-safe) col Verify token configurato sotto — lo scegli tu e lo incolli identico nel pannello Meta; (b) ogni POST evento è accettato SOLO se la firma X-Hub-Signature-256 (HMAC-SHA256 dell'App Secret sui byte esatti del body) è valida — App Secret mancante o firma errata = 401, mai esecuzione. Dedup automatico per message-id (Meta ri-consegna gli eventi non ACK-ati: lo stesso messaggio non fa MAI ripartire il workflow due volte, TTL 24h). Status update (sent/delivered/read) ignorati di default — attivabili con lo switch dedicato. Differenza con i sibling: trigger_webhook = endpoint HTTP generico (nessuna semantica WhatsApp: handshake, firma Meta, dedup message-id e normalizzazione li dovresti costruire a mano); action_whatsapp_send = solo INVIO. Il pattern completo per un bot conversazionale è trigger_whatsapp → (logica/AI) → action_whatsapp_send: la risposta rientra nella finestra Customer Service di 24h aperta dal messaggio del cliente, quindi testo libero senza template pre-approvati. Output per ogni run: { messageId, from, profileName, phoneNumberId, displayPhoneNumber, timestamp (ISO 8601), type, text, interactive {id, title} | null, media {id, mimeType, sha256, caption, filename} | null, location {latitude, longitude, name, address} | null, replyToMessageId, kind: "message" | "status", raw }. Use case: (1) bot ordinazioni pizzeria/ristorante — il cliente scrive, l'AI agente legge menù e storico dal DB tenant e prende l'ordine, conferma via action_whatsapp_send; (2) assistenza clienti con escalation — i messaggi entrano nel workflow, un logic_if smista per parola chiave a operatore umano via action_send_email; (3) raccolta documenti — il cliente invia foto della fattura, il workflow scarica il media via Graph API e lo passa a OCR/gestionale; (4) opt-in campagne — button reply "ISCRIVIMI" registrato in tabella DB con consenso tracciato GDPR.