Collega il workflow del CRM a un agente (URL e segreto webhook)

Ogni agente AI in GodSetter ha il proprio URL webhook. È il workflow che punta a quell'URL a decidere quale agente effettua la chiamata — così uno stesso cliente può far girare agenti diversi per campagne diverse semplicemente usando URL diversi.

Questa guida collega un workflow del CRM (per esempio "nuovo lead creato") a un agente, in modo che ogni lead elaborato dal workflow venga chiamato nel giro di pochi secondi: la prima chiamata parte nel momento in cui il lead arriva.

Prima di iniziare

• Il tuo CRM è collegato in Connessioni (OAuth) e il sub-account del cliente è stato importato (compare in Clienti come attivo). Serve un posto dove prenotare: un calendario proprio, oppure un calendario predefinito sull'agente (Identità e routing), cercato per nome nel sub-account del cliente.
• L'agente esiste e ha almeno un numero attivo assegnato (editor agente → tab Numeri). Il comportamento è fail-closed: un agente senza numeri non chiama mai.
• L'agente bersaglio è in uscita. Un agente in entrata risponde alle richiamate ma non può mai iniziare un ciclo di chiamate: puntargli un workflow produce una risposta skipped con reason inbound_agent. Controlli la direzione nel tab Identità e routing dell'agente — vedi Crea gli agenti in uscita e in entrata della tua nicchia.

Passo 1 — Copia URL e segreto webhook dell'agente

Apri l'agente in Agenti, poi il tab Dati & GHL. Nella card Webhook trigger (questo agente) trovi:

• l'URL webhook dell'agente (…/api/webhooks/ghl-trigger/agent/<agent-id>),
• il segreto dell'agente (campo webhookSecret nel body),
• un esempio di body (JSON),

ciascuno con il proprio pulsante di copia. Il segreto è unico per agente: trattalo come una password.

Passo 2 — Aggiungi l'azione webhook al workflow

Nel sub-account del cliente, modifica il workflow che deve far partire le chiamate (per esempio su "Contact created" o al cambio di stage della pipeline) e aggiungi un'azione Webhook:

• Method: POST
• URL: l'URL dell'agente che hai copiato
• Header: Content-Type: application/json

Passo 3 — Costruisci il body JSON

Campi minimi obbligatori:

{
  "webhookSecret": "<the copied per-agent secret>",
  "locationId": "{{location.id}}",
  "contactId": "{{contact.id}}",
  "phone": "{{contact.phone}}"
}

Aggiunte consigliate:

Il campo timezone viene salvato sul lead e riutilizzato anche sui richiami successivi. Se manca — o se non è un identificatore IANA valido — si applica la catena di ripiego: fuso del sub-account, poi fuso di riserva dell'agente. Dettagli in Imposta una fascia oraria per agente.

Passo 4 — Invia un lead di prova

La verifica più rapida è nell'app. Nello stesso tab Dati & GHL, sotto la card del webhook e la card Tag di avvio, la card Invia un lead di prova simula un lead che arriva dal workflow: scegli il cliente (sono elencati solo i clienti attivi con un posto dove prenotare — il proprio calendario o il predefinito dell'agente), inserisci un numero che controlli e premi Invia lead di prova. Il lead passa dallo stesso ingresso dei webhook — gate di direzione, cliente, numero, consenso e Do-Not-Call — e poi dal dispatch immediato: se tutto è collegato, l'agente ti chiama entro pochi secondi. È una chiamata reale (costo reale) su un lead reale, che resta in Chiamate e Lead come tutti gli altri. Il calendario è quello reale del cliente; prenotazione, tag e note sono simulati: nel CRM non resta nulla. La card mostra una traccia in tre righe (e siccome il lead è reale, una prova a cui non rispondi viene richiamata dal piano richiami dell'agente: aspettati altre chiamate vere al tuo numero, a meno che tu non blocchi il lead dalla pagina Lead):

• Ingresso — lead accettato, oppure saltato con il motivo (gli stessi della tabella qui sotto);
• Dispatch — chiamata partita, in coda in testa (slot tutti occupati), parcheggiata all'apertura della fascia (fuori dalla fascia oraria), oppure non partita con il motivo;
• Apri il lead — il lead creato dalla prova.

Se il prompt attivo dell'agente cita dei custom values (token {{cv_*}}), la card mostra anche una sezione Custom values del prompt con un campo per ogni token. Compila ciò che il workflow manderebbe per quel contatto: i valori arrivano al lead di prova esattamente come i customValues di un trigger vero, così la chiamata parla con gli stessi dati. Un campo vuoto non viene inviato e il token resta vuoto, a meno che il sub-account del cliente non abbia un custom value con quel nome.

Poi fai la verifica vera dal CRM: lancia il workflow con un contatto di test (usa un numero che controlli). Risposta attesa:

{ "status": "enqueued", "leadId": "…" }

Dentro la fascia oraria la chiamata parte entro pochi secondi; fuori, il lead aspetta l'apertura. Controlla Chiamate per vedere la riga in tempo reale.

Se la risposta dice skipped

Il campo reason ti dice quale gate di attivazione ha fermato la chiamata:

Un trigger duplicato — lo stesso contatto scattato due volte entro 10 minuti — ha una sua risposta dedicata, {"status":"duplicate"}, e viene semplicemente ignorato: è il dedup integrato che funziona come previsto.

Tre di questi scarti vengono anche taggati nel tuo CRM — no_number, no_consent e blocked (nomi configurabili in Impostazioni → Tag CRM) — così i tuoi workflow possono reagire. Gli altri tre (client_inactive_or_not_found, not_configured e inbound_agent) sono errori di configurazione dalla tua parte: vengono riportati nella risposta e sul lead, ma nel CRM non viene scritto nulla.

Passo 5 — Ferma il ciclo quando il contatto prenota da solo

Una prenotazione fatta durante una chiamata ferma già il ciclo automaticamente. Ma un contatto può prenotare anche fuori da qualsiasi chiamata — dal link del funnel, o con un operatore umano. Avvisa GodSetter, così i richiami schedulati non chiamano mai qualcuno che ha già prenotato:

1. Nel sub-account del cliente crea un secondo workflow sul trigger nativo del CRM «Customer booked appointment».
2. Aggiungi un'azione Webhook che punta all'URL «Appuntamento prenotato (stop chiamate)» mostrato nella pagina Connessioni (la pagina mostra anche il segreto webhook dell'agenzia e un body di esempio pronto da incollare).
3. Campi del body: webhookSecret (il segreto agenzia da Connessioni), locationId, contactId e facoltativamente phone.

Se va a buon fine la risposta è {"status":"stopped"}: il lead viene segnato come prenotato e ogni suo richiamo/callback schedulato viene rimosso. Una risposta not_found è benigna — quel contatto semplicemente non era in un ciclo di chiamate.

Gli altri URL della pagina Connessioni

La card Webhook in entrata della pagina Connessioni elenca cinque URL, e solo due sono da incollare in GoHighLevel:

• Trigger chiamata — il trigger a livello di agenzia (l'URL legacy; quello per-agente del Passo 1 è la configurazione consigliata).
• Appuntamento prenotato (stop chiamate) — il Passo 5 qui sopra.

Gli altri tre — Inbound voice, Call lifecycle e Strumenti in-call — sono webhook di Retell, e li configura GodSetter per te: gli URL di call lifecycle e strumenti in-call vengono impostati sull'agente al momento della creazione (e riconfermati da «Sincronizza strumenti GHL»), mentre l'URL inbound voice viene impostato sul numero quando lo registri su Retell. Non c'è nulla da incollare: sono mostrati come riferimento, per esempio per controllare su quale host puntano agenti e numeri. Il Secret webhook vale solo per i due webhook di GoHighLevel.

Rigenerare il segreto

Rigenera un segreto quando potrebbe averlo visto qualcuno che non dovrebbe più averlo — un ex membro del team, uno screenshot condiviso, un workflow copiato in un altro account. Il vecchio segreto smette subito di funzionare, e solo per quell'agente o per la tua agenzia: il resto non cambia.

• Il segreto di un agente — nel tab Dati & GHL dell'agente, Rigenera il segreto sotto il segreto. Autentica l'URL webhook di quell'agente.
• Il segreto dell'agenzia — nella pagina Connessioni, Rigenera il segreto sotto il Secret webhook. Autentica i due URL dell'agenzia: Trigger chiamata e Appuntamento prenotato (stop chiamate).

Il pulsante lo vede solo il titolare dell'account — non i membri del team né il supporto GodSetter — e chiede prima conferma: i workflow GoHighLevel che usano il segreto attuale smettono di funzionare finché non incolli quello nuovo. Da quel momento ricevono 401 (invalid secret) e nessun lead viene chiamato. Poi:

1. Copia il nuovo segreto: la pagina lo mostra subito.
2. In ogni workflow che chiama quell'URL apri l'azione Webhook e sostituisci il valore di webhookSecret nel body (Passi 3 e 5).
3. Manda una prova (Passo 4) e controlla che la risposta torni enqueued.

Gli URL non cambiano, e nemmeno l'Agent ID e l'Account ID: le azioni workflow brandizzate e il tag di avvio non usano il segreto e continuano a funzionare. Ogni rigenerazione resta nel registro Audit come webhook.secret.rotate — mai il segreto.

Preferisci le azioni workflow brandizzate

Se l'app marketplace di GodSetter è installata sul sub-account, entrambi i passi sono disponibili come azioni workflow native — niente URL o JSON da incollare. Servono l'app installata su quel sub-account e la fatturazione "Workflow LC Premium Triggers & Actions" attiva: senza entrambe le cose i nodi brandizzati non compaiono nel workflow builder e resta il webhook generico.

• Avvia ciclo di chiamate — scegli l'azione e incolla l'ID agente (lo copi dal tab Dati & GHL dell'agente). Telefono, nome, fuso orario e custom fields del contatto vengono recuperati automaticamente — ogni token {{cv_contact_*}} nel prompt si risolve senza alcuna mappatura.
• Appuntamento prenotato (stop chiamate) — scegli l'azione e incolla il tuo ID account (lo copi dalla pagina Connessioni).

Il webhook generico resta pienamente supportato; le azioni fanno la stessa cosa con meno configurazione. Anche il consenso funziona allo stesso modo: l'azione di avvio ha un campo facoltativo Consent proof (prova di consenso) — incolla lo stesso oggetto che il webhook invia come consentProof, per esempio {"formId": "…", "submittedAt": "…"}, mappando i valori del tuo modulo di opt-in. Con la strict mode attiva, un campo vuoto o non valido fa saltare il lead con no_consent. (I custom fields del contatto e i valori già salvati da trigger webhook precedenti vengono applicati automaticamente.)

Nessun workflow: il tag di avvio

Non vuoi toccare i workflow? Dai all'agente un tag di avvio: nel tab Dati & GHL dell'agente compila Tag di avvio (es. chiama-con-ai) e salva. Da quel momento, aggiungere quel tag a un contatto nel CRM avvia il ciclo di chiamate di questo agente per quel contatto — è lo speculare del tag di disconnessione. Serve l'app marketplace di GodSetter installata (è così che GodSetter viene a sapere dei cambi di tag) e il sub-account del contatto importato come cliente.

• Valgono tutti i controlli visti sopra: un agente inbound o disattivato, un cliente senza dove prenotare, nessun numero, consenso mancante in strict mode o un lead in Do-Not-Call significano nessuna chiamata.
• Un tag, un agente: due agenti della stessa agenzia non possono condividere il tag di avvio, e non si possono usare il tag di disconnessione né un tag che GodSetter scrive da sé.
• Il tag avvia il ciclo una volta finché resta sul contatto, per quante volte cambino gli altri suoi tag (compresi quelli di esito che scrive GodSetter). Per ripartire, togli il tag e rimettilo.
• Non parte nulla se il contatto ha anche il tag di disconnessione (il contatto viene invece tolto da GodSetter) o se il ciclo del lead si è già chiuso con appuntamento fissato o non interessato.
• A differenza del webhook e dell'azione di avvio, il tag non trasporta prova di consenso né custom values: con la strict mode attiva, per i clienti che richiedono il consenso usa uno di quei due (col tag il lead verrebbe saltato come no_consent).

Ricontattare un lead già passato dal workflow

Un workflow che parte su "Tag aggiunto al contatto" non riparte se togli il tag e lo rimetti nel giro di pochi secondi: GoHighLevel lo considera lo stesso evento e lo scarta, quindi non parte nessuna nuova chiamata. Per richiamare quel contatto:

• attendi qualche minuto — finché il workflow non mostra concluso il passaggio precedente del contatto — poi togli il tag e rimettilo; oppure
• usa un tag dedicato al ricontatto (per esempio richiama) con un workflow suo e la stessa azione webhook, così il nuovo trigger non si confonde mai con il primo.

In entrambi i casi il nuovo trigger fa ripartire il ciclo di chiamate (vedi sotto).

Buono a sapersi

• Un URL per agente. Per instradare una campagna su un agente diverso, duplica il workflow e sostituisci URL + segreto — nessuna modifica lato GodSetter.
• Un nuovo trigger fa ripartire il ciclo. Lanciare di nuovo il workflow su un contatto che GodSetter conosce già azzera il contatore dei tentativi e scarta i richiami ancora parcheggiati per quel lead: il piano riparte dalla chiamata #1 invece di riprendere a metà. Una richiamata chiesta esplicitamente dal lead viene mantenuta.
• Il webhook legacy a livello di agenzia (senza /agent/) funziona ancora e usa l'agente di default del cliente, ma la configurazione consigliata è l'URL per-agente — e risponde {"status":"skipped","reason":"no_template"} quando il cliente non ha un agente di default. Quel default è il campo Agent Template nella scheda del cliente (Gestisci i tuoi clienti).
• Se il workflow scatta mentre la fascia oraria chiamate è chiusa, il lead resta in coda e viene chiamato alla riapertura della fascia.