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, subito sotto la card del webhook, 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.

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.

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. Una nota: l'azione di avvio non trasporta consentProof — con la strict mode attiva, usa il webhook per i clienti che richiedono il consenso. (I custom fields del contatto e i valori già salvati da trigger webhook precedenti vengono applicati automaticamente.)

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.