# API chiavi (SyBox)

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.

### Come attivare il gateway e creare una chiave

1. Vai su Impostazioni > Integrazioni > API chiavi.
2. Attiva l'interruttore "Gateway API".
3. Clicca su "Nuova chiave".
   ![Settings, API keys: keys that let another program send through SyBox, and the "New key" button](https://www.sybox.io/res/sybox/help/it/turn-on-the-gateway-and-create-a-key-3.webp?v=b4c6ce30)
4. 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.
5. Inserisci il "Nome del dispositivo o del programma", ad esempio "PC ufficio" o "Software contabilità". Assegna una chiave distinta a ciascun dispositivo o programma.
6. 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)".
7. 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.
8. Clicca su Salva.
9. 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".

### Come modificare, sospendere o eliminare una chiave

1. 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.
   ![To change, pause or delete a key: "Edit" marked on the screen in SyBox](https://www.sybox.io/res/sybox/help/it/change-pause-or-delete-a-key-1.webp?v=16cb1a0d)
2. Clicca su Abilita / Disabilita per sospendere temporaneamente una chiave.
3. Clicca su Elimina, quindi conferma: "Eliminare questa chiave API? Qualsiasi programma che la sta ancora usando smetterà subito di funzionare."

**Q: 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.

**Q: 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.

**Q: L'elenco "Sends da" è vuoto.**

L'elenco mostra solo i numeri WhatsApp collegati e attivi. Collega prima un numero in Impostazioni > Messaggistica > Canali.

**Q: 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.

**Q: 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.

**Q: 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".

Source: https://www.sybox.io/it/help/api-keys