Passa al contenuto principale
DocumentationAPI ReferenceVideo Tutorials

Integrazioni

Le integrazioni estendono i tuoi agenti vocali IA collegandoli a servizi esterni. Questa sezione copre tutte le integrazioni disponibili e come configurarle.

Integrazioni disponibili​

IntegrazioneScopoStatoPiani
Numeri di telefonoNumeri di telefono e chiamateDisponibileTutti
SIP TrunkPorta il tuo carrier (sipgate, Placetel, TENIOS, easybell, Zadarma, Twilio BYO, Telnyx, Custom)DisponibileTutti — richiede approvazione di conformità
Google CalendarPianificazione appuntamenti tramite GoogleDisponibileTutti
Outlook CalendarPianificazione appuntamenti tramite Microsoft OutlookDisponibileTutti
HubSpot CRMLeggi/scrivi contatti e deal dal tuo agente vocale IADisponibileTutti
Server MCPPorta il tuo server di strumenti compatibile MCP ed esponi i suoi strumenti agli agenti — vedi Server MCPDisponibileTutti
Chiavi APIAccesso applicazioni esterneDisponibileTutti
WebhookNotifiche eventi in tempo realeDisponibileTutti
Tutti i piani

Integrazioni calendario, SIP, HubSpot, server MCP, accesso API e webhook sono disponibili su tutti i piani, incluso Free. Il SIP trunking richiede un'approvazione di conformità una tantum prima che il wizard di connessione si sblocchi.

Configurazione del numero di telefono​

I numeri di telefono permettono ai tuoi agenti di ricevere ed effettuare vere chiamate telefoniche.

Passaggi di setup​

  1. Vai su Numeri di telefono nella barra laterale
  2. Clicca su "Acquista numero"
  3. Seleziona paese e tipo di numero
  4. Completa l'acquisto
  5. Assegna un agente al numero

I numeri sono automaticamente configurati e pronti all'uso dopo l'acquisto.

Integrazione SIP Trunk​

Porta il tuo carrier SIP — HANC parla SIP nativamente e instrada le chiamate in entrata nel tuo agente vocale IA (e le chiamate in uscita di nuovo attraverso il tuo trunk). Disponibile su tutti i piani incluso Free dopo un'approvazione di conformità una tantum.

Carrier supportati​

HANC ha adattatori ottimizzati per i seguenti carrier, più un'opzione generica per qualsiasi altro:

CarrierImportazione automatica numeri tramite APINote
sipgateSì (Personal Access Token)SIP trunking UE
PlacetelManualeVoIP tedesco, credenziali Webportal
TENIOSManualeSIP europeo
easybellManualeCarrier tedesco, credenziali Kundencenter
ZadarmaSì (chiave API opzionale)Numeri globali
Twilio (BYO)SìAccount SID + Auth Token
TelnyxSìSIP e DID guidati da API
SIP trunk personalizzatoManualeQualsiasi altro provider — fornisci host, porta, trasporto

Approvazione di conformità​

Le connessioni dei carrier SIP condividono lo stesso flusso di conformità delle campagne in uscita. Fino a quando il tuo account non è approvato, il pulsante Connetti SIP apre una finestra modale vetrina che elenca tutti i carrier supportati con una CTA mailto:support@hanc.ai. L'approvazione è di solito nello stesso giorno lavorativo.

Passaggi di setup (dopo l'approvazione)​

  1. Vai su Numeri di telefono → Connetti SIP.
  2. Scegli il tuo carrier.
  3. Inserisci le credenziali SIP (e la chiave/segreto API opzionale se il tuo carrier supporta l'importazione automatica).
  4. Per SIP personalizzato, fornisci anche host, porta (predefinita 5060) e trasporto (UDP / TCP / TLS).
  5. Clicca su Connetti — HANC registra il tuo utente SIP e, dove supportato, elenca i tuoi numeri di telefono.
  6. Seleziona i numeri da importare (o aggiungili manualmente per E.164).
  7. Assegna un agente in entrata e/o in uscita su ciascun numero.

Quando usare SIP vs. acquistare un numero​

ScenarioRaccomandazione
Nuovo al servizio telefonicoAcquista numeri tramite HANC (più semplice — nessun passaggio di conformità)
PBX o contratto carrier esistenteConnetti tramite SIP — mantieni il tuo numero
Telefonia enterprise con requisiti carrier rigorosiSIP per il pieno controllo
Più regioni / pool di numeriSIP per flessibilità

Integrazione Google Calendar​

Collega Google Calendar per consentire ai tuoi agenti vocali IA di verificare la disponibilità e prenotare appuntamenti durante le chiamate.

Passaggi di setup​

  1. Vai su Integrazione → Calendari
  2. Clicca su "Connetti Google Calendar"
  3. Accedi con Google
  4. Autorizza l'accesso di Hanc.AI

Permessi richiesti:

  • Visualizza eventi del calendario (per verificare la disponibilità)
  • Crea eventi del calendario (per prenotare appuntamenti)

Configurazione del calendario​

Dopo la connessione, configura lo strumento del calendario sul tuo agente:

ImpostazioneDescrizione
calendar_idQuale Google Calendar usare per la pianificazione
timezoneFuso orario per la pianificazione degli appuntamenti (es. Europe/Vienna)
work_hoursOrari disponibili per la prenotazione (es. Lunedì-Venerdì 9:00-18:00)
slot_durationDurata predefinita dell'appuntamento (es. 30 minuti)
bufferTempo buffer tra appuntamenti (es. 15 minuti)

Uso del calendario negli agenti​

Una volta connesso e configurato, gli agenti possono:

  • Verificare la disponibilità per date e orari specifici
  • Prenotare appuntamenti automaticamente
  • Rispettare gli orari di lavoro e i tempi buffer
  • Gestire richieste di riprogrammazione

Conversazione di esempio:

Cliente: "Posso prenotare un appuntamento per martedì alle 15?"

Agente: [Verifica calendario]
       "Sì, martedì alle 15 è disponibile.
        Posso avere il suo nome per completare la prenotazione?"

Integrazione Outlook Calendar​

Collega Microsoft Outlook Calendar per abilitare la pianificazione di appuntamenti tramite i tuoi agenti vocali IA.

Passaggi di setup​

  1. Vai su Integrazione → Calendari
  2. Clicca su "Connetti Outlook Calendar"
  3. Accedi con il tuo account Microsoft
  4. Autorizza l'accesso di Hanc.AI

Permessi richiesti:

  • Visualizza eventi del calendario (per verificare la disponibilità)
  • Crea eventi del calendario (per prenotare appuntamenti)

Configurazione del calendario​

Dopo la connessione, configura lo strumento del calendario sul tuo agente:

ImpostazioneDescrizione
CalendarioQuale calendario Outlook usare per la pianificazione
Fuso orarioFuso orario per la pianificazione degli appuntamenti (es. Europe/Vienna)
Orari di lavoroOrari disponibili per la prenotazione (es. Lunedì-Venerdì 9:00-18:00)
Durata slotDurata predefinita dell'appuntamento (es. 30 minuti)
BufferTempo buffer tra appuntamenti (es. 15 minuti)

Differenze rispetto a Google Calendar​

Entrambe le integrazioni del calendario funzionano in modo identico dal punto di vista dell'agente. L'unica differenza è il processo di accesso — scegli il servizio di calendario che già usi.

suggerimento

Puoi connettere sia i calendari Google che Outlook contemporaneamente, ma ogni agente può usare solo uno strumento del calendario.

Cancellazione degli appuntamenti​

I chiamanti che hanno prenotato un appuntamento ricevono un link di cancellazione. Possono cancellare il loro appuntamento direttamente senza dover richiamare.

Integrazione HubSpot CRM​

Connetti il tuo workspace HubSpot così i tuoi agenti vocali IA possono leggere e scrivere contatti e deal durante la chiamata, e così il CRM integrato di HANC può rispecchiare le tue pipeline HubSpot.

Cosa abilita​

  • Strumento live — HubSpot CRM nella scheda Azioni dell'agente. L'agente può abbinare il chiamante a un contatto HubSpot per telefono, recuperare lo stage del deal e aggiornare le proprietà dalla conversazione live. Vedi Azioni e strumenti.
  • Mirroring della pipeline nel CRM di HANC. Gli stage dei tuoi deal HubSpot appaiono nel kanban Deal così puoi vedere chiamate e contesto HubSpot fianco a fianco.
  • Toggle IA per pipeline — decidi su quali pipeline HubSpot l'IA è autorizzata ad agire; tutto il resto rimane in sola lettura.

Passaggi di setup​

  1. Apri la pagina Integrazioni e clicca su Connetti HubSpot.
  2. Autorizza HANC nel tuo account HubSpot.
  3. Scegli quali pipeline devono essere rispecchiate (visibili sotto le impostazioni CRM → Pipeline) e quali devono consentire gli aggiornamenti di stage dell'agente.
  4. Aggiungi lo strumento HubSpot CRM a qualsiasi agente che dovrebbe toccare HubSpot durante la chiamata.
suggerimento

Non devi usare HubSpot per usare il CRM di HANC. Il CRM integrato funziona in modo autonomo — l'integrazione HubSpot è puramente per le organizzazioni che già vivono in HubSpot e vogliono entrambi i mondi sincronizzati.

Server MCP​

Il Model Context Protocol (MCP) è uno standard aperto per connettere assistenti IA a strumenti esterni. Se gestisci un server compatibile MCP, puoi registrarlo una volta sulla pagina Integrazione e far chiamare ai tuoi agenti i suoi strumenti a metà conversazione.

Passaggi di setup (panoramica)​

  1. Vai su Integrazione → Server MCP.
  2. Clicca su Connetti server MCP, inserisci un'etichetta e l'URL HTTPS del tuo server, scegli l'autenticazione (Nessuna o token Bearer) e salva.
  3. Apri l'agente che vuoi che usi gli strumenti, vai su Azioni → Aggiungi azione → Server MCP, e attiva le connessioni che questo agente dovrebbe usare.

L'agente scoprirà e utilizzerà gli strumenti del server all'inizio di ogni chiamata.

Vedi la pagina completa Server MCP per setup dettagliato, risoluzione dei problemi e come MCP si inserisce accanto agli strumenti integrati.

Chiavi API​

Genera chiavi API per integrare Hanc.AI con le tue applicazioni.

Creazione di una chiave API​

Puoi creare fino a 3 chiavi API per utente.

  1. Vai su Integrazione → Chiavi API
  2. Clicca su "Crea chiave API"
  3. Inserisci un nome (es. "Integrazione CRM")
  4. Imposta i permessi (lettura, scrittura, admin)
  5. Copia la chiave immediatamente (mostrata una sola volta)

Sicurezza delle chiavi API​

Importante
  • Memorizza le chiavi in modo sicuro (variabili d'ambiente, gestore segreti)
  • Non committare mai le chiavi al version control
  • Ruota le chiavi periodicamente
  • Elimina le chiavi inutilizzate

Utilizzo delle chiavi API​

Includi nelle richieste API:

curl -X GET "https://api.hanc.ai/v1/agent/list" \
  -H "x-api-key: YOUR_API_KEY"

Permessi delle chiavi API​

PermessoAccesso
LetturaVisualizza agenti, chiamate, analytics
ScritturaCrea/modifica agenti, carica KB
AdminTutte le operazioni, eliminazione, impostazioni

Endpoint disponibili​

L'elenco completo degli endpoint API, raggruppati per risorsa (Chiamate, Agenti, Knowledge Base, Numeri di telefono, Voci, Abbonamento, Clienti, Workspace) vive sulla sua pagina dedicata:

→ Riferimento API completo

Webhook​

Configura i webhook per ricevere notifiche in tempo reale sugli eventi nel tuo account Hanc.AI.

Setup​

  1. Vai su Integrazione → Webhook
  2. Inserisci l'URL del tuo endpoint webhook
  3. Seleziona gli eventi a cui iscriverti
  4. Salva la configurazione

I webhook inviano richieste HTTP POST al tuo endpoint con i dati dell'evento in formato JSON.

Azioni post-chiamata​

Le azioni post-chiamata si attivano automaticamente dopo che termina una conversazione dell'agente vocale IA. Configurale sui singoli agenti.

Tipi di azioni disponibili​

AzioneDescrizione
EmailInvia un riepilogo email della chiamata (al proprietario dell'azienda, al cliente o entrambi)
SMSInvia una notifica SMS dopo la chiamata
WhatsAppInvia un messaggio WhatsApp dopo la chiamata
Chiamata APIEffettua una richiesta HTTP a un endpoint esterno con i dati della chiamata

Setup​

  1. Vai su Agenti vocali IA → seleziona il tuo agente
  2. Apri la scheda Azioni
  3. Clicca su "Aggiungi azione"
  4. Seleziona il tipo di azione e configura:
    • Trigger: Quando si attiva l'azione (es. dopo ogni chiamata, solo su esiti specifici)
    • Destinatari: Chi riceve la notifica
    • Contenuto: Template del messaggio con variabili dati della chiamata

Integrazioni personalizzate​

Utilizzo dell'API​

Costruisci integrazioni personalizzate usando l'API Hanc.AI:

URL Base: https://api.hanc.ai/v1
Autenticazione: Token Bearer (chiave API)
Formato: JSON

Documentazione API​

Vedi il Riferimento API per l'elenco completo degli endpoint disponibili.

Best practice per le integrazioni​

Sicurezza​

  • Memorizza le credenziali in modo sicuro
  • Ruota regolarmente le chiavi API
  • Limita i permessi al minimo necessario

Affidabilità​

  • Registra tutti gli eventi di integrazione
  • Monitora la salute dell'integrazione

Test​

  • Testa prima le integrazioni in staging
  • Verifica il flusso dei dati in entrambe le direzioni
  • Testa gli scenari di errore
  • Documenta il setup dell'integrazione

Risoluzione dei problemi​

L'integrazione non si connette​

  1. Verifica che le credenziali siano corrette
  2. Controlla eventuali errori di battitura
  3. Assicurati che l'account di terze parti sia attivo
  4. Prova a disconnettere e riconnettere

Il calendario non si sincronizza​

  1. Riautorizza l'accesso al calendario
  2. Verifica i permessi del calendario
  3. Verifica che il calendario selezionato sia corretto
  4. Controlla eventuali ritardi di sincronizzazione (fino a 5 minuti)

Argomenti correlati​