Webhook e agente vocale AI: la chiamata da qualsiasi strumento

Un webhook è una richiesta HTTP che uno strumento invia da solo a un indirizzo quando succede qualcosa, per esempio quando una persona invia un modulo. Qualunque strumento capace di inviarla può far partire la chiamata dell'agente vocale AI di Aptiva: uno strumento di automazione come Make o n8n, le automazioni di un CRM, il tuo server.

Le richieste sono due. La prima crea il contatto in Aptiva e restituisce il suo identificativo. La seconda avvia la chiamata verso quel contatto. Questa guida spiega che cosa deve saper fare lo strumento e come configurare le due richieste. Per Zapier, Wix e Typeform ci sono guide dedicate.

Che cosa deve saper fare lo strumento#

Lo strumento deve saper fare tre cose. Se ne manca una, serve uno strumento intermedio.

1. Inviare un corpo JSON scritto da te, con i nomi dei campi che Aptiva vuole: phone, name, email e così via.
2. Aggiungere un header con la chiave API. Se non può, c'è una strada di riserva, descritta più sotto.
3. Usare la risposta della prima richiesta nella seconda: l'identificativo del contatto creato serve per avviare la chiamata.

Il primo punto esclude il webhook nativo di molti moduli. Quel webhook invia i campi con i nomi scelti dal modulo, e Aptiva rifiuta i campi che non conosce, con un errore 422. È una scelta voluta: un refuso si scopre alla prima prova, non dopo una settimana di dati persi. Per quei moduli, il webhook del modulo va verso lo strumento intermedio, e lo strumento intermedio chiama Aptiva.

Lo strumento deve stare su un server, non nel browser dei visitatori: la chiave API dà pieno accesso ai dati della tua azienda, e una pagina web la renderebbe pubblica.

Prima di cominciare: chiave API e ID dell'agente#

Servono due valori, che leggi dal pannello di Aptiva.

• La chiave API si legge nel menu utente in basso a sinistra, alla voce «Mostra API Key», ogni volta che serve. Trattala come una password di amministratore.
• L'ID dell'agente che farà la chiamata è il numero accanto al suo nome, nella forma #43, nella pagina «Agenti». L'agente deve essere in uscita, con un numero attivo.

Ingrandisci

Ingrandisci

Prima richiesta: creare il contatto#

La prima richiesta crea il contatto, o lo aggiorna se il numero di telefono esiste già. Si configura così:

• metodo: POST;
• indirizzo: https://api.aptiva.cloud/external/api/leads/create;
• header: X-API-Key con la tua chiave, e Content-Type con il valore application/json;
• corpo: un JSON con i dati del contatto.

{
  "phone": "+393331234567",
  "name": "Mario",
  "lastName": "Rossi",
  "email": "mario.rossi@example.com",
  "leadCompanyName": "Rossi Srl"
}

Solo phone è obbligatorio. Un numero senza prefisso internazionale è letto come italiano. Nello strumento, al posto dei valori d'esempio, metti i campi del modulo. Un campo email vuoto è rifiutato: se nel modulo l'email è facoltativa, lascia fuori email quando manca.

La risposta ha stato 201 e un corpo come {"id": 1285}. Quel numero è l'identificativo del contatto, e lo strumento deve salvarlo per la seconda richiesta.

Puoi aggiungere additionalInfo, un oggetto con ciò che la persona ha scritto, per esempio {"richiesta": "Preventivo per un impianto"}. L'agente lo riceve all'inizio della chiamata, e apre la conversazione sapendo di che cosa parlare. I dettagli sono nella guida API su lead e chiamate.

Se il contatto arriva da un annuncio Meta, puoi aggiungere anche i dati del clic, nella voce leadMetadata.attribution: Aptiva li rimanda a Meta dopo la chiamata, se hai collegato Meta. Un campo vuoto o sconosciuto fa rifiutare l'intera richiesta: le regole e un esempio sono nella guida sui lead da Meta.

Seconda richiesta: avviare la chiamata#

La seconda richiesta fa partire la chiamata dell'agente verso il contatto appena creato:

• metodo: POST;
• indirizzo: https://api.aptiva.cloud/external/api/calls/start;
• header: gli stessi della prima richiesta;
• corpo: l'identificativo del contatto, preso dalla risposta della prima richiesta, e quello dell'agente.

{
  "leadId": 1285,
  "agentId": 43
}

La risposta ha stato 204, senza corpo: Aptiva ha accettato la richiesta. Per un contatto nuovo la chiamata parte subito.

Per un contatto già chiamato, con l'impostazione predefinita dei richiami, vale la cadenza: la richiesta prende il posto successivo della sequenza, e oltre la quinta chiamata viene rifiutata. Se la persona ha appena chiesto di essere chiamata, aggiungi "force": true e la chiamata parte comunque subito. La regola completa è nella guida API su lead e chiamate.

Se lo strumento non sa impostare un header#

Alcuni strumenti non permettono di aggiungere header, per esempio le automazioni di Wix. Per loro Aptiva accetta la chiave anche nell'indirizzo, nel parametro api_key:

https://api.aptiva.cloud/external/api/leads/create?api_key=<LA_TUA_CHIAVE>

Funziona per le due richieste di questa guida. Se nella stessa richiesta ci sono sia l'header sia il parametro, vale l'header. Aptiva nasconde il valore del parametro nei propri registri, ma un indirizzo può restare scritto nei registri degli altri sistemi che la richiesta attraversa, compreso lo strumento stesso. Per questo l'header resta la strada da preferire.

Il parametro non vale per le richieste che leggono elenchi, come GET /leads e GET /calls: lì un parametro in più fa rifiutare la richiesta con 422.

Provare il collegamento#

Prova con un tuo numero di telefono, non con quello di un cliente: la chiamata è vera.

1. Invia il modulo, o fai partire lo strumento, con il tuo numero.
2. Controlla la prima risposta: stato 201 e un id.
3. Controlla la seconda: stato 204.
4. Il tuo telefono squilla, e nel pannello trovi il contatto fra i contatti e la chiamata fra le chiamate.

Se una richiesta fallisce, la risposta contiene un codice nel campo code. I casi più comuni:

Gli altri codici sono nella guida introduttiva alle API.

Dopo la chiamata#

A fine chiamata Aptiva invia un'email di riepilogo con i dati del contatto, il riassunto della conversazione e la trascrizione, quando c'è. Oggi Aptiva non invia richieste a un indirizzo del tuo sistema quando una chiamata finisce. Se ti serve l'esito nel CRM, lo strumento può leggerlo con le API, con GET /calls, come descrive la guida API su lead e chiamate.

Prossimi passi#

1. Scegli lo strumento: se usi Zapier o Wix, segui le guide dedicate a Zapier e a Wix.
2. Se scrivi codice, la guida introduttiva alle API spiega chiave, convenzioni ed errori.
3. Rileggi il giro completo della lead generation telefonica, dalla chiamata immediata ai richiami.