Zapier e agente vocale AI: creare il lead e avviare la chiamata

Con Zapier un contatto nuovo, da qualunque strumento Zapier sappia leggere, diventa un lead in Aptiva e riceve la chiamata dell'agente vocale AI. Il caso tipico sono i moduli istantanei delle inserzioni di Meta: la persona invia il modulo su Facebook o Instagram, e l'agente la chiama appena il contatto arriva ad Aptiva. Quanto tempo passa prima che Zapier lo mandi dipende da Zapier e dal tuo piano.

Non esiste un'app di Aptiva su Zapier. Lo Zap chiama le API di Aptiva con l'azione Webhooks by Zapier, che invia una richiesta HTTP a un indirizzo esterno. Le richieste sono due: una crea il lead, una avvia la chiamata. Sono le stesse della guida sul webhook, che spiega il meccanismo per qualunque strumento.

Che cosa ti serve#

1. Un piano Zapier a pagamento: Webhooks by Zapier è un'app premium.
2. La chiave API di Aptiva, che leggi nel pannello: menu utente in basso a sinistra, voce «Mostra API Key».
3. L'ID dell'agente che farà la chiamata: è il numero accanto al suo nome nella pagina «Agenti», nella forma #42. L'agente deve essere in uscita, con un numero attivo.

Ingrandisci

Nel pannello, alla pagina Zapier delle integrazioni, c'è la stessa procedura con i valori pronti da copiare.

Lo Zap, passo per passo#

1. Il trigger: da dove arrivano i contatti#

Crea uno Zap e scegli il trigger. Per i moduli istantanei di Meta è l'app Facebook Lead Ads, con l'evento dei nuovi lead:

1. collega il tuo account Facebook;
2. scegli la pagina e il modulo;
3. fai una prova, così Zapier legge un lead d'esempio con i suoi campi.

Qualunque altro trigger va bene, purché dia almeno il numero di telefono: un CRM, un modulo, un foglio di calcolo.

2. Se serve, dividi nome e cognome#

Molti moduli danno il nome completo in un solo campo. Aptiva distingue name e lastName. Per dividerli aggiungi un passo Formatter, scegli «Text» e poi «Split Text», con lo spazio come separatore. Il primo pezzo è il nome, il resto il cognome. Il passo è facoltativo: puoi anche mandare il nome completo in name.

3. La richiesta che crea il lead#

Aggiungi un'azione Webhooks by Zapier con l'evento POST:

• URL: https://api.aptiva.cloud/external/api/leads/create;
• Payload Type: json;
• Data: una riga per campo, con a sinistra il nome di Aptiva e a destra il campo del trigger;
• Headers: una riga con X-API-Key a sinistra e la tua chiave a destra.

I nomi vanno scritti esattamente così, maiuscole comprese: Aptiva rifiuta i campi che non conosce. Fai la prova del passo: la risposta di Aptiva contiene id, l'identificativo del lead, che serve al passo successivo.

4. La richiesta che avvia la chiamata#

Aggiungi una seconda azione Webhooks by Zapier con l'evento POST. Puoi duplicare la precedente e cambiare ciò che serve:

• URL: https://api.aptiva.cloud/external/api/calls/start;
• Payload Type: json;
• Data: leadId, con l'id restituito dal passo 3, e agentId, con l'ID del tuo agente;
• Headers: la stessa riga X-API-Key.

Se la persona ha appena chiesto di essere chiamata, aggiungi in Data force con il valore true: la chiamata parte subito anche se il contatto era già stato chiamato. Senza, con l'impostazione predefinita dei richiami, un contatto già chiamato prende il posto successivo della cadenza. Per un contatto nuovo la chiamata parte subito in ogni caso.

5. La prova finale#

Prova il passo con un lead d'esempio che abbia il tuo numero di telefono, non quello di un cliente: la chiamata è vera. Il tuo telefono squilla, e nel pannello trovi il lead fra i contatti e la chiamata fra le chiamate. Poi pubblica lo Zap.

Con i moduli istantanei di Meta: l'identificativo del lead#

Se il trigger è un modulo istantaneo di Meta, conviene passare ad Aptiva anche l'identificativo del lead che Meta assegna a ogni invio. Aptiva lo conserva sul contatto e, se hai collegato Meta, lo rimanda a Meta negli eventi di fine chiamata: il contatto in target e l'appuntamento. Per Meta è il modo più diretto di riconoscere quel lead. Il giro completo è nella guida sui lead da Meta.

L'identificativo va in un campo annidato, leadMetadata.attribution.metaLeadId. Il modo più sicuro per scriverlo è l'azione Custom Request di Webhooks by Zapier, con il metodo POST, lo stesso indirizzo e lo stesso header, e il corpo JSON scritto per intero:

{
  "phone": "+393331234567",
  "name": "Mario",
  "lastName": "Rossi",
  "leadMetadata": {
    "attribution": {
      "form": "modulo-meta-preventivi",
      "metaLeadId": "1234567890123456"
    }
  }
}

Al posto dei valori d'esempio inserisci i campi del trigger. form è facoltativo: è un nome breve che scegli tu per riconoscere il modulo, in minuscolo, con lettere, cifre e trattini.

Attenzione ai campi vuoti. Se un campo del trigger è vuoto, lo Zap manda una stringa vuota. Per il telefono, l'email e i campi di attribution Aptiva rifiuta allora l'intera richiesta, e il lead non nasce; per name, lastName e leadCompanyName la stringa vuota è accettata. Metti nel corpo telefono, email e campi di attribution solo se il trigger li dà sempre. Le regole complete della voce attribution sono nella guida sui lead da Meta.

Se qualcosa non va#

La risposta di Aptiva dice che cosa non va nel campo code.

• invalid_api_key, stato 401: la chiave è incompleta, o l'header non si chiama esattamente X-API-Key.
• validation_error, stato 422: un nome di campo sbagliato, un campo in più, un'email vuota o un telefono non valido. Il dettaglio dice quale.
• AGENT_DISABLED o OUTBOUND_CONFIG_REQUIRED: l'agente è disattivato, oppure non è un agente in uscita.

Gli altri codici sono nella guida introduttiva alle API. Aptiva chiama i contatti che le indichi e presume che tu abbia il consenso di ciascuno: raccoglierlo spetta a te. Per i moduli di Meta, la guida sul consenso alle chiamate spiega dove mettere la casella.

Prossimi passi#

1. Collega Meta, se i contatti arrivano dalle inserzioni: la guida su Meta.
2. Rivedi i richiami che Aptiva fa da sola verso chi non risponde, nella guida su quante volte e quando Aptiva richiama un lead.
3. Per gli altri strumenti guarda la mappa delle integrazioni.