API chiavi
Aggiornato il
Dove: Impostazioni > Integrazioni > API chiavi
A cosa serve:
"Assegna a un programma esterno la propria chiave per inviare tramite SyBox: il token di WhatsApp non lascia mai il server e una chiave compromessa può essere revocata singolarmente." Il tuo gestionale ERP, punto vendita o software desktop utilizza una chiave di SyBox, senza aver mai bisogno delle tue credenziali WhatsApp reali.
Cosa può fare un programma con una chiave (dettagli nella documentazione per sviluppatori):
- Inviare messaggi WhatsApp dal tuo numero collegato. Utilizza lo stesso formato di richiesta delle API Cloud di WhatsApp di Meta; perciò un programma già configurato per esse deve solo aggiornare l'indirizzo e inserire una chiave di SyBox. Testo, modelli, immagini, documenti e messaggi interattivi sono tutti supportati. Le risposte e gli errori vengono restituiti esattamente come forniti da Meta.
- Apri una pratica dal tuo sistema, ad esempio per un reclamo registrato nell'ERP. Il cliente deve essere già presente in SyBox.
- Importa SMS da un telefono nella posta in arrivo.
- Avvia le tue automazioni da un altro sistema (una chiave di tipo "Avvia un'automazione").
- Cerca, leggi e modifica i tuoi contatti da un altro sistema (una chiave di tipo "Leggi e aggiorna i contatti").
Chi può aprirla: l'amministratore principale e i membri del team con il permesso "Gestisci i canali".
L'interruttore "Gateway API":
In cima alla schermata delle chiavi API è presente un interruttore chiamato "Gateway API". È disattivato per impostazione predefinita. Quando è disattivato, nessuna chiave funziona e non è possibile crearne di nuove. Se ci provi, compare il messaggio "Il gateway API è disattivato. Attivalo con l'interruttore in cima a questa schermata prima di creare le chiavi." L'interruttore salva la modifica all'istante.
- Vai su Impostazioni > Integrazioni > API chiavi.
- Attiva l'interruttore "Gateway API".
- Clicca su "Nuova chiave".
- Scegli il "Tipo di chiave":
- "Invia tramite WhatsApp": il programma invia messaggi ai tuoi clienti.
- "Apri una pratica": il programma crea pratiche in SyBox. Non può inviare messaggi.
- "Importa SMS da un telefono": un telefono inoltra i propri messaggi SMS nella posta in arrivo.
- "Avvia un'automazione": il programma avvia le automazioni il cui "Parte quando" è "Un altro programma chiama SyBox" (POST /v1/automation con il "phone" del cliente ed "event" e "data" facoltativi). Non può inviare messaggi. Vedi Impostazioni > IA e automazione > Automazioni.
- "Leggi e aggiorna i contatti": il programma cerca i contatti, ne legge uno e ne modifica nome, email, campi contatto ed etichette (POST /v1/contacts/search, /get, /update e /labels). Non può inviare messaggi. La chiave agisce a nome della persona che l'ha creata: vede solo i contatti che quella persona può vedere, funziona solo se quella persona può aprire l'elenco dei contatti e vedere i numeri, e può modificare i contatti solo se quella persona può modificarli. Se quella persona viene disattivata, la chiave smette di funzionare.
- Inserisci il "Nome del dispositivo o del programma", ad esempio "PC ufficio" o "Software contabilità". Assegna una chiave distinta a ciascun dispositivo o programma.
- Per una chiave di tipo "Invia tramite WhatsApp", configura anche:
- "Sends da": il numero WhatsApp da cui questa chiave invia i messaggi (obbligatorio).
- "Consenti messaggi a testo libero": attivo o disattivato.
- "Consenti modelli approvati": attivo o disattivato. Almeno una di queste due opzioni deve essere attiva, altrimenti comparirà "Consenti almeno uno tra testo libero o modelli — altrimenti la chiave non potrà inviare nulla."
- "Consenti l'invio di file multimediali": attivo o disattivato.
- "Modelli" (facoltativo): i nomi dei modelli, separati da virgole. Lascia vuoto per consentire qualunque modello.
- "Paesi destinatari consentiti" (facoltativo): codici paese a due lettere, ad esempio IT,FR,ES. Lascia vuoto per consentire qualunque paese.
- "Invio consentito dalle" ... "A": le fasce orarie in cui la chiave può inviare. Imposta lo stesso valore su entrambi per non avere limiti di orario. Gli orari si riferiscono all'ora locale dello spazio di lavoro.
- "Limite giornaliero di messaggi (0 = illimitato)".
- Per una chiave di tipo "Importa SMS da un telefono", imposta "Solo contatti e clienti". Quando è attiva, gli SMS ricevuti da qualsiasi altro numero rimangono sul telefono e non entrano nella posta in arrivo. Disattivala solo se il telefono è dedicato esclusivamente al lavoro.
- Clicca su Salva.
- Una finestra mostrerà l'"URL di base" e la "Chiave API". Copiali subito. "Copia subito questa chiave — viene mostrata una sola volta." Inseriscili nelle impostazioni del tuo programma.
Cosa mostra la scheda della chiave:
- Il nome della chiave e il numero da cui invia (o l'etichetta del tipo, per le chiavi che non inviano messaggi).
- Gli ultimi caratteri della chiave, per poter distinguere facilmente le chiavi create.
- "usato l'ultima volta", con data e ora, oppure "mai".
- Gli eventuali limiti impostati: "Solo testo libero", "Solo modelli", "nessun media", "Modelli", paesi consentiti, orari di invio e il limite giornaliero mostrato come inviati oggi / limite / giorno. Una chiave SMS che accetta qualsiasi mittente mostra "Tutti i numeri".
- Clicca su Modifica nella scheda della chiave. Puoi modificarne il nome, il numero e i limiti. Il tipo di chiave non può essere modificato dopo la creazione e la chiave in chiaro non verrà mai più mostrata.
- Clicca su Abilita / Disabilita per sospendere temporaneamente una chiave.
- Clicca su Elimina, quindi conferma: "Eliminare questa chiave API? Qualsiasi programma che la sta ancora usando smetterà subito di funzionare."
Ho perso la mia chiave API. Posso visualizzarla di nuovo?
No. Viene mostrata una sola volta. Crea una nuova chiave, inseriscila nel tuo programma ed elimina la vecchia chiave.
Temo che una chiave sia stata compromessa. Cosa devo fare?
Elimina o disabilita immediatamente quella chiave. Smetterà di funzionare solo quella specifica chiave. Il tuo numero WhatsApp e le altre chiavi non subiranno interruzioni.
L'elenco "Sends da" è vuoto.
L'elenco mostra solo i numeri WhatsApp collegati e attivi. Collega prima un numero in Impostazioni > Messaggistica > Canali.
Le richieste di invio del mio programma vengono rifiutate.
Verifica che l'interruttore "Gateway API" sia attivo e che la chiave risulti abilitata. Controlla anche i limiti della chiave: testo libero o modelli, file multimediali, modelli autorizzati, paesi consentiti, orari di invio e limite giornaliero. Si applicano comunque le regole native di WhatsApp: ad esempio, i messaggi di testo libero sono consentiti solo entro 24 ore dall'ultimo messaggio del cliente.
Una chiave di tipo "Apri una pratica" può anche inviare messaggi?
No, è progettata appositamente così. Una chiave per le pratiche non può scrivere ai clienti e una chiave di invio non può aprire pratiche. Usa una chiave diversa per ciascuna operazione.
Ho una vecchia chiave di tipo "Ricevi da un programma". Funziona ancora?
Sì, le chiavi esistenti di questo tipo continuano a funzionare. Non è più possibile crearne di nuove; per queste operazioni usa "Apri una pratica".