action_whatsapp_send · action · Utility · Available · v1.0.0

Description

Invia messaggi WhatsApp Business via Meta Cloud API ufficiale (Graph v18+) usando i due regimi del protocollo: messaggi text in finestra di conversazione (validi solo nelle 24 ore successive a un messaggio in ingresso del cliente, secondo le policy Customer Service di WhatsApp Business) oppure messaggi template pre-approvati nel Business Manager (UTILITY, MARKETING, AUTHENTICATION) inviabili in qualsiasi momento. Supporta header media (immagine, video, documento, location), placeholder body con sostituzione posizionale (variabili numerate {{1}}, {{2}}, ...), bottoni quick-reply/url/call e lingua multipla. Validazione formato numero E.164 obbligatoria (+393331234567) con conversione automatica dai formati nazionali comuni. Rate limit Meta rispettato con backoff esponenziale e jitter. Errori semantici espliciti: 132xxx (template), 131xxx (numero), 80007 (rate). Output: { messageId, recipient, mode, response, billable, conversationCategory }. L'integrazione passa SOLO per Phone Number ID assegnato dall'app WhatsApp Business dedicata — nessun accesso al numero personale del proprietario. Costi conversazione visibili in Insights Meta. Use case: notifica spedizione e-commerce con tracking number via template UTILITY, conferma appuntamento studio commercialista 24h prima con template AUTHENTICATION, ricezione documento via media header (cliente invia foto fattura → workflow estrae con OCR e crea fattura in Odoo), broadcast newsletter MARKETING con opt-out tracciato, escalation supporto tecnico real-time durante la finestra 24h con messaggi text plain.

⚙️ Configuration parameters

Fields shown in the editor when configuring the node. Generated directly from the NodeDefconfigFields.

Field	Type	Required	Default	Description
`phoneNumberId` Phone Number ID (Meta)	`string`	yes	— 1234567890123456	NON e` il tuo numero di telefono. E` l'ID NUMERICO che trovi nel pannello Meta Business → WhatsApp → Configurazione API. Composto da soli numeri.
`accessToken` Access Token (permanente)	`string (encrypted)`	yes	—	Token di accesso permanente da Meta Business → Sistema Users → genera token con permesso whatsapp_business_messaging. Bypassa scadenza, da custodire come segreto.
`apiVersion` Versione API Graph	`enum` `v18.0v19.0v20.0v21.0`	no	`v20.0`	Default v20.0. Cambia solo se Meta annuncia una deprecation.
`recipient` Destinatario (numero E.164)	`expression`	yes	— +39 333 1234567 oppure {{input.phone}}	Numero di telefono del destinatario in formato E.164. Spazi/trattini/parentesi vengono rimossi automaticamente. Il `+` opzionale.
`mode` Modalita`	`enum` `texttemplate`	yes	`text`	text = messaggio di testo libero. RICHIEDE che il cliente ti abbia scritto negli ultimi 24h (regola Meta). template = template pre-approvato in WhatsApp Business Manager. Funziona SEMPRE — l'unico modo per iniziare una nuova conversazione.
`body` Testo messaggio	`expression`	no	— Buongiorno {{input.nome}}, abbiamo ricevuto la sua PEC.	Testo del messaggio. Max 4096 caratteri. Supporta {{espressioni}}.
`previewUrl` Anteprime link automatiche	`boolean`	no	`false`	Se on, WhatsApp genera anteprime per i link nel body. Default off (UX piu` pulita + niente costo extra per la preview).
`templateName` Nome template	`string`	no	— pec_ricevuta_consegna	Nome esatto del template come approvato in WhatsApp Business Manager. Case-sensitive. Solo template "APPROVED" funzionano (PENDING / REJECTED danno errore).
`languageCode` Codice lingua	`string`	no	`it` it oppure en_US	Codice lingua del template. Deve combaciare ESATTAMENTE con quello scelto in WhatsApp Business Manager. Formato xx oppure xx_XX.
`componentsJson` Components (JSON array)	`code`	no	— [{"type":"body","parameters":[{"type":"text","text":"{{input.nome}}"},{"type":"text","text":"{{$today}}"}]}]	Array di components per popolare le variabili del template (placeholder {{1}}, {{2}}, ecc). Tipi parametro: text, currency, date_time, image, document, video. Vuoto = nessuna variabile (template fissi). Per dettagli: https://developers.facebook.com/docs/whatsapp/cloud-api/reference/messages
`timeoutMs` Timeout HTTP (ms)	`number`	no	`15000`	Range 1000-60000. Meta tipicamente risponde < 1s.
`includePipelineLog` Includi log nell'output	`boolean`	no	`true`	—

💡 Configuration example

JSON snippet of the node as it appears in the workflow. Values are derived fromdefaultValue and from required parameters.

{
  "id": "node-action_whatsapp_send-1",
  "defId": "action_whatsapp_send",
  "label": "WhatsApp",
  "config": {
    "phoneNumberId": "1234567890123456",
    "accessToken": "<accessToken>",
    "apiVersion": "v20.0",
    "recipient": "+39 333 1234567   oppure   {{input.phone}}",
    "mode": "text",
    "previewUrl": false,
    "languageCode": "it",
    "timeoutMs": 15000,
    "includePipelineLog": true
  }
}

🔗 Related nodes in the same category

Ready to use WhatsApp?

Available now on all FlowForge plans. Try it free without a credit card.

Start free Browse all nodes