Collega WhatsApp a FyneDesk

Porta un numero WhatsApp Business in FyneDesk così che ogni messaggio in entrata diventi un ticket e il tuo team risponda direttamente dal ticket — senza bisogno di un'app WhatsApp separata. Puoi collegarti direttamente tramite la Cloud API di Meta o tramite un provider come Gupshup, 360Dialog o Twilio.

Cosa ti serve

• Un numero WhatsApp Business già configurato con il tuo provider (o direttamente con Meta).
• Accesso da amministratore alla tua organizzazione FyneDesk.
• Le credenziali del tuo provider — vedi il Passaggio 2 per sapere esattamente quali valori copiare.

Passaggio 1 — Aggiungi la connessione in FyneDesk

In FyneDesk, vai su Impostazioni amministratore → WhatsApp e fai clic su Aggiungi connessione. Sotto Dove si trova il tuo WhatsApp, scegli come è ospitato il tuo numero: Meta Cloud API diretto, Gupshup, 360Dialog, Twilio (modalità passthrough Meta) o Altro / provider personalizzato.

Poi compila il modulo:

• Numero di telefono WhatsApp Business — il numero a cui scrivono i clienti, in formato internazionale (es. +55 11 99999-9999).
• Phone Number ID — il lungo ID numerico dalla dashboard del tuo provider, non il numero di telefono visibile.
• Token di accesso — il token o la chiave API del tuo provider (Passaggio 2). Memorizzato crittografato; una volta salvato, non viene più mostrato.
• WhatsApp Business Account ID — facoltativo.
• App Secret — il valore che il tuo provider etichetta come App Secret o Webhook Signing Secret. FyneDesk lo usa per verificare che ogni messaggio in entrata provenga davvero da WhatsApp.
• Tipi di messaggio accettati — Testo, Immagini e Documenti.

Fai clic su Salva e collega.

Passaggio 2 — Ottieni le credenziali dal tuo provider

Trova la sezione che corrisponde al provider scelto nel Passaggio 1, copia i valori e incollali nel modulo.

Meta Cloud API diretto

Apri developers.facebook.com, vai alla tua app, poi WhatsApp → API Setup:

• Phone number ID e WhatsApp Business Account ID (WABA ID) sono mostrati in quella pagina.
• Fai clic su Generate token per il token di accesso.
• App Secret si trova sotto App Settings → Basic → App Secret → Show.

Gupshup

Apri hub.gupshup.io, apri la tua app WhatsApp e vai su Settings:

• Copia la tua API key e incollala nel campo Token di accesso di FyneDesk.
• Copia il tuo numero di telefono, il nome dell'app e il Phone Number ID.
• Per l'App Secret, usa il valore che Gupshup etichetta come Webhook Signature Secret (sotto Settings → Webhook).

Gupshup trasmette inalterato il formato webhook di Meta, quindi FyneDesk legge lo stesso payload sia che tu sia su Meta diretto sia su Gupshup.

360Dialog

Nell'hub 360Dialog, apri il canale per il tuo numero:

• Genera la tua API key (360Dialog la chiama D360-API-KEY) e incollala nel campo Token di accesso di FyneDesk. Ogni numero ha la sua chiave, e solo la chiave più recente resta valida.
• Copia il tuo Phone Number ID e il WABA ID dall'hub.
• Scegliere 360Dialog nel Passaggio 1 indica a FyneDesk di instradare attraverso l'endpoint di 360Dialog (waba-v2.360dialog.io) per te.

Twilio (modalità passthrough Meta)

FyneDesk ha bisogno del formato webhook nativo di Meta di WhatsApp. I webhook WhatsApp standard di Twilio usano il formato proprio di Twilio, che FyneDesk non può leggere — quindi il tuo numero Twilio deve essere configurato in modalità passthrough Meta, in cui Twilio inoltra inalterati i webhook grezzi di Meta.

• Abilita il passthrough Meta per il tuo mittente WhatsApp in Twilio, poi usa le tue credenziali Meta Cloud API (Phone number ID, token di accesso, App Secret) per quel numero, esattamente come nella sezione Meta sopra.
• Vedi la documentazione WhatsApp Business Platform di Twilio per abilitare il passthrough sul tuo account.

Se il tuo numero Twilio non può funzionare in modalità passthrough Meta, collegalo invece tramite Meta Cloud API diretto o un altro provider supportato.

Altro / provider personalizzato

Qualsiasi provider che inoltra il formato webhook della Cloud API di Meta funzionerà. Incolla le credenziali che il tuo provider ti fornisce nei campi corrispondenti. Se il tuo provider usa un endpoint API o un'intestazione di autenticazione diversi, apri Mostra impostazioni avanzate nel modulo per impostare l'URL di base in uscita e l'intestazione di autenticazione. Usa qualunque valore il tuo provider etichetti come App Secret o Webhook Signing Secret per il campo App Secret.

Passaggio 3 — Completa la configurazione nel tuo provider

Dopo aver salvato, FyneDesk mostra un banner con un Webhook URL e un Verify Token. Copia entrambi nelle impostazioni webhook del tuo provider e iscriviti ai messaggi in entrata.

Dove si trova l'impostazione webhook, per provider:

• Meta Cloud API diretto — WhatsApp → Configuration → Webhook: incolla il Webhook URL come Callback URL e il Verify Token, fai clic su Verify and save, poi iscriviti al campo messages.
• Gupshup — Settings → Webhook: incolla il Webhook URL e il Verify Token, e attiva l'evento messages (facoltativamente message_event per lo stato di consegna).
• 360Dialog — imposta l'URL webhook per il tuo numero nell'hub 360Dialog. (Ricorda che si azzera se rigeneri la API key.)
• Twilio — punta il webhook in entrata del tuo mittente WhatsApp al Webhook URL di FyneDesk.
• Altro / personalizzato — incolla il Webhook URL nel campo callback/webhook del tuo provider e abilita gli eventi dei messaggi in entrata.

Passaggio 4 — Testa la connessione

Di nuovo in FyneDesk, sulla riga della connessione, fai clic su Testa connessione. Un segno di spunta verde significa che le credenziali e il webhook funzionano. Poi invia un vero messaggio di prova: da un WhatsApp personale, scrivi al tuo numero aziendale. Dovrebbe comparire in FyneDesk come un nuovo ticket entro circa cinque secondi.

Risoluzione dei problemi