Avvio di chiamate in uscita dell'Agente vocale IA tramite HubSpot

Questa guida illustra come configurare un Flusso di lavoro HubSpot che attiva automaticamente una chiamata in uscita di un Agente vocale IA. Per mostrare come funziona, utilizzeremo il seguente caso d'uso: attivare una chiamata sette giorni prima dell'appuntamento di un cliente. L'agente IA confermerà la partecipazione, risponderà alle domande di base sull'appuntamento e registrerà eventuali preferenze relative alla riprogrammazione o all'annullamento.

Come funziona

Indipendentemente dal caso d'uso, questo è il processo principale con cui viene attivata l'automazione:

Il record soddisfa i criteri di registrazione tramite il valore della proprietà HubSpot → viene registrato nel Flusso di lavoro → il Flusso di lavoro invia il payload di contesto all'Agente vocale IA → l'Agente vocale IA avvia una chiamata in uscita al record

Questa base può essere adattata praticamente a qualsiasi caso d'uso.

Concentrandoci sul caso d'uso del promemoria per gli appuntamenti, ecco un tipico Flusso delle chiamate dopo che il record è passato attraverso il Flusso di lavoro ed è stata attivata la chiamata:

• L'agente saluta il cliente per nome e conferma la data e l'ora dell'appuntamento.
• Chiede se desidera ancora procedere.
• Se SÌ: conferma gli eventuali dettagli pertinenti (luogo, persona che incontrerà) e conclude la chiamata.
• Se desidera RIPROGRAMMARE: l'agente chiede la nuova data preferita e comunica che qualcuno lo ricontatterà per confermarla.*
• Se desidera ANNULLARE: l'agente ne prende nota e comunica che il team lo contatterà.
• Se pone una domanda a cui l'agente non può rispondere: gli comunica che un membro del team lo richiamerà.

* NOTA:
Le azioni IA di HubSpot meetingAvailability e bookMeeting saranno disponibili prossimamente e consentiranno agli agenti di riprogrammare automaticamente le riunioni senza intervento umano.

Prerequisiti

Questa guida presuppone che siano già disponibili i seguenti elementi:

• Hai creato un Agente vocale IA per le chiamate in uscita configurato per il caso d'uso del promemoria per gli appuntamenti nel Dashboard di Aircall.
• Disponi di una proprietà del contatto HubSpot in cui è memorizzata la data dell'appuntamento.

Personalizzazione per il tuo caso d'uso 

Prima di iniziare, considera quanto segue:

• Campi obbligatori: il numero di telefono del contatto e la data dell'appuntamento sono i dati minimi necessari per attivare una chiamata. Tutti gli altri campi sono facoltativi: includi solo quelli effettivamente utilizzati dall'agente IA durante la conversazione.
• Campi facoltativi: puoi aggiungere o rimuovere campi di contesto (ad esempio luogo, rappresentante assegnato, tipo di appuntamento) in base alle informazioni necessarie all'agente per gestire efficacemente la chiamata.
• Intervallo di tempo: questo Flusso di lavoro si basa su promemoria inviati 7 giorni prima. Puoi modificare il numero di giorni in base alle tue esigenze operative. 
• Altri tipi di record: questa guida è basata sui record dei contatti HubSpot, ma lo stesso approccio può essere adattato ad altri oggetti: è sufficiente sostituire il tipo di record e le proprietà associate nell'attivatore del Flusso di lavoro e nell'azione del codice.
• Nomi delle proprietà: sostituisci ogni segnaposto come [your_appointment_date_property] con il nome interno effettivo della proprietà HubSpot utilizzata per memorizzare tali dati.

Passaggio 1: raccogli le credenziali

Lavorerai con due strumenti, HubSpot e Aircall, quindi prima di iniziare assicurati di avere accesso a entrambi e di aver effettuato l'accesso. Dovrai recuperare le seguenti credenziali dal Dashboard di Aircall: 

• ID dell'Agente vocale IA
• Token Basic Auth 

Dovrai incollarle nel codice del passaggio 2; averle a portata di mano prima di iniziare la configurazione ti farà risparmiare tempo. 

Il tuo Agente vocale IA dispone di un URL Webhook univoco che funge da identificatore. Puoi copiarlo dal Dashboard di Aircall e utilizzarlo nel tuo Flusso di lavoro. 

Vai a Agente vocale IA → Flusso di lavoro per chiamate in uscita → URL Webhook → Copia

Il token Basic Auth viene utilizzato per autenticare le richieste inviate da HubSpot all'API di Aircall, verificando che la chiamata sia stata attivata dal tuo Flusso di lavoro. Viene generato a partire dall'ID API e dal token API di Aircall, disponibili nel Dashboard di Aircall andando su Integrazioni → Chiavi API. 

Una volta ottenuti entrambi i valori, combinali nel formato API_ID:API_TOKEN e codifica il risultato in Base64. Questa stringa codificata è il tuo token Basic Auth.

Passaggio 2: crea un'azione di codice personalizzato in HubSpot

In HubSpot, vai su Automazione > Flussi di lavoro e crea un nuovo Flusso di lavoro basato sui contatti. Assegnagli un nome descrittivo, ad esempio Promemoria appuntamento — Chiamata in uscita Aircall.

Imposta l'attivatore di registrazione

Utilizza un attivatore basato sulla pianificazione e collegato alla proprietà della data dell'appuntamento:

L'attivatore basato sulla data determina quando viene avviata la chiamata, ma non eseguirà alcuna azione se i contatti non sono effettivamente registrati nel Flusso di lavoro. L'approccio più semplice e applicabile a tutti i casi consiste nel registrare i contatti quando la data dell'appuntamento diventa nota, ovvero quando la proprietà passa da vuota a valorizzata.

Per configurarlo, aggiungi una condizione all'attivatore di registrazione: 

Proprietà del contatto → [proprietà della data dell'appuntamento] → è nota. 

In questo modo, ogni volta che viene impostata una data dell'appuntamento per un contatto, indipendentemente da come sia stata aggiunta, il contatto verrà registrato e il Flusso di lavoro gestirà il resto quando mancheranno 7 giorni alla data dell'appuntamento memorizzata nella proprietà.

Lascia attiva la nuova registrazione. Se un contatto riprogramma l'appuntamento e la relativa data viene aggiornata, verrà registrato nuovamente e riceverà una chiamata di promemoria per la nuova data, come previsto.

Fai clic su Salva. L'attivatore è ora configurato.

Aggiungere un'azione con codice personalizzato 

All'interno del Flusso di lavoro, aggiungi un'azione e seleziona Codice personalizzato. Scegli Node.js 18.x come linguaggio.

In «Proprietà da includere nel codice», aggiungi le proprietà di HubSpot che desideri trasmettere all'Agente vocale IA. La tabella seguente mostra i campi consigliati, a cosa corrispondono nel codice e quale proprietà utilizzare:

Aggiungi o rimuovi righe in base al contesto necessario al tuo agente IA. Includi solo i campi a cui l'agente farà effettivamente riferimento durante la chiamata.

Incollare il codice

Sostituisci il codice predefinito con quello seguente. 

Nota: 

• Le righe event.inputFields nel codice devono corrispondere ai campi di input appena configurati sopra in «Proprietà da includere nel codice». Assicurati che corrispondano anche alle righe del payload di contesto presenti più avanti nel codice.
• Aggiorna il segnaposto basicAuth con il tuo token Basic Auth 
• Aggiorna il segnaposto dell'URL dell'agente con l'ID del tuo agente/l'URL del Webhook

const axios = require('axios');

exports.main = async (event, callback) => {
  const firstname       = event.inputFields['firstname'];
  const lastname        = event.inputFields['lastname'];
  const phone           = event.inputFields['phone'];
  const appt_date       = event.inputFields['appointment_date'];
  const appt_time       = event.inputFields['appointment_time'];
  const appt_address    = event.inputFields['appointment_address'];
  const legal_rep       = event.inputFields['legal_representative'];
  
  const basicAuth = 'YOUR_AIRCALL_BASIC_AUTH_TOKEN';
  const agentUrl  = 'https://api.aircall.io/v1/outbound-calls/agents/YOUR_AGENT_ID';
  try {
    const response = await axios.post(
      agentUrl,
      {
        contact_phone: phone,
        idempotency_key: `appt-reminder-${event.object.objectId}`,
        context: {
          first_name:           firstname,
          last_name:            lastname,
          appointment_date:     appt_date,
          appointment_time:     appt_time,
          appointment_address:  appt_address,
          legal_representative: legal_rep
        },
        expiration_seconds: 3600
      },
      {
        headers: {
          Authorization: `Basic ${basicAuth}`,
          'Content-Type': 'application/json'
        }
      }
    );
    callback({ outputFields: { status: response.status, message: 'Call triggered' } });
  } catch (error) {
    const status = error.response?.status || 500;
    const body   = JSON.stringify(error.response?.data) || 'No response';
    callback({ outputFields: { status, message: `${error.message} | ${body}` } });
  }
};

Importante: L'agente utilizzerà solo ciò che viene trasmesso nel payload di contesto. Se un campo è assente o vuoto, non vi farà riferimento. Non trasmettere mai un campo con dati segnaposto o di prova in un Flusso di lavoro attivo.

La configurazione del Flusso di lavoro è ora completa.

Passaggio 3: eseguire un test prima dell'attivazione

Prima di abilitare il Flusso di lavoro per tutti i contatti, segui questi passaggi:

• Iscrivi un contatto di prova interno con un numero di cellulare reale e una data fittizia dell'appuntamento impostata per domani.
• Attiva manualmente il Flusso di lavoro utilizzando l'azione Test in HubSpot.
• Ascolta la chiamata e verifica che l'agente legga il nome, la data, l'ora e tutti gli altri campi inclusi correttamente.
• Verifica il percorso di riprogrammazione rispondendo che desideri cambiare la data.

Quando il comportamento corrisponde alle aspettative, puoi attivare il Flusso di lavoro.

Suggerimento: Utilizza la visualizzazione della cronologia dei Flussi di lavoro di HubSpot per verificare se ogni azione del codice è riuscita o meno e quale codice di stato ha restituito Aircall. Lo stato 200 indica che la chiamata è stata attivata correttamente.