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 Swagger interattiva
Esplora ogni endpoint, prova le richieste in tempo reale, scarica la specifica openapi.yaml e genera client nel tuo linguaggio preferito.
Vai a swagger.ai4call.comL'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