# Integrazione con GoHighLevel (GHL)

Stai già utilizzando GoHighLevel (GHL) per gestire la tua attività? Questa integrazione ti consente di aggiungere la messaggistica basata sull'IA di <span data-t="appName">Your AI Connector</span> alla tua configurazione GHL esistente. I messaggi che arrivano in GHL vengono inoltrati a <span data-t="appName">Your AI Connector</span> per la gestione tramite IA e le risposte di <span data-t="appName">Your AI Connector</span> vengono inviate nuovamente tramite GHL al cliente sul canale originale.

> Utilizzi un CRM diverso? Non serve una schermata dedicata per farlo funzionare con <span data-t="appName">Your AI Connector</span>: consulta [Connettere uno strumento non presente nel nostro elenco](connecting-other-tools.md) per funzioni personalizzate, API e webhook.

Ciò significa che puoi continuare a utilizzare GHL come hub principale, lasciando che l'IA gestisca le conversazioni basate sull'intelligenza artificiale.

::: note
**Nota:** Si tratta di un'integrazione più tecnica che prevede la configurazione di flussi di lavoro automatizzati e la connessione dei sistemi tramite webhook (notifiche automatiche tra app) e chiamate API. Se non ti senti a tuo agio con queste operazioni, potresti voler affidare questa pagina a uno sviluppatore o a un membro del team esperto di tecnologia.
:::


---

## Prerequisiti

- Un **account <span data-t="appName">Your AI Connector</span>** attivo con la tua chiave API (che trovi in **Impostazioni → Integrazioni → Chiave API**). Una chiave API è un codice univoco che consente a GHL di comunicare in modo sicuro con il tuo account.
- Un **account GoHighLevel** con l'autorizzazione per creare flussi di lavoro e gestire webhook (notifiche automatizzate tra sistemi).

---

## Come funziona

| Direzione | Cosa succede |
|---|---|
| **Da GHL a <span data-t="appName">Your AI Connector</span>** | Un cliente ti invia un messaggio tramite SMS, email, Messenger, Instagram o live chat in GHL. Un flusso di lavoro inoltra automaticamente quel messaggio a <span data-t="appName">Your AI Connector</span>. <span data-t="appName">Your AI Connector</span> lo elabora (risposta IA, tagging, ecc.). |
| **Da <span data-t="appName">Your AI Connector</span> a GHL** | Quando <span data-t="appName">Your AI Connector</span> invia una risposta (manualmente o tramite IA), notifica automaticamente GHL. Un flusso di lavoro in GHL trova il contatto e invia la risposta tramite il canale corretto. |

---

## Flusso di lavoro 1: Da GHL a <span data-t="appName">Your AI Connector</span>

Questo flusso di lavoro inoltra i messaggi in arrivo da GHL a <span data-t="appName">Your AI Connector</span>.

### Passaggio 1: Crea il flusso di lavoro

1. In GHL, vai su **Automazione > Flussi di lavoro**.
2. Fai clic su **Crea nuovo flusso di lavoro**.
3. Dagli un nome descrittivo, come "Invia messaggio a <span data-t="appName">Your AI Connector</span>".

### Passaggio 2: Aggiungi trigger

Aggiungi un trigger per ogni canale che desideri inoltrare:

- Risposta del cliente - SMS
- Risposta del cliente - Email
- Risposta del cliente - Messaggio Facebook
- Risposta del cliente - DM Instagram
- Risposta del cliente - Live Chat

Puoi aggiungerli tutti o solo i canali pertinenti alla tua configurazione.

### Passaggio 3: Aggiungi filtro tag (opzionale)

Se desideri inoltrare solo i messaggi provenienti da contatti specifici:

1. Fai clic su **Aggiungi filtro** sul trigger.
2. Imposta la condizione su "Il contatto ha un tag".
3. Scegli il/i tuo/i tag.
4. Seleziona se il contatto deve avere **qualsiasi** o **tutti** i tag selezionati.

### Passaggio 4: Crea una suddivisione dei canali

Aggiungi un'azione **Condizione** per instradare ogni canale verso il proprio webhook:

| Ramo | Condizione |
|---|---|
| Ramo 1 | La sorgente del messaggio è uguale a `Email` |
| Ramo 2 | La sorgente del messaggio è uguale a `SMS` |
| Ramo 3 | La sorgente del messaggio è uguale a `Messenger` |
| Ramo 4 | La sorgente del messaggio è uguale a `Instagram` |
| Ramo 5 | La sorgente del messaggio è uguale a `Live Chat` |

### Passaggio 5: Configura i webhook

Per ogni ramo, aggiungi un'azione **Webhook / Richiesta HTTP**:

- **Metodo:** `POST`
- **URL:**
  ```
  https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
  ```

- **Campi dati personalizzati:**

| Campo | Valore | Note |
|---|---|---|
| `messageSid` | `{{right_now.second}}{{contact.id}}` | Identificatore univoco del messaggio |
| `fromId` | `{{contact.id}}` | ID contatto GHL |
| `toId` | `{{user.id}}` | Il tuo ID utente GHL |
| `body` | `{{message.body}}` | Il contenuto del messaggio |
| `channel` | Vedi tabella sotto | Deve corrispondere al ramo |
| `status` | `created` | Impostare sempre su `created` |
| `messageType` | `text` | Tipo di messaggio |

**Valori del canale per ramo:**

| Ramo | Valore `channel` |
|---|---|
| Email | `email` |
| SMS | `sms` |
| Messenger | `messenger` |
| Instagram | `ig` |
| Live Chat | `livechat` |

::: warning
**Importante:** Assicurati che il valore `channel` corrisponda esattamente: sono sensibili alle maiuscole.
:::


### Passaggio 6: Abilita il rientro

Nelle impostazioni del flusso di lavoro, assicurati che **Consenti rientro** sia abilitato. Senza questa opzione, verrà inoltrato solo il primo messaggio di ogni contatto.

---

## Flusso di lavoro 2: Da Your AI Connector a GHL

Questo flusso di lavoro riceve le risposte da Your AI Connector e le invia al cliente tramite il canale GHL corretto.

### Passaggio 1: Creare un Webhook in entrata in GHL

1. In GHL, vai su **Impostazioni > Sviluppatori / API**.
2. Fai clic su **Crea nuovo webhook** (o "Webhook in entrata").
3. Chiamalo "Messaggi".
4. Salva e **copia l'URL del webhook**: ti servirà nel passaggio successivo.

### Passaggio 2: Configura Your AI Connector

1. In Your AI Connector, fai clic su **Settings** nella barra laterale.
2. Sotto **Channels**, fai clic su **Channels**.
3. Scorri fino alla scheda **Custom channel** in fondo alla pagina.
4. Incolla l'URL del webhook in entrata di GHL che hai appena copiato in **Webhook URL** (deve essere un indirizzo HTTPS pubblico) e fai clic su **Save**.

> **Questa non è la pagina Settings → Integrations → Webhooks.** Quella pagina serve per le notifiche degli eventi e invia un payload diverso. Il relay in uscita di GHL si imposta nella scheda **Custom channel** sotto **Settings → Channels**.

Your AI Connector invierà ora automaticamente una notifica a GHL ogni volta che viene inviato un messaggio a un contatto. I dati inviati appaiono così:

```json
{
  "contactId": "NtL97bwnhITrfIq8lWFi",
  "messageId": "s28dtg13qNuhXLoKpcLs",
  "userId": "wpDZRvaw4Hgh4whUBpwlKPRftOi2",
  "body": "Message content here",
  "toId": "qtpBsc6fiqkXTnSOeze3",
  "channel": "email"
}
```

> **Nota di navigazione:** la chiave API che utilizzi per il Workflow 1 e la scheda Custom channel che utilizzi qui si trovano in posti diversi: **Settings → Integrations → API Key** per la chiave, e la scheda **Custom channel** in fondo a **Settings → Channels** per questo relay. La pagina separata **Settings → Integrations → Webhooks** serve per le notifiche degli eventi e invia un payload diverso; consulta [Webhooks](webhooks.md) se è quello che ti serve.

### Passaggio 3: Creare il flusso di lavoro di risposta

1. In GHL, vai su **Automazione > Flussi di lavoro**.
2. Crea un nuovo flusso di lavoro chiamato "Invia messaggio al contatto".
3. Imposta il trigger su **Webhook in entrata** e seleziona il webhook creato nel Passaggio 1.

### Passaggio 4: Aggiungere un'azione Trova contatto

1. Aggiungi un'azione **Trova contatto**.
2. Imposta il campo di ricerca su **ID contatto**.
3. Usa il valore: `{{inboundWebhookRequest.toId}}`

### Passaggio 5: Aggiungere un controllo tag opzionale

Se desideri limitare quali contatti ricevono messaggi da Your AI Connector:

1. Aggiungi un'azione **Condizione**.
2. Verifica se il contatto ha un tag specifico.
3. Se il tag manca, termina il flusso di lavoro (aggiungi un'azione "Interrompi" sul ramo falso).

### Passaggio 6: Aggiungere una suddivisione dei canali

Aggiungi un'azione **Condizione** che instrada il messaggio in base a `{{inboundWebhookRequest.channel}}`:

| Ramo | Condizione | Azione |
|---|---|---|
| Ramo 1 | uguale a `email` | Invia email |
| Ramo 2 | uguale a `sms` | Invia SMS |
| Ramo 3 | uguale a `messenger` | Invia messaggio Facebook |
| Ramo 4 | uguale a `ig` | Invia messaggio Instagram |
| Ramo 5 | uguale a `livechat` | Invia messaggio chat |

### Passaggio 7: Configura ogni azione di invio

In ogni azione di invio, imposta il corpo del messaggio su:

```
{{inboundWebhookRequest.body}}
```

### Passaggio 8: Abilita il rientro

Come per il Flusso di lavoro 1, assicurati che **Consenti rientro** sia abilitato nelle impostazioni del flusso di lavoro.

---

## Test dell'integrazione

### Testa da GHL a <span data-t="appName">Your AI Connector</span> (Flusso di lavoro 1)

1. Invia un messaggio al tuo numero GHL o al canale collegato (ad esempio, inviati un SMS).
2. Apri <span data-t="appName">Your AI Connector</span> e verifica che il messaggio appaia in **Chat**.
3. Controlla che l'etichetta del canale sia corretta (SMS, email, ecc.).
4. Ripeti per ogni canale configurato.

### Testa da <span data-t="appName">Your AI Connector</span> a GHL (Flusso di lavoro 2)

1. In <span data-t="appName">Your AI Connector</span>, invia una risposta a un contatto (manualmente o lascia che l'IA risponda).
2. Apri GHL e verifica che il contatto abbia ricevuto il messaggio.
3. Conferma che sia stato inviato tramite il canale corretto.
4. Controlla che il contenuto del messaggio corrisponda.

---

## Risoluzione dei problemi

| Problema | Cosa controllare |
|---|---|
| I messaggi non raggiungono <span data-t="appName">Your AI Connector</span> | Verifica che la tua chiave API sia corretta nell'URL del webhook. Controlla che i trigger del workflow si stiano attivando (log del workflow GHL). Conferma che l'opzione Allow Re-entry sia abilitata. |
| I messaggi non raggiungono GHL | Verifica che l'URL del webhook in entrata di GHL sia incollato correttamente in **Webhook URL** nella scheda **Custom channel** in fondo a **Settings → Channels** (non nella pagina Settings → Integrations → Webhooks, che è una funzionalità diversa). Controlla che il webhook in entrata di GHL sia attivo. Esamina i log di esecuzione del workflow GHL. |
| Contatto non trovato in GHL | L'`toId` nei dati del webhook deve corrispondere a un ID contatto GHL esistente. Assicurati che i contatti esistano in entrambi i sistemi con ID corrispondenti. |
| Canale errato utilizzato per la risposta | Ricontrolla i valori del canale nei tuoi rami di condizione. Devono corrispondere esattamente: `email`, `sms`, `messenger`, `ig`, `livechat`. |
| Viene inoltrato solo il primo messaggio | Abilita **Allow Re-entry** nelle impostazioni di entrambi i workflow. |

---

## Prossimi passi

- [Webhook](webhooks.md) — configura i webhook per altri eventi <span data-t="appName">Your AI Connector</span>.
- [Accesso API](api-access.md) — utilizza l'API per integrazioni personalizzate oltre a GHL.
- [Canali personalizzati](../messaging-channels/custom-channels.md) — scopri di più sulla messaggistica tramite canali personalizzati.