Passa al contenuto principale
DocumentationAPI ReferenceVideo Tutorials

Integrazioni

Le integrazioni estendono i tuoi agenti vocali 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
eTerminVerifica la disponibilità e prenota/riprogramma/annulla appuntamenti in tempo reale — vedi eTerminDisponibileTutti
resmioPrenota tavoli del ristorante nel tuo registro prenotazioni in tempo reale — vedi resmioDisponibileTutti
HubSpot CRMLeggi/scrivi contatti e deal dal tuo agente vocaleDisponibileTutti
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 configurazione​

  1. Vai su Phone Numbers nella barra laterale
  2. Clicca "Buy Number"
  3. Seleziona il paese e il tipo di numero
  4. Completa l'acquisto
  5. Assegna un agente al numero

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

Integrazione SIP Trunk​

Porta il tuo carrier SIP — HANC parla SIP nativamente e instrada le chiamate in entrata verso il tuo agente vocale (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, oltre a un'opzione generica per qualsiasi altro:

CarrierAuto-import numeri via 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 gestiti via API
Custom SIP trunkManualeQualsiasi altro provider — fornisci host, porta, transport

Approvazione di conformità​

Le connessioni ai carrier SIP condividono lo stesso flusso di conformità delle campagne in uscita. Finché il tuo account non è approvato, il pulsante Connect SIP apre una finestra modale vetrina che elenca tutti i carrier supportati con una CTA mailto:support@hanc.ai. L'approvazione avviene di solito entro la stessa giornata lavorativa.

Passaggi di configurazione (dopo l'approvazione)​

  1. Vai su Phone Numbers → Connect SIP.
  2. Scegli il tuo carrier.
  3. Inserisci le credenziali SIP (e la chiave/secret API opzionale se il tuo carrier supporta l'auto-import).
  4. Per il Custom SIP, fornisci anche host, porta (predefinita 5060) e transport (UDP / TCP / TLS).
  5. Clicca Connect — HANC registra il tuo utente SIP e, dove supportato, elenca i tuoi numeri di telefono.
  6. Seleziona i numeri da importare (o aggiungili manualmente in formato E.164).
  7. Assegna un agente in entrata e/o in uscita a ciascun numero.

Quando usare il SIP invece di acquistare un numero​

ScenarioRaccomandazione
Nuovo nel servizio telefonicoAcquista numeri tramite HANC (più semplice — nessuna fase di conformità)
PBX o contratto carrier esistenteConnetti via SIP — mantieni il tuo numero
Telefonia aziendale con requisiti carrier rigidiSIP per il controllo completo
Più regioni / pool di numeriSIP per flessibilità

Integrazione Google Calendar​

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

Passaggi di configurazione​

  1. Vai su Integration → Calendars
  2. Clicca "Connect Google Calendar"
  3. Accedi con Google
  4. Autorizza l'accesso di Hanc.AI

Autorizzazioni richieste:

  • Visualizzare gli eventi del calendario (per verificare la disponibilità)
  • Creare eventi del calendario (per prenotare appuntamenti)

Configurazione del calendario​

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

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

Uso del calendario negli agenti​

Una volta connessi e configurati, gli agenti possono:

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

Esempio di conversazione:

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

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

Integrazione Outlook Calendar​

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

Passaggi di configurazione​

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

Autorizzazioni richieste:

  • Visualizzare gli eventi del calendario (per verificare la disponibilità)
  • Creare eventi del calendario (per prenotare appuntamenti)

Configurazione del calendario​

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

ImpostazioneDescrizione
CalendarQuale calendario Outlook usare per la pianificazione
TimezoneFuso orario per la pianificazione degli appuntamenti (es. Europe/Vienna)
Work HoursOre disponibili per la prenotazione (es. lunedì-venerdì 9:00-18:00)
Slot DurationDurata predefinita dell'appuntamento (es. 30 minuti)
BufferTempo cuscinetto tra appuntamenti (es. 15 minuti)

Differenze rispetto a Google Calendar​

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

suggerimento

Puoi collegare contemporaneamente sia i calendari Google che Outlook, ma ogni agente può usare un solo strumento calendario.

Annullamento degli appuntamenti​

I chiamanti che hanno prenotato un appuntamento ricevono un link di annullamento. Possono annullare il proprio appuntamento direttamente senza dover richiamare.

Prenotazione appuntamenti eTermin​

Collega eTermin così i tuoi agenti possono verificare la disponibilità e prenotare, riprogrammare o annullare appuntamenti in tempo reale durante la chiamata, direttamente nei tuoi calendari e servizi eTermin — con protezione integrata contro le doppie prenotazioni. Usa eTermin invece di un calendario semplice quando i tuoi appuntamenti risiedono già in eTermin e offri servizi distinti con durate e regole proprie.

Vedi la pagina completa eTermin per i passaggi di connessione, la configurazione per singolo agente e la protezione contro le doppie prenotazioni.

Prenotazione tavoli resmio​

Collega resmio così i tuoi agenti possono prenotare tavoli del ristorante direttamente nel tuo registro prenotazioni durante una chiamata — verificando la disponibilità reale per orario e numero di persone, e gestendo riprogrammazioni e annullamenti. Usa resmio quando il tuo ristorante accetta già prenotazioni tramite di esso.

Vedi la pagina completa resmio per i passaggi di connessione e i dettagli.

Agire tramite account collegati nei workflow​

Oltre agli strumenti sempre attivi che un agente usa durante una chiamata live, i workflow hanno uno step Integration dedicato (aggiunto in v2.8). Trascina uno step Integration in un workflow per farlo agire tramite un account Google Calendar, Outlook o HubSpot collegato in un singolo step — ad esempio, crea un evento del calendario o aggiorna un deal HubSpot come parte di un flusso automatizzato più ampio. Lo step usa le stesse connessioni a livello di account che imposti in questa pagina, quindi non c'è nulla di ulteriore da autorizzare.

Integrazione HubSpot CRM​

Collega il tuo workspace HubSpot così i tuoi agenti vocali 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 Actions dell'agente. L'agente può abbinare il chiamante a un contatto HubSpot tramite telefono, recuperare la fase del deal e aggiornare le proprietà dalla conversazione live. Vedi Azioni e strumenti.
  • Mirroring delle pipeline nel CRM di HANC. Le fasi dei tuoi deal HubSpot compaiono nel kanban Deals così puoi vedere le chiamate e il contesto HubSpot affiancati.
  • Toggle IA per singola pipeline — decidi su quali pipeline HubSpot l'IA può agire; tutto il resto resta in sola lettura.

Passaggi di configurazione​

  1. Apri la pagina Integrations e clicca Connect HubSpot.
  2. Autorizza HANC nel tuo account HubSpot.
  3. Scegli quali pipeline rispecchiare (visibili nelle impostazioni CRM → Pipeline) e quali dovrebbero consentire aggiornamenti di fase da parte dell'agente.
  4. Aggiungi lo strumento HubSpot CRM a qualsiasi agente che debba interagire con HubSpot durante la chiamata.
suggerimento

Non è necessario 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 mantenere 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 nella pagina Integration e far sì che i tuoi agenti chiamino i suoi strumenti a metà conversazione.

Passaggi di configurazione (panoramica)​

  1. Vai su Integration → MCP servers.
  2. Clicca Connect MCP server, inserisci un'etichetta e l'URL HTTPS del tuo server, scegli l'autenticazione (None o Bearer token) e salva.
  3. Apri l'agente su cui vuoi usare gli strumenti, vai su Actions → Add Action → MCP servers e attiva le connessioni che questo agente dovrebbe usare.

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

Vedi la pagina completa Server MCP per la configurazione dettagliata, la risoluzione dei problemi e come MCP si affianca agli strumenti integrati.

Chiavi API​

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

Creare una chiave API​

Puoi creare fino a 3 chiavi API per utente.

  1. Vai su Integration → API Keys
  2. Clicca "Create API Key"
  3. Inserisci un nome (es. "CRM Integration")
  4. Imposta i permessi (read, write, admin)
  5. Copia la chiave immediatamente (mostrata solo una volta)

Sicurezza delle chiavi API​

Importante
  • Conserva le chiavi in modo sicuro (variabili d'ambiente, secrets manager)
  • Non inserire mai le chiavi nel version control
  • Ruota le chiavi periodicamente
  • Elimina le chiavi inutilizzate

Uso 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
ReadVisualizzare agenti, chiamate, analytics
WriteCreare/modificare agenti, caricare KB
AdminTutte le operazioni, eliminazione, impostazioni

Endpoint disponibili​

L'elenco completo degli endpoint API, raggruppati per risorsa (Calls, Agents, Knowledge Base, Phone Numbers, Voices, Subscription, Customers, Workspaces) si trova nella sua pagina dedicata:

→ Riferimento API completo

Webhook​

Dopo ogni chiamata Hanc.AI può inviare la chiamata — riepilogo, trascrizione e i tuoi campi estratti — al tuo endpoint in formato JSON. Configuralo come azione Chiamata API post-chiamata sull'agente (Azioni → Post call) oppure come passaggio Chiamata API in un workflow.

Se il tuo server non è disponibile, la richiesta viene ritentata secondo una pianificazione (per impostazione predefinita 8 tentativi in circa 3,4 giorni), ogni tentativo viene registrato e una consegna non riuscita può essere inviata di nuovo.

Consulta Webhook e consegna per i nuovi tentativi, il registro delle consegne, i requisiti del firewall e il formato dei dati.

Azioni post-chiamata​

Le azioni post-chiamata si attivano automaticamente dopo la fine di una conversazione con un agente vocale. Configurale sui singoli agenti.

Tipi di azione disponibili​

AzioneDescrizione
EmailInvia un riepilogo email della chiamata (al titolare, al cliente o a entrambi)
SMSInvia una notifica SMS dopo la chiamata
WhatsAppInvia un messaggio WhatsApp dopo la chiamata
API CallEffettua una richiesta HTTP a un endpoint esterno con i dati della chiamata

Configurazione​

  1. Vai su Voice Agents → seleziona il tuo agente
  2. Apri la scheda Actions
  3. Clicca "Add Action"
  4. Seleziona il tipo di azione e configura:
    • Trigger: Quando l'azione si attiva (es. dopo ogni chiamata, solo su esiti specifici)
    • Recipients: Chi riceve la notifica
    • Content: Template del messaggio con variabili dei dati della chiamata

Integrazioni personalizzate​

Usare l'API​

Costruisci integrazioni personalizzate usando l'API di Hanc.AI:

Base URL: https://api.hanc.ai/v1
Authentication: Bearer token (API key)
Format: JSON

Documentazione API​

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

Best practice per le integrazioni​

Sicurezza​

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

Affidabilità​

  • Registra tutti gli eventi di integrazione
  • Monitora lo stato dell'integrazione

Test​

  • Testa prima le integrazioni in staging
  • Verifica il flusso dei dati in entrambe le direzioni
  • Testa gli scenari di errore
  • Documenta la configurazione 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. Ri-autorizza l'accesso al calendario
  2. Controlla i permessi del calendario
  3. Verifica che il calendario selezionato sia corretto
  4. Controlla eventuali ritardi di sincronizzazione (fino a 5 minuti)

Argomenti correlati​