API AI4CALL: integra l'AI vocale nei tuoi sistemi
Un set completo di API REST per controllare assistenti AI, gestire prompt e configurazione vocale, knowledge base RAG, tool, plugin e analytics. Tutto documentato in formato OpenAPI 3 esplorabile via Swagger.
Come funziona l'autenticazione
Le API utilizzano credenziali del portale (email + portalApiKey) e header dedicati su tutte le chiamate business. Un secondo livello di chiave (assistantApiKey) protegge le operazioni sui singoli assistenti.
Login portale
Chiama POST /api/v1/auth/portal/login passando email e portalApiKey per validare le credenziali del cliente.
Header di sessione
Su ogni richiesta business invia gli header x-client-email e x-portal-api-key. Tutto il traffico viaggia su HTTPS/TLS.
Operazioni per assistente
Per modificare un singolo assistente usa l'assistantApiKey nel path: /api/v1/assistants/{assistantApiKey}/...
Aree funzionali esposte dalle API
Le API espongono tutta la piattaforma AI4CALL. Ogni area corrisponde a un gruppo di endpoint Swagger ed è governata in modo programmatico, con la stessa logica del portale grafico.
Account & ambiente
Gestisci configurazione globale del cliente: IP autorizzati, limiti di chiamata, routing dei numeri e plugin attivi.
/account/allowed-ips— IP whitelist (lettura/aggiornamento)/account/call-limits— Limiti chiamate concorrenti e per periodo/account/number-routing— Mapping numero → assistente/account/plugins/*— Plugin disponibili, istanze, configurazioni e acquisti
Assistenti & prompt
CRUD completo sugli assistenti AI: creali, leggi i dettagli, aggiorna prompt, primo messaggio e settings.
GET/POST /assistants— Lista e creazione assistenti/assistants/{key}— Dettaglio del singolo assistente/assistants/{key}/prompt— Prompt + first message editabili/runtime/settings— Settings runtime e advanced settings
Voce: TTS, ASR, LLM, DTMF
Scegli provider e modelli per text-to-speech, speech-to-text, LLM e DTMF, e applicali al volo all'assistente.
/catalog/providers/tts+tts/voices/catalog/providers/asr+asr/models/catalog/providers/llm+llm/models/runtime/{tts|asr|llm|dtmf}— Aggiornamento runtime di TTS, ASR, LLM e DTMF
RAG & knowledge base
Carica documenti, gestisci collezioni e collega le knowledge base ai tuoi assistenti per risposte sempre aggiornate.
/catalog/rag/collections— Lista collezioni RAG/rag/collections/{name}/documents— Upload, lista, elimina documenti/rag/documents/estimate— Stima preventiva di indicizzazione/runtime/rag— Binding RAG runtime sull'assistente
Tool & Pre-Call
Estendi gli assistenti con tool disponibili e logica pre-call: validazione numero, configurazione MCP e tool runtime.
/catalog/tools— Catalogo tool runtime lato cliente/runtime/tools— Tool collegati al singolo assistente/runtime/precall/number-validation/runtime/precall/mcp-config
Hangup & post-call
Definisci comportamenti di chiusura chiamata: redirect, trasferimento, salvataggio conversazione e schema dati strutturati.
/runtime/hangup— Configurazione hangup, redirect e trasferimento/runtime/hangup/save-conversation/runtime/hangup/schema- Catalogo opzioni hangup disponibili
Outbound & PBX
Avvia chiamate outbound dal tuo backend, sia con trunk AI4CALL sia con il PBX del cliente, in webhook semplici da invocare.
POST /webhook/outbound_call— Outbound via trunk AI4CALLPOST /webhook/outbound_call_pbx— Outbound via PBX cliente- Passaggio metadati custom (es. lead_id, ticket)
- Tracking dell'esito su Analytics
Analytics & storico
Esponi storico chiamate, ricariche, RAG, SMS e tool responses per la tua reportistica e i tuoi dashboard.
/account/analytics/calls+calls-outbound/account/analytics/recharges/account/analytics/rag·sms·tool-responses/account/analytics/pre-call
Come iniziare in 4 passi
Dall'attivazione alla prima chiamata via API in pochi minuti.
Attiva un account
Registra la tua azienda su AI4CALL e attiva il piano più adatto al tuo caso d'uso.
Genera la portalApiKey
Dal portale crea una chiave dedicata per ogni applicazione o ambiente (test, produzione).
Esplora Swagger
Apri la documentazione interattiva, prova gli endpoint e copia le request già pronte.
Integra & vai in produzione
Integra le API nei tuoi sistemi, configura outbound e analytics e monitora i consumi.
Esempi di chiamate cURL
Tre snippet che coprono il flusso più comune: login, lettura assistenti, lancio outbound.
1. Login portale
curl -X POST https://client-api.ai4call.com/api/v1/auth/portal/login \ -H "Content-Type: application/json" \ -d '{ "email": "demo@ai4call.local", "portalApiKey": "portal_demo_key_123456789" }'
2. Lista assistenti del cliente
curl -X GET https://client-api.ai4call.com/api/v1/assistants \ -H "x-client-email: demo@ai4call.local" \ -H "x-portal-api-key: portal_demo_key_123456789"
3. Avvio chiamata outbound
curl -X POST https://client-api.ai4call.com/webhook/outbound_call \ -H "x-client-email: demo@ai4call.local" \ -H "x-portal-api-key: portal_demo_key_123456789" \ -H "Content-Type: application/json" \ -d '{ "assistantApiKey": "ast_xxx", "to": "+39081...", "from": "+3902...", "metadata": { "lead_id": "123" } }'
Tutti gli endpoint sono documentati in Swagger con request/response di esempio, codici di errore e schemi JSON. Gli header x-client-email e x-portal-api-key sono richiesti su tutte le chiamate business.
Scenari di integrazione
Le API AI4CALL si adattano sia a software gestionali sia a flussi automatizzati low-code.
Integrazione CRM / ERP
Sincronizza lead, ticket e attività con il tuo gestionale e fai partire chiamate AI direttamente dal CRM.
Automazioni interne
Orchestra campagne outbound, conferme appuntamenti, recall e sondaggi automatici via webhook.
Reportistica avanzata
Porta i dati di AI4CALL nel tuo data warehouse o nei tuoi tool BI (Power BI, Looker, Metabase).
Workflow no-code
Collega AI4CALL a strumenti come n8n, Zapier o Make per automatizzare flussi senza scrivere codice.
Tool & plugin custom
Esponi le tue funzioni di business come tool che gli assistenti possono invocare durante le chiamate.
Multi-tenant & rivenditori
Costruisci portali e dashboard multi-cliente sopra alle API, con isolamento dati e branding.
Sicurezza, affidabilità e compliance
Le API sono pensate per ambienti di produzione: sicure, monitorate e versionate.
Autenticazione a doppio livello
Header x-client-email + x-portal-api-key per il cliente, assistantApiKey nel path per le operazioni sul singolo assistente. Tutto su HTTPS/TLS.
IP whitelist
Limita l'uso delle API a una lista di IP autorizzati gestita via /account/allowed-ips.
Limiti & quote
Endpoint dedicato /account/call-limits per leggere e aggiornare i limiti di chiamata, senza superare la capacità contrattuale.
Versioning stabile
Tutti gli endpoint business sono in /api/v1/. Le evoluzioni breaking saranno introdotte con una nuova major.
Documentazione completa delle API
Nella API Reference trovi ogni endpoint con parametri, esempi ed errori. Su Swagger puoi provare le richieste in tempo reale e scaricare la specifica openapi.yaml.
L'API è documentata secondo lo standard OpenAPI 3.0.3 ed è esplorabile tramite Swagger UI su https://swagger.ai4call.com/. Puoi scaricare il file openapi.yaml direttamente dalla stessa pagina.
La base URL di produzione è https://client-api.ai4call.com. Tutti gli endpoint business sono sotto il prefisso /api/v1/, mentre le chiamate outbound usano il prefisso /webhook/.
Si parte con POST /api/v1/auth/portal/login passando email e portalApiKey. Successivamente, ogni richiesta business deve includere gli header x-client-email e x-portal-api-key. Le operazioni sul singolo assistente richiedono inoltre l'assistantApiKey nel path.
Sì. GET/POST /api/v1/assistants permette lista e creazione, GET /api/v1/assistants/{assistantApiKey} il dettaglio. Il tag Assistants in Swagger raccoglie tutte le operazioni disponibili.
Sì, tramite GET e PATCH su /api/v1/assistants/{assistantApiKey}/prompt. È pensato per editing programmatico del prompt e del first message senza passare dal portale.
Per ogni provider/voce/modello disponibile c'è un endpoint di catalogo (es. /api/v1/catalog/providers/tts, /catalog/assistants/{key}/asr/models) ed un endpoint runtime di assegnazione (PATCH /api/v1/assistants/{assistantApiKey}/runtime/{tts|asr|llm|dtmf}).
Le collezioni RAG si gestiscono sotto /api/v1/catalog/rag/: lista collezioni, upload e cancellazione documenti, stima preventiva di indicizzazione e binding sull'assistente con PATCH /assistants/{key}/runtime/rag.
Sì. GET /api/v1/catalog/tools restituisce i tool disponibili, mentre /catalog/assistants/{key}/tools e PATCH /assistants/{key}/runtime/tools permettono di assegnare i tool a un singolo assistente.
Sotto /api/v1/assistants/{key}/runtime/precall/ puoi configurare la number-validation e la mcp-config. Inoltre /catalog/assistants/{key}/pre-call espone le opzioni disponibili.
Endpoint PATCH /assistants/{key}/runtime/hangup per redirect/trasferimento, /runtime/hangup/save-conversation per il salvataggio della conversazione e /runtime/hangup/schema per definire uno schema dati strutturato in uscita.
Tramite POST /webhook/outbound_call (trunk AI4CALL) oppure POST /webhook/outbound_call_pbx (PBX cliente). In entrambi i casi indichi assistente, numero da chiamare e metadati personalizzati.
Sotto /api/v1/account/analytics/ trovi storico chiamate inbound e outbound, ricariche, eventi RAG, SMS, tool responses e pre-call. Sono pensate per essere ingerite da BI o data warehouse.
Sì. GET/PATCH /api/v1/account/allowed-ips permette di leggere e aggiornare la whitelist di IP che possono autenticarsi e usare le API.
Tramite GET/PATCH /api/v1/account/call-limits puoi leggere e aggiornare i limiti, ad esempio chiamate concorrenti o per periodo, in base al piano sottoscritto.
Sì. Puoi listare i plugin disponibili (/account/plugins/available), gestire le istanze (/account/plugins/instances), aggiornarne la configurazione (/account/plugins/configuration) e finalizzare l'acquisto (PATCH /account/plugins/purchase).
Sì, GET /health ritorna lo stato del servizio. Non richiede autenticazione ed è utile per monitoring e probe automatici.
Tutti gli endpoint business sono sotto il prefisso /api/v1/. Eventuali modifiche non retro-compatibili saranno introdotte come /api/v2/, mantenendo la v1 attiva durante il periodo di transizione.
Puoi usare credenziali (email + portalApiKey) dedicate ad ambienti di test, isolando le configurazioni e i numeri dalle chiamate di produzione. Contattaci dal portale per attivare un account di test.
Tecnologia e persone:
insieme, zero attese e mille soluzioni.
Pronto a trasformare
le tue chiamate?
Richiedi una demo gratuita e scopri come AI4CALL può rivoluzionare il tuo business