v1.2.0
OpenAPI 3.0.3

AI4Call Client API

AI4Call technical support
Proprietary
Terms of Service

Contratto OpenAPI pubblico per le API AI4Call lato client.

Il servizio principale su https://client-api.ai4call.com copre la gestione autenticata dell'account, gli assistenti e la loro configurazione runtime, il provider wallet, le risorse di catalogo, le knowledge, la gestione dei documenti RAG, i tool e le analytics dell'account.

Flusso di autenticazione attuale della Client API:

  1. POST /api/v1/auth/portal/login valida email e portalApiKey. Non emette un access token e non crea una sessione lato server.
  2. Le chiamate business accettano Authorization: Bearer <portalApiKey> oppure la coppia legacy x-client-email e x-portal-api-key.
  3. Le operazioni su un singolo assistente usano assistantId; i valori path legacy assistantApiKey restano accettati durante il periodo di compatibilità v1.

Questo documento include anche operazioni ospitate da servizi dedicati. Le operazioni Public RAG usano la propria autenticazione Bearer e le operazioni outbound usano un proprio header API key; ogni operazione dichiara il server e lo schema di sicurezza dedicati.

Server:https://client-api.ai4call.com

Produzione client API

No authentication selected
Client Libraries
Shell Curl

Health

​

Verifica disponibilità del servizio API

Health Operations

Health check del servizio

​

Health check del servizio

Responses

  • application/json
  • application/json
  • application/json
Request Example for get/health
curl https://client-api.ai4call.com/health

{
  "success": true,
  "message": "Service is healthy.",
  "requestId": "8cb7cd6b-3f55-4226-b4a2-54fd9e90ec99",
  "data": {
    "status": "ok",
    "service": "api-rest-assistant-creator",
    "dataSource": "database"
  }
}

Servizio attivo

Auth

​

Autenticazione cliente portale via email e portalApiKey

Auth Operations

Autentica un cliente portale con email e portalApiKey

​

Valida le credenziali statiche del portale e restituisce i dati del cliente. Non emette token e non crea sessioni lato server.

Body·

required
application/json

Credenziali usate per verificare un cliente del portale. La richiesta non crea una sessione e non emette un access token.

  • email
    Type: stringFormat: email
    required

    Email del cliente del portale.

  • portalApiKey
    Type: string
    min length:  
    10
    required

    API key statica del portale associata all'account cliente.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/api/v1/auth/portal/login
curl https://client-api.ai4call.com/api/v1/auth/portal/login \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "developer@example.com",
  "portalApiKey": "portal_demo_key_123456789"
}'

{
  "success": true,
  "message": "Portal client authenticated successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "client": {
      "clientId": "example-id",
      "email": "developer@example.com",
      "displayName": "Example",
      "companyName": "Example",
      "isActive": true
    }
  }
}

Cliente autenticato

Account

​

Gestione account del cliente autenticato

Account Operations

Recupera gli IP consentiti dell'account autenticato

​

Recupera gli IP consentiti dell'account autenticato

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/allowed-ips
curl https://client-api.ai4call.com/api/v1/account/allowed-ips \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Account allowed IPs retrieved successfully.",
  "requestId": "9755db58-3e8d-4a09-b3a1-c68fd6f70c8a",
  "data": {
    "configuration": {
      "allowedIps": [
        {
          "ip": "10.10.10.5",
          "description": "Ufficio principale"
        },
        {
          "ip": "192.168.1.20",
          "description": null
        }
      ]
    }
  },
  "meta": {
    "count": 2
  }
}

Lista IP consentiti dell'account

Aggiorna gli IP consentiti dell'account autenticato

​

Aggiorna la lista IP consentiti dell'account con semantica PATCH merge.

Parametri modificabili:

  • allowedIps
  • allowedIps[].ip
  • allowedIps[].description
  • addIps
  • addIps[].ip
  • addIps[].description
  • deleteIps

Come recuperare i dati correnti:

  • usa GET /api/v1/account/allowed-ips

Regole operative:

  • allowedIps sostituisce tutta la lista
  • addIps aggiunge IP nuovi oppure aggiorna la descrizione di IP già presenti
  • deleteIps rimuove gli IP indicati
  • non combinare allowedIps con addIps o deleteIps
  • allowedIps: [] svuota completamente la lista
  • dopo l'update DB, il backend sincronizza immediatamente anche il firewall

Body·

required
application/json

PATCH merge della configurazione IP consentiti dell'account.

Regole operative:

  • allowedIps sostituisce completamente la lista corrente
  • addIps aggiunge nuovi IP oppure aggiorna la description di un IP già presente
  • deleteIps rimuove gli IP indicati
  • allowedIps non può essere combinato con addIps o deleteIps
  • allowedIps: [] rimuove tutti gli IP
  • description: null o stringa vuota rimuove la descrizione dell'IP
  • addIps
    Type:

    Valore da inviare per addIps nella richiesta AccountAllowedIpsUpdateRequest.

    Properties: 2
  • allowedIps
    Type:

    Valore da inviare per allowedIps nella richiesta AccountAllowedIpsUpdateRequest.

    Properties: 2
  • deleteIps
    Type: array of stringFormat: ipv4

    Valore da inviare per deleteIps nella richiesta AccountAllowedIpsUpdateRequest.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/account/allowed-ips
curl https://client-api.ai4call.com/api/v1/account/allowed-ips \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "allowedIps": [
    {
      "ip": "10.10.10.5",
      "description": "Ufficio principale"
    },
    {
      "ip": "192.168.1.20",
      "description": "Casa"
    }
  ]
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "configuration": {
      "allowedIps": [
        {
          "ip": "203.0.113.10",
          "description": "esempio"
        }
      ]
    }
  },
  "meta": {
    "count": 1
  }
}

Lista IP consentiti aggiornata

Recupera i limiti chiamate dell'account autenticato

​

Restituisce i limiti chiamate simultanee account-level per tutti gli assistenti del cliente.

Come usare la risposta:

  • usa assistants[].assistantApiKey nella PATCH
  • configuredLimit è il valore salvato lato tenant
  • maxConcurrentCalls è il valore effettivo mostrato a portale
  • se configuredLimit è null, il backend usa defaultLimit

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/call-limits
curl https://client-api.ai4call.com/api/v1/account/call-limits \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Account call limits retrieved successfully.",
  "data": {
    "configuration": {
      "defaultLimit": 10,
      "assistants": [
        {
          "assistantApiKey": "ai4call_sk_abc123",
          "assistantName": "Assistente Demo",
          "description": "Assistenza clienti",
          "configuredLimit": 5,
          "maxConcurrentCalls": 5
        },
        {
          "assistantApiKey": "ai4call_sk_sales456",
          "assistantName": "Assistente Vendite",
          "description": null,
          "configuredLimit": null,
          "maxConcurrentCalls": 10
        }
      ]
    }
  },
  "meta": {
    "count": 2
  },
  "requestId": "9755db58-3e8d-4a09-b3a1-c68fd6f70c8a"
}

Limiti chiamate dell'account

Aggiorna i limiti chiamate dell'account autenticato

​

Aggiorna i limiti chiamate simultanee account-level con semantica PATCH merge.

Parametri modificabili:

  • assistants
  • assistants[].assistantApiKey
  • assistants[].maxConcurrentCalls

Come recuperare i dati:

  • usa GET /api/v1/account/call-limits
  • riusa assistants[].assistantApiKey

Regole operative:

  • ogni item modifica solo l'assistente indicato
  • maxConcurrentCalls: null rimuove il limite configurato e l'assistente torna al defaultLimit
  • se un assistente non è presente nel payload, il suo limite non cambia

Body·

required
application/json

PATCH merge dei limiti chiamate simultanee dell'account.

Regole operative:

  • assistants è obbligatorio
  • ogni item aggiorna solo l'assistente indicato
  • maxConcurrentCalls: null rimuove il limite configurato per quell'assistente
  • se un assistente non viene inviato, il suo limite corrente non cambia
  • maxConcurrentCalls deve essere un intero maggiore o uguale a 0
  • assistants
    Type:
    required

    Valore da inviare per assistants nella richiesta AccountCallLimitsUpdateRequest.

    Properties: 2

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/account/call-limits
curl https://client-api.ai4call.com/api/v1/account/call-limits \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "assistants": [
    {
      "assistantApiKey": "ai4call_sk_abc123",
      "maxConcurrentCalls": 5
    },
    {
      "assistantApiKey": "ai4call_sk_sales456",
      "maxConcurrentCalls": 12
    }
  ]
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "configuration": {
      "defaultLimit": 1,
      "assistants": [
        {
          "assistantApiKey": "ai4call_sk_example",
          "assistantName": "Example",
          "configuredLimit": 1,
          "maxConcurrentCalls": 1
        }
      ]
    }
  },
  "meta": {
    "count": 1
  }
}

Limiti chiamate aggiornati

Recupera il routing numeri dell'account autenticato

​

Restituisce il routing numeri account-level del portale:

  • assistants
  • demoNumbers
  • purchasedNumbers
  • userNumbers

Come usare la risposta:

  • usa assistants[].assistantApiKey nei payload di PATCH
  • usa phoneNumber delle rispettive liste nei payload di PATCH
  • assistantApiKey e assistantName dentro ogni numero indicano l'assistente attualmente collegato

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/number-routing
curl https://client-api.ai4call.com/api/v1/account/number-routing \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Account number routing retrieved successfully.",
  "data": {
    "configuration": {
      "assistants": [
        {
          "assistantApiKey": "ai4call_sk_abc123",
          "assistantName": "Assistente Demo"
        }
      ],
      "demoNumbers": [
        {
          "phoneNumber": "000012345678",
          "assistantApiKey": "ai4call_sk_abc123",
          "assistantName": "Assistente Demo",
          "assignedAt": "2026-04-24T10:00:00.000Z"
        }
      ],
      "purchasedNumbers": [
        {
          "phoneNumber": "+390201234567",
          "prefix": "02",
          "assistantApiKey": null,
          "assistantName": null,
          "acquiredAt": "2026-04-20T09:00:00.000Z"
        }
      ],
      "userNumbers": [
        {
          "phoneNumber": "+390612345678",
          "prefix": "06",
          "assistantApiKey": "ai4call_sk_abc123",
          "assistantName": "Assistente Demo",
          "createdAt": "2026-04-10T09:00:00.000Z"
        }
      ]
    }
  },
  "meta": {
    "assistantCount": 1,
    "demoCount": 1,
    "purchasedCount": 1,
    "userCount": 1,
    "totalCount": 3
  },
  "requestId": "9755db58-3e8d-4a09-b3a1-c68fd6f70c8a"
}

Routing numeri dell'account

Aggiorna il routing numeri dell'account autenticato

​

Aggiorna il routing numeri account-level con semantica PATCH merge.

Parametri modificabili:

  • demoNumbers
  • demoNumbers[].phoneNumber
  • demoNumbers[].assistantApiKey
  • purchasedNumbers
  • purchasedNumbers[].phoneNumber
  • purchasedNumbers[].assistantApiKey
  • userNumbers
  • userNumbers[].phoneNumber
  • userNumbers[].assistantApiKey

Come recuperare i dati:

  • usa GET /api/v1/account/number-routing
  • riusa assistants[].assistantApiKey
  • riusa demoNumbers[].phoneNumber, purchasedNumbers[].phoneNumber, userNumbers[].phoneNumber

Regole operative:

  • ogni item modifica solo il numero indicato
  • assistantApiKey: null rilascia il numero
  • se il numero era già associato a un altro assistente, viene spostato sul nuovo
  • per i numeri demo, assegnando un assistente a un demo number, l'eventuale altro demo già collegato a quell'assistente viene rilasciato
  • i campi omessi non vengono modificati

Body·

required
application/json

PATCH merge del routing numeri dell'account.

Regole operative:

  • almeno uno tra demoNumbers, purchasedNumbers, userNumbers deve essere presente
  • ogni item aggiorna solo il numero indicato
  • assistantApiKey: null rilascia il numero
  • assistantApiKey: "..." collega o sposta il numero verso quell'assistente
  • se un numero era collegato a un altro assistente, viene sganciato e ricollegato al nuovo
  • per i numeri demo, se l'assistente target aveva già un altro demo number, il vecchio viene rilasciato
  • i campi omessi non vengono modificati
  • demoNumbers
    Type:

    Valore da inviare per demoNumbers nella richiesta AccountNumberRoutingUpdateRequest.

    Properties: 2
  • purchasedNumbers
    Type:

    Valore da inviare per purchasedNumbers nella richiesta AccountNumberRoutingUpdateRequest.

    Properties: 2
  • userNumbers
    Type:

    Valore da inviare per userNumbers nella richiesta AccountNumberRoutingUpdateRequest.

    Properties: 2

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/account/number-routing
curl https://client-api.ai4call.com/api/v1/account/number-routing \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "demoNumbers": [
    {
      "phoneNumber": "000012345678",
      "assistantApiKey": "ai4call_sk_abc123"
    }
  ],
  "purchasedNumbers": [
    {
      "phoneNumber": "+390201234567",
      "assistantApiKey": "ai4call_sk_sales456"
    }
  ],
  "userNumbers": [
    {
      "phoneNumber": "+390612345678",
      "assistantApiKey": null
    }
  ]
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "configuration": {
      "assistants": [
        {
          "assistantApiKey": "ai4call_sk_example",
          "assistantName": "Example"
        }
      ],
      "demoNumbers": [
        {
          "phoneNumber": "+390212345678"
        }
      ],
      "purchasedNumbers": [
        {
          "phoneNumber": "+390212345678"
        }
      ],
      "userNumbers": [
        {
          "phoneNumber": "+390212345678"
        }
      ]
    }
  },
  "meta": {
    "assistantCount": 1,
    "demoCount": 1,
    "purchasedCount": 1,
    "userCount": 1,
    "totalCount": 1
  }
}

Routing numeri aggiornato

Recupera tutti i plugin acquistabili dell'account autenticato

​

Restituisce i plugin acquistabili per il cliente autenticato secondo il suo listino.

Come usare i dati:

  • riusa direttamente pluginName nella PATCH PATCH /api/v1/account/plugins/purchase
  • non servono id plugin

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/plugins/available
curl https://client-api.ai4call.com/api/v1/account/plugins/available \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Account purchasable plugins retrieved successfully.",
  "requestId": "99c930a8-4f1f-4c98-8b9b-6af88a3aa7d8",
  "data": {
    "configuration": {
      "plugins": [
        {
          "pluginName": "Google Sheets",
          "pluginCode": "google_sheets",
          "description": "Integrazione con Google Sheets",
          "category": "data_integrations",
          "pluginType": "paid",
          "purchasePrice": 9.9,
          "monthlyPrice": 4.9,
          "priceListName": "Standard",
          "activeInstanceCount": 1
        }
      ]
    }
  },
  "meta": {
    "count": 1
  }
}

Lista plugin acquistabili

Recupera tutte le istanze plugin attive acquistate dall'account autenticato

​

Restituisce le istanze plugin attive del cliente autenticato.

Uso canonico:

  • usa l'instanceId stabile con PATCH /api/v1/account/plugins/instances/{instanceId}
  • usa lo stesso instanceId con DELETE /api/v1/account/plugins/instances/{instanceId}

La PATCH legacy basata sui nomi resta disponibile per compatibilità.

Query Parameters

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di elementi restituiti in una pagina con paginazione a cursore. Ometti sia limit sia cursor per mantenere la risposta legacy non paginata.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor dalla pagina precedente.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/plugins/instances
curl https://client-api.ai4call.com/api/v1/account/plugins/instances \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Account purchased plugin instances retrieved successfully.",
  "requestId": "1f345f1f-53a9-4d87-8a65-f45966c26ef8",
  "data": {
    "configuration": {
      "instances": [
        {
          "pluginName": "Google Sheets",
          "pluginCode": "google_sheets",
          "description": "Integrazione con Google Sheets",
          "category": "data_integrations",
          "instanceName": "Sheets Produzione",
          "instanceIndex": 1,
          "status": "active",
          "activationDate": "2026-04-24T10:30:00.000Z",
          "nextBillingDate": "2026-05-24T10:30:00.000Z",
          "purchasePrice": 9.9,
          "monthlyPrice": 4.9,
          "instanceId": "1"
        }
      ]
    }
  },
  "meta": {
    "count": 1
  }
}

Lista istanze plugin attive acquistate

Crea un'istanza plugin acquistata

​

Acquista un plugin e crea una nuova istanza plugin dell'account. La risposta espone l'instanceId stabile usato dalle route canoniche dell'istanza.

Body·

required
application/json

Acquista un plugin usando il nome plugin restituito da GET /api/v1/account/plugins/available.

Regole operative:

  • pluginName deve corrispondere al valore restituito dal catalogo
  • instanceName è opzionale
  • se instanceName non è presente, il backend genera automaticamente Istanza N
  • gli alias legacy snake_case restano accettati ma sono deprecati

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/api/v1/account/plugins/instances
curl https://client-api.ai4call.com/api/v1/account/plugins/instances \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "pluginName": "Google Sheets",
  "instanceName": "Sheets Produzione"
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "configuration": {
      "pluginName": "Example",
      "pluginCode": "example",
      "instanceName": "Example",
      "instanceIndex": 1,
      "status": "active",
      "activationDate": "2026-09-28T10:30:00.000Z",
      "purchasePriceCharged": 1,
      "monthlyPriceCharged": 1,
      "totalCharged": 1,
      "instanceId": "1"
    }
  }
}

Istanza plugin creata correttamente

Rinomina un'istanza plugin acquistata

​

Rinomina un'istanza plugin attiva usando il relativo instanceId stabile.

Path Parameters

  • instanceId
    Type: string
    required

    Identificativo stabile della sottoscrizione plugin restituito dall'elenco istanze o dall'operazione di creazione.

Body·

required
application/json

Rinomina un'istanza plugin acquistata identificata dal relativo instanceId stabile.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/account/plugins/instances/{instanceId}
curl 'https://client-api.ai4call.com/api/v1/account/plugins/instances/{instanceId}' \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "newInstanceName": "Sheets Marketing"
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "configuration": {
      "pluginName": "Example",
      "pluginCode": "example",
      "instanceName": "Example",
      "previousInstanceName": "Example",
      "status": "active",
      "activationDate": "2026-09-28T10:30:00.000Z",
      "nextBillingDate": "2026-09-28T10:30:00.000Z",
      "instanceId": "1"
    }
  }
}

Istanza plugin aggiornata

Annulla un'istanza plugin acquistata

​

Annulla un'istanza plugin attiva usando il relativo instanceId stabile.

Path Parameters

  • instanceId
    Type: string
    required

    Identificativo stabile della sottoscrizione plugin restituito dall'elenco istanze o dall'operazione di creazione.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for delete/api/v1/account/plugins/instances/{instanceId}
curl 'https://client-api.ai4call.com/api/v1/account/plugins/instances/{instanceId}' \
  --request DELETE \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "configuration": {
      "pluginName": "Example",
      "pluginCode": "example",
      "instanceName": "Example",
      "previousInstanceName": "Example",
      "status": "cancelled",
      "activationDate": "2026-09-28T10:30:00.000Z",
      "nextBillingDate": null,
      "instanceId": "1"
    }
  }
}

Istanza plugin annullata

Recupera la configurazione di un'istanza plugin acquistata

​

Recupera la configurazione di un'istanza plugin acquistata. Usa l'instanceId stabile restituito da GET /api/v1/account/plugins/instances. Il percorso legacy basato sul nome resta supportato.

Path Parameters

  • instanceId
    Type: string
    required

    Identificativo stabile dell'istanza plugin acquistata.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/plugins/instances/{instanceId}/configuration
curl 'https://client-api.ai4call.com/api/v1/account/plugins/instances/{instanceId}/configuration' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "string",
  "requestId": "string",
  "data": {
    "configuration": {
      "pluginName": "string",
      "pluginCode": "string",
      "instanceName": null,
      "supportsConfiguration": true,
      "requiresInstanceName": true,
      "patchMode": "merge",
      "configurableProperties": [
        {
          "key": "string",
          "label": "string",
          "type": "string",
          "required": true,
          "secret": true,
          "description": null,
          "enumValues": [
            "string"
          ],
          "replaceOnPatch": true
        }
      ],
      "configuration": null,
      "availableInstanceNames": [
        "string"
      ],
      "note": null
    }
  }
}

Configurazione plugin

Aggiorna la configurazione di un'istanza plugin acquistata

​

Aggiorna la configurazione usando l'instanceId stabile. I nomi del plugin e dell'istanza sono risolti lato server, quindi i client inviano solo i campi di configurazione da unire.

Path Parameters

  • instanceId
    Type: string
    required

    Identificativo stabile dell'istanza plugin acquistata.

Body·

required
application/json

Corpo PATCH della configurazione indirizzato tramite un instanceId stabile del plugin.

  • configuration
    Type: object
    required

    Campi specifici del plugin da unire alla configurazione salvata.

    Properties: 1

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/account/plugins/instances/{instanceId}/configuration
curl 'https://client-api.ai4call.com/api/v1/account/plugins/instances/{instanceId}/configuration' \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "configuration": {
    "additionalProperty": "anything"
  }
}'

{
  "success": true,
  "message": "string",
  "requestId": "string",
  "data": {
    "configuration": {
      "pluginName": "string",
      "pluginCode": "string",
      "instanceName": null,
      "supportsConfiguration": true,
      "requiresInstanceName": true,
      "patchMode": "merge",
      "configurableProperties": [
        {
          "key": "string",
          "label": "string",
          "type": "string",
          "required": true,
          "secret": true,
          "description": null,
          "enumValues": [
            "string"
          ],
          "replaceOnPatch": true
        }
      ],
      "configuration": null,
      "availableInstanceNames": [
        "string"
      ],
      "note": null
    }
  }
}

Configurazione plugin aggiornata

Assistants

​

Gestione degli assistenti del cliente autenticato

Assistants Operations

Elenca gli assistenti del cliente autenticato

​

Elenca gli assistenti del cliente autenticato

Query Parameters

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di elementi restituiti in una pagina con paginazione a cursore. Ometti sia limit sia cursor per mantenere la risposta legacy non paginata.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor dalla pagina precedente.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/assistants
curl https://client-api.ai4call.com/api/v1/assistants \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistants": [
      {
        "assistantId": "example-id",
        "id": "example-id",
        "clientEmail": "developer@example.com",
        "mode": "text",
        "name": "Example",
        "status": "draft",
        "numbers": {
          "demo": [
            "example"
          ],
          "purchased": [
            "example"
          ]
        },
        "network": {
          "allowedIps": [
            "203.0.113.10"
          ]
        },
        "settings": {
          "model": "example-model",
          "voice": "example-voice",
          "language": "it-IT",
          "timezone": "Europe/Rome",
          "recordingEnabled": true
        },
        "firstMessage": {
          "text": "",
          "callerSpeaksFirst": false,
          "uninterruptible": false
        },
        "metadata": {},
        "createdAt": "2026-09-28T10:30:00.000Z",
        "updatedAt": "2026-09-28T10:30:00.000Z"
      }
    ]
  }
}

Lista assistenti

Crea un nuovo assistente preinizializzato per il cliente autenticato

​

Crea l'assistente replicando la stessa logica usata dal portale AI4Call.

Per un assistente classico sono richiesti solo name e description. Per un assistente audio-to-audio invia mode: audio_to_audio e, se vuoi sovrascrivere i valori predefiniti, il blocco canonico audioToAudio. La modalità legacy voice_to_voice e il campo voiceToVoice restano accettati per compatibilità.

Il backend esegue automaticamente:

  • generazione di assistantApiKey nel formato ai4call_sk_*
  • allocazione progressiva di jsonFilename nel formato FLLM*.json
  • generazione del virtualNumber demo nel formato 0000********
  • inizializzazione del JSON runtime con i default del portale
  • trigger di provisioning backend
  • tentativo best-effort di registrare l'assistente sul tenant MCP

Default iniziali:

  • TTS tts_live_azure_multi con voce it-IT-ElsaNeural
  • ASR asr_azure_multi
  • LLM openai con modello gpt-4o
  • primo messaggio non configurato (firstMessage.text vuoto)
  • prompt iniziale preconfigurato
  • stato iniziale draft

Se mode è audio_to_audio, il backend inizializza un JSON configType: voice-llm con root audio-to-audio compatibile con il portale.

Body·

required
application/json

Payload minimo di creazione. Il backend replica la logica del portale: genera assistantApiKey, virtualNumber e jsonFilename, inizializza il JSON runtime con i default AI4Call e avvia il provisioning dell'assistente. Il nome assistente viene normalizzato sostituendo gli spazi con _.

  • description
    Type: string
    min length:  
    1
    max length:  
    500
    required

    Descrizione funzionale dell'assistente.

  • name
    Type: string
    min length:  
    3
    max length:  
    100
    required

    Nome assistente. Se contiene spazi, il backend li converte automaticamente in _.

  • audioToAudio
    Type:
    deprecated

    Configurazione audio-to-audio iniziale, usata quando applicabile alla modalità selezionata.

    Properties: 6
  • mode
    Type: enum

    Modalità runtime da usare durante la creazione dell'assistente.

    values
    textaudio_to_audiovoice_to_voice
  • voiceToVoice
    Type:
    deprecated

    Alias legacy di audioToAudio.

    Properties: 6

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/api/v1/assistants
curl https://client-api.ai4call.com/api/v1/assistants \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "name": "Sales Assistant",
  "description": "Assistente demo per campagne commerciali inbound.",
  "mode": "text"
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistant": {
      "assistantId": "example-id",
      "id": "example-id",
      "apiKey": "sk_example",
      "clientEmail": "developer@example.com",
      "mode": "text",
      "name": "Example",
      "status": "draft",
      "numbers": {
        "demo": [
          "example"
        ],
        "purchased": [
          "example"
        ]
      },
      "network": {
        "allowedIps": [
          "203.0.113.10"
        ]
      },
      "settings": {
        "model": "example-model",
        "voice": "example-voice",
        "language": "it-IT",
        "timezone": "Europe/Rome",
        "recordingEnabled": true
      },
      "firstMessage": {
        "text": "",
        "callerSpeaksFirst": false,
        "uninterruptible": false
      },
      "metadata": {},
      "createdAt": "2026-09-28T10:30:00.000Z",
      "updatedAt": "2026-09-28T10:30:00.000Z"
    }
  }
}

Assistente creato

Recupera un assistente specifico del cliente autenticato

​

Recupera un assistente specifico del cliente autenticato

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/assistants/{assistantId}
curl https://client-api.ai4call.com/api/v1/assistants/205 \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistant": {
      "assistantId": "example-id",
      "id": "example-id",
      "apiKey": "sk_example",
      "clientEmail": "developer@example.com",
      "mode": "text",
      "name": "Example",
      "status": "draft",
      "numbers": {
        "demo": [
          "example"
        ],
        "purchased": [
          "example"
        ]
      },
      "network": {
        "allowedIps": [
          "203.0.113.10"
        ]
      },
      "settings": {
        "model": "example-model",
        "voice": "example-voice",
        "language": "it-IT",
        "timezone": "Europe/Rome",
        "recordingEnabled": true
      },
      "firstMessage": {
        "text": "",
        "callerSpeaksFirst": false,
        "uninterruptible": false
      },
      "metadata": {},
      "createdAt": "2026-09-28T10:30:00.000Z",
      "updatedAt": "2026-09-28T10:30:00.000Z"
    }
  }
}

Assistente trovato

Aggiorna metadati, stato e configurazione base dell'assistente

​

Aggiorna i campi generali dell'assistente.

Per gli assistenti text, il blocco firstMessage aggiorna il primo messaggio statico con semantica PATCH merge. Invia firstMessage.text: null o firstMessage.text: "" per eliminarlo.

Per gli assistenti audio-to-audio, il blocco canonico audioToAudio aggiorna il JSON voice-llm con semantica PATCH merge. Il campo legacy voiceToVoice resta accettato per compatibilità.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

Payload PATCH usato per aggiornare i campi modificabili dell'assistente.

  • audioToAudio
    Type:
    deprecated

    Aggiornamento parziale della configurazione audio-to-audio.

    Properties: 6
  • description
    Type: string | null
    max length:  
    500

    Nuova descrizione funzionale; null rimuove la descrizione corrente.

  • firstMessage
    Type:

    Aggiornamento parziale della configurazione del primo messaggio dell'assistente.

    Properties: 3
  • metadata
    Type: object

    Metadati liberi da memorizzare con l'assistente.

    Properties: 1
  • name
    Type: string
    min length:  
    3
    max length:  
    100

    Se contiene spazi, il backend li converte automaticamente in _.

  • network
    Type: object

    Impostazioni di rete da aggiornare sull'assistente.

    Properties: 1
  • numbers
    Type: object

    Valori sostitutivi per le liste di numeri dell'assistente quando inviati.

    Properties: 2
  • settings
    Type: object

    Impostazioni principali dell'assistente da aggiornare.

    Properties: 5
  • status
    Type: "draft" or "active" or "disabled"enum

    Nuovo stato del ciclo di vita dell'assistente.

  • voiceToVoice
    Type:
    deprecated

    Alias legacy di audioToAudio.

    Properties: 6

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}
curl https://client-api.ai4call.com/api/v1/assistants/205 \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "status": "active",
  "firstMessage": {
    "text": "Ciao, sono l'\''assistente virtuale. Come posso aiutarti?",
    "callerSpeaksFirst": false,
    "uninterruptible": false
  }
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistant": {
      "assistantId": "example-id",
      "id": "example-id",
      "apiKey": "sk_example",
      "clientEmail": "developer@example.com",
      "mode": "text",
      "name": "Example",
      "status": "draft",
      "numbers": {
        "demo": [
          "example"
        ],
        "purchased": [
          "example"
        ]
      },
      "network": {
        "allowedIps": [
          "203.0.113.10"
        ]
      },
      "settings": {
        "model": "example-model",
        "voice": "example-voice",
        "language": "it-IT",
        "timezone": "Europe/Rome",
        "recordingEnabled": true
      },
      "firstMessage": {
        "text": "",
        "callerSpeaksFirst": false,
        "uninterruptible": false
      },
      "metadata": {},
      "createdAt": "2026-09-28T10:30:00.000Z",
      "updatedAt": "2026-09-28T10:30:00.000Z"
    }
  }
}

Assistente aggiornato

Elimina un assistente

​

Elimina l'assistente, rilascia i numeri telefonici assegnati, rimuove il relativo JSON runtime e aggiorna la mappa di routing. L'eliminazione viene rifiutata se un altro assistente dello stesso account usa questo assistente come destinazione di trasferimento.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for delete/api/v1/assistants/{assistantId}
curl https://client-api.ai4call.com/api/v1/assistants/205 \
  --request DELETE \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant deleted successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "deleted": true
  }
}

Assistente eliminato

Aggiorna i numeri instradati sull'assistente

​

Aggiorna l'instradamento dei numeri del cliente su questo assistente, con semantica PATCH merge fra le tre liste.

Parametri modificabili:

  • demoNumbers
  • purchasedNumbers
  • userNumbers

Come recuperare i dati attuali:

  • usare GET /api/v1/catalog/assistants/{assistantApiKey}/number-routing per i numeri già assegnati e per quelli ancora liberi sull'account

Regole operative:

  • almeno una delle tre liste deve essere presente
  • una lista omessa mantiene il valore attuale
  • una lista presente sostituisce interamente la precedente: inviare [] per liberare tutti i numeri di quel tipo
  • assegnare un numero già instradato su un altro assistente lo sposta su questo

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

PATCH merge dei numeri instradati sull'assistente.

Regole operative:

  • almeno uno fra demoNumbers, purchasedNumbers e userNumbers deve essere presente
  • le liste omesse mantengono il valore attuale
  • ogni lista sostituisce interamente la precedente: per rimuovere tutti i numeri di un tipo, inviare []
  • si possono assegnare solo numeri già disponibili sull'account del cliente
  • un numero assegnato a un altro assistente viene spostato su questo
  • demoNumbers
    Type: array of string

    Numeri demo da instradare su questo assistente

  • purchasedNumbers
    Type: array of string

    Numeri acquistati da instradare su questo assistente

  • userNumbers
    Type: array of string

    Numeri propri del cliente (centralino proprio) da instradare su questo assistente

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/number-routing
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/number-routing \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "demoNumbers": [
    "+390211223344"
  ]
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "configuration": {
      "demoNumbers": [
        "example"
      ],
      "purchasedNumbers": [
        "example"
      ],
      "userNumbers": [
        "example"
      ]
    }
  }
}

Instradamento aggiornato

Elenca i numeri del cliente con il relativo stato di instradamento

​

Restituisce tutti i numeri del cliente, divisi in demo, acquistati e propri, ognuno con l'assistente su cui e attualmente instradato.

Da usare prima di PATCH /api/v1/assistants/{assistantApiKey}/runtime/number-routing per sapere quali numeri sono liberi e quali sono già assegnati altrove.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/assistants/{assistantId}/number-routing
curl https://client-api.ai4call.com/api/v1/catalog/assistants/205/number-routing \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant number routing configuration retrieved successfully.",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "configuration": {
      "demoNumbers": [
        {
          "phoneNumber": "+390211223344",
          "assistantApiKey": "ak_live_123",
          "assistantName": "Reception",
          "assignedToCurrentAssistant": true,
          "assignedAt": "2026-08-01T09:15:00.000Z"
        }
      ],
      "purchasedNumbers": [],
      "userNumbers": []
    }
  },
  "meta": {
    "demoCount": 1,
    "purchasedCount": 0,
    "userCount": 0,
    "totalCount": 1
  }
}

Numeri con il relativo stato di instradamento

Assistant Prompt

​

Prompt editabile dell'assistente, primo messaggio e relative opzioni

Assistant Prompt Operations

Recupera prompt editabile e configurazione primo messaggio dell'assistente

​

Restituisce la configurazione prompt dell'assistente nello stesso modello concettuale usato dal portale.

Cosa ritorna

  • prompt.text: solo la parte editabile del prompt
  • firstMessage.text: il primo messaggio statico, se presente
  • firstMessage.callerSpeaksFirst: opzione che indica se il chiamante parla per primo
  • firstMessage.uninterruptible: opzione che indica se il primo messaggio non può essere interrotto

Nota importante

Eventuali sezioni automatiche già presenti nel JSON, come blocchi di sistema o knowledge, non vengono restituite in prompt.text. Sugli assistenti voice_to_voice, prompt.text corrisponde al campo root prompt del JSON voice-llm; il primo messaggio non è usato.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/assistants/{assistantId}/prompt
curl https://client-api.ai4call.com/api/v1/assistants/205/prompt \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistantApiKey": "ai4call_sk_6asvqzto",
    "assistantId": "205",
    "configuration": {
      "prompt": {
        "text": "Sei un assistente commerciale cordiale e conciso. Rispondi in italiano."
      },
      "firstMessage": {
        "text": "Ciao, sono l'assistente virtuale di AI4Call. Come posso aiutarti?",
        "callerSpeaksFirst": false,
        "uninterruptible": false
      }
    }
  }
}

Configurazione prompt recuperata

Aggiorna prompt editabile e configurazione primo messaggio dell'assistente

​

Aggiorna la configurazione prompt dell'assistente con semantica PATCH merge.

Parametri modificabili:

  • prompt.text
  • firstMessage.text
  • firstMessage.callerSpeaksFirst
  • firstMessage.uninterruptible

Se aggiorni il prompt

  • Invia prompt.text
  • Il backend aggiorna solo la parte editabile
  • Eventuali sezioni automatiche già presenti nel JSON, come sistema e knowledge, restano preservate

Se aggiorni il primo messaggio

  • Invia firstMessage.text per impostarlo o sostituirlo
  • Invia firstMessage.text: null o "" per eliminarlo
  • Invia firstMessage.callerSpeaksFirst: true se vuoi che il chiamante parli per primo
  • Se callerSpeaksFirst=true, il backend elimina il primo messaggio statico e forza uninterruptible=false

Nota sul merge

  • I campi omessi mantengono il valore attuale
  • Puoi aggiornare solo il prompt, solo il primo messaggio, oppure entrambi nella stessa chiamata
  • sugli assistenti voice_to_voice, viene aggiornato solo prompt.text nel root JSON voice-llm; i campi firstMessage sono ignorati dal runtime audio-to-audio

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

Payload di aggiornamento prompt e primo messaggio.

Usa uno degli esempi qui sotto in base a quello che vuoi cambiare:

  • solo prompt
  • solo primo messaggio
  • switch a callerSpeaksFirst

PATCH merge della configurazione prompt dell'assistente.

Regole operative:

  • i campi omessi mantengono il valore attuale
  • prompt.text aggiorna solo la parte editabile del prompt
  • eventuali sezioni automatiche già presenti nel JSON, come sistema e knowledge, vengono preservate
  • per eliminare il primo messaggio statico, invia firstMessage.text: null oppure firstMessage.text: ""
  • se dopo il merge firstMessage.callerSpeaksFirst=true, il backend:
    • elimina il primo messaggio statico
    • forza firstMessage.uninterruptible=false
  • firstMessage
    Type: object

    Valore da inviare per firstMessage nella richiesta AssistantPromptUpdateRequest.

    Properties: 3
  • prompt
    Type: object

    Valore da inviare per prompt nella richiesta AssistantPromptUpdateRequest.

    Properties: 1

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/prompt
curl https://client-api.ai4call.com/api/v1/assistants/205/prompt \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "prompt": {
    "text": "Sei un assistente commerciale chiaro, breve e orientato alla conversione."
  }
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistantApiKey": "ai4call_sk_6asvqzto",
    "assistantId": "205",
    "configuration": {
      "prompt": {
        "text": "Sei un assistente commerciale cordiale e conciso. Rispondi in italiano."
      },
      "firstMessage": {
        "text": "Ciao, sono l'assistente virtuale di AI4Call. Come posso aiutarti?",
        "callerSpeaksFirst": false,
        "uninterruptible": false
      }
    }
  }
}

Configurazione prompt aggiornata

Provider Wallet

​

Credenziali provider del cliente, riusabili fra assistenti senza inviare chiavi in chiaro

Provider Wallet Operations

Elenca i provider che accettano credenziali proprie

​

Restituisce il catalogo dei provider supportati dal portafoglio, ognuno con i campi esatti richiesti per salvare una credenziale.

Da leggere prima di POST /api/v1/account/provider-wallet: serviceType, provider e engine del payload di creazione devono corrispondere a una di queste voci, e config accetta solo le chiavi elencate nei suoi fields.

ai4call: true indica un provider usabile anche tramite il listino AI4CALL, senza credenziali proprie; byok: true indica che accetta le tue credenziali.

Il catalogo e statico e non dipende dal cliente autenticato.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/provider-wallet/catalog
curl https://client-api.ai4call.com/api/v1/account/provider-wallet/catalog \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Provider wallet catalog retrieved successfully.",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "providers": [
      {
        "id": "llm:openai",
        "serviceType": "llm",
        "serviceLabel": "LLM",
        "provider": "openai",
        "engine": "openai",
        "label": "OpenAI",
        "description": "Modelli di punta della famiglia GPT e serie o",
        "ai4call": true,
        "byok": true,
        "fields": [
          {
            "key": "apiKey",
            "label": "API key",
            "type": "password",
            "required": true,
            "secret": true
          }
        ]
      }
    ]
  },
  "meta": {
    "count": 29
  }
}

Catalogo dei provider supportati

Elenca le credenziali salvate nel portafoglio

​

Restituisce le credenziali del cliente, ordinate per servizio e provider.

La configurazione non torna mai in chiaro: preview contiene i valori non segreti più i segreti troncati ai primi caratteri, quanto basta per distinguere due credenziali.

L'id di ogni credenziale è il valore da inviare come providerWalletId sugli endpoint runtime dell'assistente, al posto di mettere una API key nel payload.

Query Parameters

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di elementi restituiti in una pagina con paginazione a cursore. Ometti sia limit sia cursor per mantenere la risposta legacy non paginata.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor dalla pagina precedente.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/provider-wallet
curl https://client-api.ai4call.com/api/v1/account/provider-wallet \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Provider wallet credentials retrieved successfully.",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "credentials": [
      {
        "id": 42,
        "serviceType": "llm",
        "provider": "openai",
        "engine": "openai",
        "name": "OpenAI produzione",
        "isActive": true,
        "preview": {
          "apiKey": "sk-proj-ab**********"
        },
        "createdAt": "2026-08-01T09:15:00.000Z",
        "updatedAt": "2026-08-20T11:02:00.000Z"
      }
    ]
  },
  "meta": {
    "count": 1
  }
}

Credenziali salvate

Salva una nuova credenziale nel portafoglio

​

Salva una credenziale provider. Il valore viene cifrato a riposo e non torna mai in chiaro.

Come costruire il payload:

  • leggere GET /api/v1/account/provider-wallet/catalog
  • copiare serviceType, provider e engine dalla voce scelta
  • riempire config con le chiavi elencate nei fields di quella voce

Regole operative:

  • config accetta solo le chiavi dichiarate: qualsiasi altra chiave restituisce 400
  • ogni campo marcato required deve essere presente e non vuoto
  • i campi con options accettano solo i valori elencati
  • name e testo libero, serve a riconoscere la credenziale in seguito

L'id nella risposta è il valore da usare come providerWalletId sui runtime dell'assistente.

Body·

required
application/json

Creazione di una credenziale nel portafoglio.

Regole operative:

  • serviceType, provider e engine devono corrispondere a una voce restituita da GET /api/v1/account/provider-wallet/catalog
  • config accetta solo le chiavi dichiarate nei fields di quella voce; ogni altra chiave viene rifiutata
  • ogni campo marcato required deve essere presente e non vuoto
  • config
    Type: object
    required

    Valori dei campi dichiarati dalla voce di catalogo

    Properties: 1
  • engine
    Type: string
    required

    Codice engine selezionato dal catalogo provider wallet.

  • name
    Type: string
    max length:  
    120
    required

    Nome definito dal cliente per la credenziale salvata.

  • provider
    Type: string
    required

    Codice provider selezionato dal catalogo provider wallet.

  • serviceType
    Type: enum
    required

    Categoria di servizio selezionata dal catalogo provider wallet.

    values
    llmttsasrvoice_llm

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/api/v1/account/provider-wallet
curl https://client-api.ai4call.com/api/v1/account/provider-wallet \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "serviceType": "llm",
  "provider": "openai",
  "engine": "openai",
  "name": "OpenAI produzione",
  "config": {
    "apiKey": "sk-proj-example"
  }
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "credential": {
      "id": 42,
      "serviceType": "llm",
      "provider": "openai",
      "engine": "openai",
      "name": "OpenAI produzione",
      "isActive": true,
      "preview": {
        "apiKey": "sk-proj-ab**********"
      },
      "createdAt": "2026-09-28T10:30:00.000Z",
      "updatedAt": "2026-09-28T10:30:00.000Z"
    }
  }
}

Credenziale salvata

Elenca le credenziali del portafoglio associate a un assistente

​

Restituisce quale credenziale sta usando ogni runtime dell'assistente, una voce per scopeKey (per esempio il llm, il tts, l'asr).

Gli endpoint runtime riportano solo hasProviderWallet, un booleano: qui si scopre quale credenziale e applicata.

Le associazioni non si scrivono qui: si creano inviando providerWalletId sull'endpoint runtime corrispondente, e si rimuovono inviando providerWalletId: null.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/provider-wallet/assistants/{assistantId}
curl https://client-api.ai4call.com/api/v1/account/provider-wallet/assistants/205 \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant provider wallet associations retrieved successfully.",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "associations": [
      {
        "assistantApiKey": "ai4call_sk_abc123",
        "scopeKey": "llm",
        "serviceType": "llm",
        "provider": "openai",
        "engine": "openai",
        "providerWalletId": 42,
        "walletName": "OpenAI produzione",
        "createdAt": "2026-08-01T09:15:00.000Z",
        "updatedAt": "2026-08-20T11:02:00.000Z"
      }
    ]
  },
  "meta": {
    "count": 1
  }
}

Associazioni dell'assistente

Recupera una credenziale dal portafoglio

​

Restituisce una singola credenziale. Come nell'elenco, la configurazione torna solo come preview, con i segreti mascherati.

Path Parameters

  • providerWalletId
    Type: integer
    min:  
    1
    required

    Id della credenziale, restituito alla creazione o dall'endpoint di elenco

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/provider-wallet/{providerWalletId}
curl https://client-api.ai4call.com/api/v1/account/provider-wallet/42 \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "credential": {
      "id": 42,
      "serviceType": "llm",
      "provider": "openai",
      "engine": "openai",
      "name": "OpenAI produzione",
      "isActive": true,
      "preview": {
        "apiKey": "sk-proj-ab**********"
      },
      "createdAt": "2026-09-28T10:30:00.000Z",
      "updatedAt": "2026-09-28T10:30:00.000Z"
    }
  }
}

Credenziale trovata

Aggiorna una credenziale nel portafoglio

​

Aggiorna una credenziale con semantica PATCH merge.

Parametri modificabili:

  • name
  • isActive
  • config

Regole operative:

  • almeno uno dei tre deve essere presente
  • serviceType, provider e engine non si cambiano: per cambiare provider si crea una nuova credenziale
  • dentro config, un campo omesso o vuoto conserva il valore già salvato. E questo che permette di rinominare una credenziale senza reinviare una API key che il client non può mai rileggere
  • disattivare con isActive: false conserva la credenziale ma smette di applicarla ai runtime

Path Parameters

  • providerWalletId
    Type: integer
    min:  
    1
    required

    Id della credenziale, restituito alla creazione o dall'endpoint di elenco

Body·

required
application/json

PATCH merge di una credenziale.

Regole operative:

  • almeno uno fra name, isActive e config deve essere presente
  • serviceType, provider e engine non si cambiano: per cambiare provider si crea una nuova credenziale
  • dentro config, un campo omesso o vuoto conserva il valore già salvato - utile per i segreti, che il client non può mai rileggere
  • config
    Type: object

    Campi credenziali da unire alla configurazione salvata.

    Properties: 1
  • isActive
    Type: boolean

    Indica se la credenziale salvata può essere usata dai runtime degli assistenti.

  • name
    Type: string
    max length:  
    120

    Nuovo nome della credenziale definito dal cliente.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/account/provider-wallet/{providerWalletId}
curl https://client-api.ai4call.com/api/v1/account/provider-wallet/42 \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "name": "OpenAI produzione (rinnovata)"
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "credential": {
      "id": 42,
      "serviceType": "llm",
      "provider": "openai",
      "engine": "openai",
      "name": "OpenAI produzione",
      "isActive": true,
      "preview": {
        "apiKey": "sk-proj-ab**********"
      },
      "createdAt": "2026-09-28T10:30:00.000Z",
      "updatedAt": "2026-09-28T10:30:00.000Z"
    }
  }
}

Credenziale aggiornata

Elimina una credenziale dal portafoglio

​

Elimina definitivamente la credenziale e ogni associazione con gli assistenti del cliente.

Gli assistenti coinvolti tornano a usare i valori scritti direttamente nella propria configurazione; non vengono fermati. Se serve sapere quali sono, controllare prima le associazioni con GET /api/v1/account/provider-wallet/assistants/{assistantApiKey}.

Path Parameters

  • providerWalletId
    Type: integer
    min:  
    1
    required

    Id della credenziale, restituito alla creazione o dall'endpoint di elenco

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for delete/api/v1/account/provider-wallet/{providerWalletId}
curl https://client-api.ai4call.com/api/v1/account/provider-wallet/42 \
  --request DELETE \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "deleted": true
  }
}

Credenziale eliminata

Catalog TTS

​

Provider TTS, voci e aggiornamento runtime TTS dell'assistente

Catalog TTS Operations

Aggiorna la configurazione runtime TTS dell'assistente

​

Aggiorna la configurazione runtime TTS dell'assistente con semantica PATCH merge.

Parametri modificabili:

  • sourceMode
  • engineCode
  • voiceCode
  • apiKey
  • region

Se usi ai4call

  • Invia sourceMode: ai4call
  • Invia voiceCode
  • engineCode è opzionale
  • Non inviare apiKey
  • Non inviare region

Se usi customer

  • Invia sourceMode: customer
  • Invia engineCode
  • Invia voiceCode
  • Invia apiKey
  • Se usi Azure, invia anche region

Nota sul merge

  • I campi omessi mantengono il valore attuale, se già presente
  • La risposta restituisce la configurazione finale risultante

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

Scegli uno degli esempi qui sotto in base alla modalità che vuoi impostare.

  • ai4call: selezione di una voce dal catalogo AI4Call
  • customer: configurazione diretta con parametri del provider del cliente

PATCH merge della configurazione TTS dell'assistente.

Regole operative:

  • sourceMode e sempre obbligatorio
  • i campi omessi mantengono il valore corrente già salvato, se presente
  • in ai4call il backend risolve la configurazione partendo dalla voiceCode
  • in customer la configurazione usa i parametri diretti del cliente

Vincoli applicativi:

  • customer: engineCode, voiceCode e apiKey devono risultare valorizzati dopo il merge
  • customer con Azure: region deve risultare valorizzata dopo il merge
  • ai4call: usare voiceCode; engineCode e facoltativo e serve solo come controllo di coerenza
  • sourceMode
    Type: "ai4call" or "customer"enum
    required

    modalità di sourcing runtime.

    • ai4call: usa un provider/modello presente nei listini AI4Call del cliente
    • customer: usa credenziali e configurazione diretta del cliente
  • apiKey
    Type: string | null
    write-only

    API key del provider TTS del cliente. Va inviata solo in customer. In ai4call va omessa.

  • engineCode
    Type: string | null

    Codice engine/provider TTS. In customer identifica il motore da usare. In ai4call è opzionale e, se inviato, viene usato solo per verificare che la voiceCode appartenga a quell'engine.

  • providerWalletId
    Type: integer | null

    Id di una credenziale salvata nel portafoglio provider del cliente, da usare al posto dell'invio di apiKey in chiaro.

    Quando è presente, le credenziali vengono lette dal portafoglio, applicate al runtime e l'associazione viene salvata sull'assistente. null rimuove l'associazione e torna ai valori inviati esplicitamente.

    Le credenziali del portafoglio si creano e si gestiscono dal portale AI4CALL.

  • region
    Type: string | null

    Regione/provider area richiesta da alcuni engine customer, in particolare Azure. Obbligatoria per Azure in customer. In ai4call va omessa.

  • voiceCode
    Type: string | null

    Codice voce TTS. In ai4call è il parametro principale per selezionare la voce dal catalogo AI4Call. In customer deve identificare la voce valida per il provider/engine scelto.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/tts
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/tts \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "sourceMode": "ai4call",
  "voiceCode": "it-IT-DiegoNeural"
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistantApiKey": "ai4call_sk_example",
    "assistantId": "example-id",
    "service": "tts",
    "configuration": {
      "sourceMode": "ai4call",
      "hasApiKey": true
    },
    "runtimeBinding": {
      "configured": true,
      "sourceMode": "ai4call"
    }
  }
}

Configurazione runtime TTS aggiornata

Elenca i provider TTS disponibili per il cliente

​

Elenca i provider TTS disponibili per il cliente

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/providers/tts
curl https://client-api.ai4call.com/api/v1/catalog/providers/tts \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "TTS providers retrieved successfully.",
  "requestId": "5f6ca30b-7046-416e-b4da-e149833885e2",
  "meta": {
    "count": 3
  },
  "data": {
    "providers": [
      {
        "providerId": "azure",
        "providerLabel": "Azure",
        "engineCode": "tts_live_azure_multi",
        "serviceType": "tts",
        "availableModes": [
          "ai4call",
          "customer"
        ],
        "itemCount": 530
      },
      {
        "providerId": "elevenlabs",
        "providerLabel": "ElevenLabs",
        "engineCode": "tts_live_eleven_multi",
        "serviceType": "tts",
        "availableModes": [
          "customer"
        ],
        "itemCount": 2793
      }
    ]
  }
}

Lista provider TTS

Elenca le voci TTS risolte dalla configurazione runtime dell'assistente

​

Elenca le voci TTS risolte dalla configurazione runtime dell'assistente

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/assistants/{assistantId}/tts/voices
curl https://client-api.ai4call.com/api/v1/catalog/assistants/205/tts/voices \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant TTS voices retrieved successfully.",
  "requestId": "00421620-08b4-473d-b703-2d7df18d0f5a",
  "meta": {
    "count": 530
  },
  "data": {
    "voices": [
      {
        "voiceId": "1",
        "voiceCode": "it-IT-DiegoNeural",
        "voiceLabel": "Diego - Italian (Italy)",
        "providerId": "azure",
        "providerLabel": "Azure",
        "engineCode": "tts_live_azure_multi",
        "language": "it-IT",
        "region": null,
        "price": 0.008,
        "sourceMode": "ai4call",
        "catalogOrigin": "ai4call_pricing",
        "previewUrl": null
      }
    ]
  }
}

Lista voci TTS dell'assistente

Catalog ASR

​

Provider ASR, modelli e aggiornamento runtime ASR dell'assistente

Catalog ASR Operations

Aggiorna la configurazione runtime ASR dell'assistente

​

Aggiorna la configurazione runtime ASR dell'assistente con semantica PATCH merge.

Parametri modificabili:

  • sourceMode
  • engineCode
  • apiKey

Se usi ai4call

  • Invia sourceMode: ai4call
  • Invia engineCode
  • Non inviare apiKey

Se usi customer

  • Invia sourceMode: customer
  • Invia engineCode
  • Invia apiKey

Nota sul merge

  • I campi omessi mantengono il valore attuale, se già presente
  • La risposta restituisce la configurazione finale risultante

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

Scegli uno degli esempi qui sotto in base alla modalità che vuoi impostare.

  • ai4call: selezione di un engine ASR dal catalogo AI4Call
  • customer: configurazione diretta con engine e API key del cliente

PATCH merge della configurazione ASR dell'assistente.

Regole operative:

  • sourceMode e sempre obbligatorio
  • i campi omessi mantengono il valore corrente già salvato, se presente
  • in ai4call il backend seleziona un engine disponibile dai listini AI4Call del cliente
  • in customer la configurazione usa i parametri diretti del cliente

Vincoli applicativi:

  • customer: engineCode e apiKey devono risultare valorizzati dopo il merge
  • ai4call: engineCode deve identificare un engine disponibile nel catalogo AI4Call del cliente
  • sourceMode
    Type: "ai4call" or "customer"enum
    required

    modalità di sourcing runtime.

    • ai4call: usa un engine ASR presente nei listini AI4Call del cliente
    • customer: usa credenziali e configurazione diretta del cliente
  • apiKey
    Type: string | null
    write-only

    API key del provider ASR del cliente. Va inviata solo in customer. In ai4call va omessa.

  • engineCode
    Type: string | null

    Codice engine/provider ASR. In ai4call identifica l'engine AI4Call da associare. In customer identifica l'engine del provider del cliente.

  • providerWalletId
    Type: integer | null

    Id di una credenziale salvata nel portafoglio provider del cliente, da usare al posto dell'invio di apiKey in chiaro.

    Quando è presente, le credenziali vengono lette dal portafoglio, applicate al runtime e l'associazione viene salvata sull'assistente. null rimuove l'associazione e torna ai valori inviati esplicitamente.

    Le credenziali del portafoglio si creano e si gestiscono dal portale AI4CALL.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/asr
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/asr \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "sourceMode": "ai4call",
  "engineCode": "asr_azure_multi"
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistantApiKey": "ai4call_sk_example",
    "assistantId": "example-id",
    "service": "asr",
    "configuration": {
      "sourceMode": "ai4call",
      "hasApiKey": true
    },
    "runtimeBinding": {
      "configured": true,
      "sourceMode": "ai4call"
    }
  }
}

Configurazione runtime ASR aggiornata

Elenca i provider ASR disponibili per il cliente

​

Elenca i provider ASR disponibili per il cliente

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/providers/asr
curl https://client-api.ai4call.com/api/v1/catalog/providers/asr \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "providers": [
      {
        "providerId": "openai",
        "providerLabel": "openai",
        "serviceType": "tts",
        "availableModes": [
          "ai4call"
        ]
      }
    ]
  }
}

Lista provider ASR

Elenca i modelli ASR risolti dalla configurazione runtime dell'assistente

​

Elenca i modelli ASR risolti dalla configurazione runtime dell'assistente

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/assistants/{assistantId}/asr/models
curl https://client-api.ai4call.com/api/v1/catalog/assistants/205/asr/models \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant ASR models retrieved successfully.",
  "requestId": "cbdebd8b-8904-4463-bbef-3c5751dc2087",
  "meta": {
    "count": 1
  },
  "data": {
    "models": [
      {
        "modelId": "1",
        "modelCode": "asr_azure_multi",
        "modelLabel": "asr_azure_multi",
        "providerId": "azure",
        "providerLabel": "AZURE",
        "supportedLanguages": [
          "it-IT"
        ],
        "price": 0.005,
        "sourceMode": "ai4call",
        "catalogOrigin": "ai4call_pricing"
      }
    ]
  }
}

Lista modelli ASR dell'assistente

Catalog LLM

​

Provider LLM, modelli e aggiornamento runtime LLM dell'assistente

Catalog LLM Operations

Aggiorna la configurazione runtime LLM dell'assistente

​

Aggiorna la configurazione runtime LLM dell'assistente con semantica PATCH merge.

Parametri modificabili:

  • sourceMode
  • engineCode
  • modelCode
  • apiKey
  • baseUrl

Se usi ai4call

  • Invia sourceMode: ai4call
  • Invia modelCode
  • engineCode è opzionale
  • Non inviare apiKey
  • Non inviare baseUrl

Se usi customer

  • Invia sourceMode: customer
  • Invia engineCode
  • Invia modelCode
  • Se engineCode = ollama, invia baseUrl
  • Per tutti gli altri engine, invia apiKey

Nota sul merge

  • I campi omessi mantengono il valore attuale, se già presente
  • La risposta restituisce la configurazione finale risultante

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

Scegli uno degli esempi qui sotto in base alla modalità che vuoi impostare.

  • ai4call: selezione di un modello dal catalogo AI4Call
  • customer: configurazione diretta con provider del cliente

PATCH merge della configurazione LLM dell'assistente.

Regole operative:

  • sourceMode e sempre obbligatorio
  • i campi omessi mantengono il valore corrente già salvato, se presente
  • in ai4call il backend risolve la configurazione partendo dalla modelCode
  • in customer la configurazione usa i parametri diretti del cliente

Vincoli applicativi:

  • customer: engineCode e modelCode devono risultare valorizzati dopo il merge
  • customer con ollama: baseUrl deve risultare valorizzata dopo il merge
  • customer con engine diversi da ollama: apiKey deve risultare valorizzata dopo il merge
  • ai4call: usare modelCode; engineCode e facoltativo e serve solo come controllo di coerenza
  • sourceMode
    Type: "ai4call" or "customer"enum
    required

    modalità di sourcing runtime.

    • ai4call: usa un modello presente nei listini AI4Call del cliente
    • customer: usa credenziali e configurazione diretta del cliente
  • apiKey
    Type: string | null
    write-only

    API key del provider LLM del cliente. Va inviata in customer per i provider che la richiedono. Per ollama normalmente non serve. In ai4call va omessa.

  • baseUrl
    Type: string | null

    Base URL custom del provider LLM. Tipicamente usata per ollama o per endpoint compatibili OpenAI self-hosted. In customer con ollama è obbligatoria. In ai4call va omessa.

  • engineCode
    Type: string | null

    Codice engine/provider LLM. In customer identifica il provider da usare. In ai4call è opzionale e, se inviato, viene usato solo per verificare che il modelCode appartenga a quell'engine.

  • modelCode
    Type: string | null

    Codice modello LLM. In ai4call è il parametro principale per selezionare il modello dal catalogo AI4Call. In customer deve identificare il modello valido per il provider scelto.

  • providerWalletId
    Type: integer | null

    Id di una credenziale salvata nel portafoglio provider del cliente, da usare al posto dell'invio di apiKey in chiaro.

    Quando è presente, le credenziali vengono lette dal portafoglio, applicate al runtime e l'associazione viene salvata sull'assistente. null rimuove l'associazione e torna ai valori inviati esplicitamente.

    Le credenziali del portafoglio si creano e si gestiscono dal portale AI4CALL.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/llm
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/llm \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "sourceMode": "ai4call",
  "modelCode": "gpt-4.1-mini"
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistantApiKey": "ai4call_sk_example",
    "assistantId": "example-id",
    "service": "llm",
    "configuration": {
      "sourceMode": "ai4call",
      "hasApiKey": true
    },
    "runtimeBinding": {
      "configured": true,
      "sourceMode": "ai4call"
    }
  }
}

Configurazione runtime LLM aggiornata

Elenca i provider LLM disponibili per il cliente

​

Elenca i provider LLM disponibili per il cliente

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/providers/llm
curl https://client-api.ai4call.com/api/v1/catalog/providers/llm \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "providers": [
      {
        "providerId": "openai",
        "providerLabel": "openai",
        "serviceType": "tts",
        "availableModes": [
          "ai4call"
        ]
      }
    ]
  }
}

Lista provider LLM

Elenca i modelli LLM risolti dalla configurazione runtime dell'assistente

​

Elenca i modelli LLM risolti dalla configurazione runtime dell'assistente

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/assistants/{assistantId}/llm/models
curl https://client-api.ai4call.com/api/v1/catalog/assistants/205/llm/models \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant LLM models retrieved successfully.",
  "requestId": "dc4d2d62-0fd3-4b4f-8bf7-1c1d9509966d",
  "meta": {
    "count": 2
  },
  "data": {
    "models": [
      {
        "modelId": "16",
        "modelCode": "gpt-4.1-mini",
        "modelLabel": "GPT-4.1 mini",
        "providerId": "openai",
        "providerLabel": "openai",
        "inputPrice": 0.15,
        "outputPrice": 0.6,
        "sourceMode": "ai4call",
        "catalogOrigin": "ai4call_pricing"
      }
    ]
  }
}

Lista modelli LLM dell'assistente

Catalog Audio-to-Audio

​

Provider, modelli, voci e runtime canonici per assistenti audio-to-audio

Catalog Audio-to-Audio Operations

Aggiorna la configurazione runtime audio-to-audio dell'assistente

​

Rotta canonica per gli assistenti realtime audio-to-audio.

PATCH /api/v1/assistants/{assistantApiKey}/runtime/voice-to-voice resta come alias storico: stesso handler, stesso payload, stessa risposta.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

PATCH merge della configurazione runtime audio-to-audio.

Aggiorna il JSON del server configType: voice-llm. Deve essere presente almeno un campo tra engineCode, modelCode, voiceCode, providerWalletId, apiKey, baseUrl o prompt.

  • apiKey
    Type: string | null
    write-only

    API key provider cliente. Invia null per rimuoverla dal JSON.

  • baseUrl
    Type: string | null

    Base URL custom. Invia null per rimuoverla dal JSON.

  • engineCode
    Type: string

    Provider/engine voice LLM.

  • modelCode
    Type: string

    Codice modello voice LLM.

  • prompt
    Type: string

    Prompt principale del runtime audio-to-audio.

  • providerWalletId
    Type: integer | null

    Id di una credenziale salvata nel portafoglio provider del cliente, da usare al posto dell'invio di apiKey in chiaro.

    Quando è presente, le credenziali vengono lette dal portafoglio, applicate al runtime e l'associazione viene salvata sull'assistente. null rimuove l'associazione e torna ai valori inviati esplicitamente.

    Le credenziali del portafoglio si creano e si gestiscono dal portale AI4CALL.

  • voiceCode
    Type: string

    Codice voce del modello.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/audio-to-audio
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/audio-to-audio \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "engineCode": "openai",
  "modelCode": "gpt-4o-realtime-preview",
  "voiceCode": "alloy"
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistantApiKey": "ai4call_sk_example",
    "assistantId": "example-id",
    "service": "audio-to-audio",
    "configuration": {
      "engineCode": "openai",
      "modelCode": "example-model",
      "voiceCode": "example-voice",
      "baseUrl": "https://example.com",
      "hasApiKey": true,
      "prompt": "example"
    }
  }
}

Runtime audio-to-audio aggiornato

Elenca i provider voice LLM disponibili per il cliente

​

Elenca i provider voice LLM disponibili per il cliente

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/providers/audio-to-audio
curl https://client-api.ai4call.com/api/v1/catalog/providers/audio-to-audio \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "providers": [
      {
        "providerId": "openai",
        "providerLabel": "openai",
        "serviceType": "tts",
        "availableModes": [
          "ai4call"
        ]
      }
    ]
  }
}

Lista provider voice LLM

Elenca i modelli voice LLM

​

Elenca i modelli voice LLM

Query Parameters

  • provider
    Type: string
    required
  • sourceMode
    Type: "ai4call" or "customer"enum

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/audio-to-audio/models
curl 'https://client-api.ai4call.com/api/v1/catalog/audio-to-audio/models?provider=openai&sourceMode=ai4call' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "models": [
      {
        "modelId": "example-model",
        "modelCode": "example-model",
        "modelLabel": "example-model",
        "providerId": "openai",
        "providerLabel": "openai",
        "sourceMode": "ai4call",
        "catalogOrigin": "ai4call_pricing"
      }
    ]
  }
}

Lista modelli voice LLM

Elenca le voci disponibili per un modello voice LLM

​

Elenca le voci disponibili per un modello voice LLM

Query Parameters

  • modelCode
    Type: string
    required

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/audio-to-audio/voices
curl 'https://client-api.ai4call.com/api/v1/catalog/audio-to-audio/voices?modelCode=gpt-4o-realtime-preview' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "voices": [
      {
        "voiceId": "example-voice",
        "voiceCode": "example-voice",
        "voiceLabel": "example-voice",
        "modelCode": "example-model",
        "providerId": "openai",
        "providerLabel": "openai"
      }
    ]
  }
}

Lista voci voice LLM

Elenca i modelli voice LLM coerenti con l'assistente

​

Elenca i modelli voice LLM coerenti con l'assistente

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/assistants/{assistantId}/audio-to-audio/models
curl https://client-api.ai4call.com/api/v1/catalog/assistants/205/audio-to-audio/models \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "models": [
      {
        "modelId": "example-model",
        "modelCode": "example-model",
        "modelLabel": "example-model",
        "providerId": "openai",
        "providerLabel": "openai",
        "sourceMode": "ai4call",
        "catalogOrigin": "ai4call_pricing"
      }
    ]
  }
}

Lista modelli voice LLM dell'assistente

Elenca le voci voice LLM disponibili per un assistente

​

Elenca le voci voice LLM disponibili per un assistente

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Query Parameters

  • modelCode
    Type: string
    required

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/assistants/{assistantId}/audio-to-audio/voices
curl 'https://client-api.ai4call.com/api/v1/catalog/assistants/205/audio-to-audio/voices?modelCode=gpt-4o-realtime-preview' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "voices": [
      {
        "voiceId": "example-voice",
        "voiceCode": "example-voice",
        "voiceLabel": "example-voice",
        "modelCode": "example-model",
        "providerId": "openai",
        "providerLabel": "openai"
      }
    ]
  }
}

Lista voci voice LLM dell'assistente

Catalog DTMF

​

Configurazione DTMF dell'assistente e aggiornamento runtime DTMF

Catalog DTMF Operations

Aggiorna la configurazione runtime DTMF dell'assistente

​

Aggiorna la configurazione DTMF dell'assistente con semantica PATCH merge.

Parametri modificabili:

  • enabled
  • playEnabled
  • acceptTimeout
  • minLength
  • maxLength
  • terminationChars

Come recuperare i dati correnti:

  • usa GET /api/v1/catalog/assistants/{assistantApiKey}/dtmf

Regole operative:

  • se vuoi modificare un solo campo, invia solo quel campo
  • enabled: false resetta tutti i settings DTMF
  • playEnabled resta indipendente dal toggle DTMF ricevuto
  • sugli assistenti voice_to_voice il backend aggiorna dtmf e pbxTools.dtmf/playDtmf nel JSON voice-llm

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

PATCH merge della configurazione DTMF dell'assistente.

Regole operative:

  • almeno uno tra enabled, playEnabled, acceptTimeout, minLength, maxLength, terminationChars deve essere presente
  • i campi omessi mantengono il valore corrente
  • inviando uno dei settings DTMF con enabled omesso, il DTMF viene considerato abilitato
  • enabled: false resetta acceptTimeout, minLength, maxLength e terminationChars
  • playEnabled controlla l'invio DTMF durante la chiamata
  • acceptTimeout
    Type: integer | null
    min:  
    0

    Valore da inviare per acceptTimeout nella richiesta AssistantDtmfRuntimeUpdateRequest.

  • enabled
    Type: boolean

    Abilita o disabilita la ricezione DTMF.

  • maxLength
    Type: integer | null
    min:  
    0

    Valore da inviare per maxLength nella richiesta AssistantDtmfRuntimeUpdateRequest.

  • minLength
    Type: integer | null
    min:  
    0

    Valore da inviare per minLength nella richiesta AssistantDtmfRuntimeUpdateRequest.

  • playEnabled
    Type: boolean

    Abilita o disabilita l'invio DTMF durante la chiamata.

  • terminationChars
    Type: string | null

    Valore da inviare per terminationChars nella richiesta AssistantDtmfRuntimeUpdateRequest.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/dtmf
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/dtmf \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "enabled": true,
  "acceptTimeout": 3000,
  "minLength": 1,
  "maxLength": 6,
  "terminationChars": "#"
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistantApiKey": "ai4call_sk_example",
    "assistantId": "example-id",
    "service": "dtmf",
    "configuration": {
      "enabled": true,
      "playEnabled": true,
      "acceptTimeout": 1,
      "minLength": 1,
      "maxLength": 1,
      "terminationChars": "example"
    }
  }
}

Configurazione runtime DTMF aggiornata

Recupera la configurazione DTMF dell'assistente

​

Recupera la configurazione DTMF dell'assistente

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/assistants/{assistantId}/dtmf
curl https://client-api.ai4call.com/api/v1/catalog/assistants/205/dtmf \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant DTMF configuration retrieved successfully.",
  "requestId": "4d5581dd-efce-440d-92a6-23444e9cd84f",
  "data": {
    "configuration": {
      "enabled": true,
      "playEnabled": false,
      "acceptTimeout": 3000,
      "minLength": 1,
      "maxLength": 6,
      "terminationChars": "#"
    }
  }
}

Configurazione DTMF dell'assistente

Catalog Settings

​

Settings e advanced settings dell'assistente

Catalog Settings Operations

Aggiorna i settings dell'assistente

​

Aggiorna i settings dell'assistente con semantica PATCH merge.

Parametri modificabili:

  • asrSilenceMs
  • asrInitialDelayMs
  • truncateInitialAudio
  • dynamicTimeoutMs
  • vad
  • vadThreshold
  • vadMinVoiceMs
  • ttsInterruptionInConversation
  • filler.enabled
  • filler.delayMs
  • filler.waitingListIds
  • filler.toolListIds
  • filler.waiting
  • filler.tool
  • reprompt.enabled
  • reprompt.mode
  • reprompt.text
  • reprompt.repeatMaxLength
  • reprompt.maxRetries
  • maxResponseLength
  • callPermissions.checkVerifyNumber
  • callPermissions.allowForeignNumbers
  • callPermissions.allowInternationalNumbers
  • callPermissions.allowMobileNumbers
  • callPermissions.allowFixedNumbers
  • callPermissions.country
  • callPermissions.prefixMobile
  • callPermissions.prefixFixed

Come recuperare i dati correnti:

  • usa GET /api/v1/catalog/assistants/{assistantApiKey}/settings

Regole operative:

  • se vuoi modificare un solo campo, invia solo quel campo
  • filler, reprompt e callPermissions fanno merge solo dei campi presenti
  • country, prefixMobile e prefixFixed possono essere impostati a null
  • sugli assistenti voice_to_voice, i settings conversazionali vengono scritti nel root JSON voice-llm; i permessi chiamata restano su DB come nel portale

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

PATCH merge dei settings dell'assistente.

Come recuperare i dati correnti:

  • usa GET /api/v1/catalog/assistants/{assistantApiKey}/settings

Regole operative:

  • invia solo i campi da modificare
  • filler, reprompt e callPermissions usano merge parziale sui campi inviati
  • callPermissions usa merge parziale sui campi inviati
  • country, prefixMobile e prefixFixed possono essere inviati a null per rimuovere il valore salvato
  • asrInitialDelayMs
    Type: integer
    min:  
    0
    max:  
    10000

    Valore da inviare per asrInitialDelayMs nella richiesta AssistantSettingsRuntimeUpdateRequest.

  • asrSilenceMs
    Type: integer
    min:  
    500
    max:  
    5000

    Valore da inviare per asrSilenceMs nella richiesta AssistantSettingsRuntimeUpdateRequest.

  • callPermissions
    Type: object

    Valore da inviare per callPermissions nella richiesta AssistantSettingsRuntimeUpdateRequest.

    Properties: 8
  • dynamicTimeoutMs
    Type: integer
    min:  
    5000
    max:  
    300000

    Valore da inviare per dynamicTimeoutMs nella richiesta AssistantSettingsRuntimeUpdateRequest.

  • filler
    Type: object

    Valore da inviare per filler nella richiesta AssistantSettingsRuntimeUpdateRequest.

    Properties: 6
  • maxResponseLength
    Type: integer
    min:  
    1000
    max:  
    10000000

    Valore da inviare per maxResponseLength nella richiesta AssistantSettingsRuntimeUpdateRequest.

  • reprompt
    Type: object

    Valore da inviare per reprompt nella richiesta AssistantSettingsRuntimeUpdateRequest.

    Properties: 5
  • truncateInitialAudio
    Type: boolean

    Valore da inviare per truncateInitialAudio nella richiesta AssistantSettingsRuntimeUpdateRequest.

  • ttsInterruptionInConversation
    Type: boolean

    Valore da inviare per ttsInterruptionInConversation nella richiesta AssistantSettingsRuntimeUpdateRequest.

  • vad
    Type: boolean

    Valore da inviare per vad nella richiesta AssistantSettingsRuntimeUpdateRequest.

  • vadMinVoiceMs
    Type: integer
    min:  
    0

    Valore da inviare per vadMinVoiceMs nella richiesta AssistantSettingsRuntimeUpdateRequest.

  • vadThreshold
    Type: numberFormat: float
    min:  
    0
    max:  
    1

    Valore da inviare per vadThreshold nella richiesta AssistantSettingsRuntimeUpdateRequest.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/settings
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/settings \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "asrSilenceMs": 750,
  "asrInitialDelayMs": 250,
  "dynamicTimeoutMs": 12000,
  "vad": true,
  "vadThreshold": 0.55,
  "vadMinVoiceMs": 180,
  "truncateInitialAudio": false
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistantApiKey": "ai4call_sk_example",
    "assistantId": "example-id",
    "service": "settings",
    "configuration": {
      "asrSilenceMs": 1,
      "asrInitialDelayMs": 1,
      "truncateInitialAudio": true,
      "dynamicTimeoutMs": 1,
      "vad": true,
      "vadThreshold": 1,
      "vadMinVoiceMs": 1,
      "ttsInterruptionInConversation": true,
      "filler": {
        "enabled": true,
        "delayMs": 1,
        "waitingListIds": [
          "example"
        ],
        "toolListIds": [
          "example"
        ],
        "waiting": [
          "example"
        ],
        "tool": [
          "example"
        ]
      },
      "reprompt": {
        "enabled": true,
        "mode": "llm",
        "text": [
          "example"
        ],
        "repeatMaxLength": 1,
        "maxRetries": 1
      },
      "maxResponseLength": 1,
      "callPermissions": {
        "checkVerifyNumber": true,
        "allowForeignNumbers": true,
        "allowInternationalNumbers": true,
        "allowMobileNumbers": true,
        "allowFixedNumbers": true,
        "country": "example",
        "prefixMobile": "example",
        "prefixFixed": "example"
      }
    }
  }
}

Settings aggiornati

Aggiorna gli advanced settings dell'assistente

​

Aggiorna gli advanced settings dell'assistente con semantica PATCH merge.

Parametri modificabili:

  • temperature
  • maxTokens
  • topP
  • topK
  • freqPenalty
  • presencePenalty
  • stopSequences

Come recuperare i dati correnti:

  • usa GET /api/v1/catalog/assistants/{assistantApiKey}/advanced-settings

Regole operative:

  • se vuoi modificare un solo campo, invia solo quel campo
  • i campi numerici possono essere inviati a null per essere rimossi
  • stopSequences: null o stopSequences: [] resetta la lista
  • sugli assistenti voice_to_voice questi valori vengono scritti nel root JSON voice-llm

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

PATCH merge degli advanced settings dell'assistente.

Come recuperare i dati correnti:

  • usa GET /api/v1/catalog/assistants/{assistantApiKey}/advanced-settings

Regole operative:

  • invia solo i campi da modificare
  • i campi numerici possono essere inviati a null per essere rimossi
  • stopSequences: null o stopSequences: [] resetta la lista
  • freqPenalty
    Type: number | null
    min:  
    -2
    max:  
    2

    Valore da inviare per freqPenalty nella richiesta AssistantAdvancedSettingsRuntimeUpdateRequest.

  • maxTokens
    Type: integer | null
    min:  
    1
    max:  
    100000

    Valore da inviare per maxTokens nella richiesta AssistantAdvancedSettingsRuntimeUpdateRequest.

  • presencePenalty
    Type: number | null
    min:  
    -2
    max:  
    2

    Valore da inviare per presencePenalty nella richiesta AssistantAdvancedSettingsRuntimeUpdateRequest.

  • stopSequences
    Type: array of string | null

    Valore da inviare per stopSequences nella richiesta AssistantAdvancedSettingsRuntimeUpdateRequest.

  • temperature
    Type: number | null
    min:  
    0
    max:  
    2

    Valore da inviare per temperature nella richiesta AssistantAdvancedSettingsRuntimeUpdateRequest.

  • topK
    Type: integer | null
    min:  
    1
    max:  
    100

    Valore da inviare per topK nella richiesta AssistantAdvancedSettingsRuntimeUpdateRequest.

  • topP
    Type: number | null
    min:  
    0
    max:  
    1

    Valore da inviare per topP nella richiesta AssistantAdvancedSettingsRuntimeUpdateRequest.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/advanced-settings
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/advanced-settings \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "temperature": 0.6
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistantApiKey": "ai4call_sk_example",
    "assistantId": "example-id",
    "service": "advanced-settings",
    "configuration": {
      "temperature": 1,
      "maxTokens": 1,
      "topP": 1,
      "topK": 1,
      "freqPenalty": 1,
      "presencePenalty": 1,
      "stopSequences": [
        "example"
      ]
    }
  }
}

Advanced settings aggiornati

Recupera i settings dell'assistente

​

Recupera i settings dell'assistente

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/assistants/{assistantId}/settings
curl https://client-api.ai4call.com/api/v1/catalog/assistants/205/settings \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant settings configuration retrieved successfully.",
  "requestId": "c3d93c2c-8f89-4a2e-b9ad-67d2746c9d16",
  "data": {
    "configuration": {
      "asrSilenceMs": 500,
      "asrInitialDelayMs": 0,
      "truncateInitialAudio": false,
      "dynamicTimeoutMs": 10000,
      "vad": false,
      "vadThreshold": 0.5,
      "vadMinVoiceMs": 180,
      "ttsInterruptionInConversation": true,
      "filler": {
        "enabled": true,
        "delayMs": 1200,
        "waitingListIds": [],
        "toolListIds": [],
        "waiting": [],
        "tool": []
      },
      "reprompt": {
        "enabled": true,
        "mode": "llm",
        "text": [],
        "repeatMaxLength": 180,
        "maxRetries": 1
      },
      "maxResponseLength": 50000,
      "callPermissions": {
        "checkVerifyNumber": false,
        "allowForeignNumbers": false,
        "allowInternationalNumbers": false,
        "allowMobileNumbers": false,
        "allowFixedNumbers": false,
        "country": "it",
        "prefixMobile": "3",
        "prefixFixed": "0"
      }
    }
  }
}

Settings dell'assistente

Recupera gli advanced settings dell'assistente

​

Recupera gli advanced settings dell'assistente

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/assistants/{assistantId}/advanced-settings
curl https://client-api.ai4call.com/api/v1/catalog/assistants/205/advanced-settings \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant advanced settings configuration retrieved successfully.",
  "requestId": "d1f31a39-a20c-491b-8551-0b2f6a47bbf8",
  "data": {
    "configuration": {
      "temperature": 0.7,
      "maxTokens": 800,
      "topP": 0.9,
      "topK": 40,
      "freqPenalty": 0,
      "presencePenalty": 0,
      "stopSequences": [
        "END"
      ]
    }
  }
}

Advanced settings dell'assistente

Catalog Hangup

​

Configurazione hangup, redirect e trasferimento dell'assistente

Catalog Hangup Operations

Aggiorna la configurazione runtime hangup dell'assistente

​

Aggiorna la configurazione hangup, redirect e trasferimento con semantica PATCH merge.

Parametri modificabili:

  • enableHangup
  • enableRedirect
  • enableTransferAgent
  • transferAgentNotificationText
  • availableAgents
  • availableAgents[].assistantApiKey
  • availableAgents[].description

Come recuperare i dati correnti:

  • usa GET /api/v1/catalog/assistants/{assistantApiKey}/hangup
  • usa GET /api/v1/assistants per recuperare gli assistantApiKey selezionabili per il trasferimento

Regole operative:

  • se vuoi modificare un solo parametro, invia solo quel parametro
  • enableTransferAgent: false resetta notifica e assistenti collegati
  • se enableTransferAgent è attivo, serve almeno un assistente con descrizione non vuota
  • sugli assistenti voice_to_voice il backend aggiorna pbxTools.hangup, pbxTools.redirect e pbxTools.transferAgent

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

PATCH merge della configurazione hangup/redirect/trasferimento dell'assistente.

Regole operative:

  • almeno uno tra enableHangup, enableRedirect, enableTransferAgent, transferAgentNotificationText, availableAgents deve essere presente
  • i campi omessi mantengono il valore corrente
  • usa GET /api/v1/catalog/assistants/{assistantApiKey}/hangup per leggere lo stato corrente
  • usa GET /api/v1/assistants per recuperare gli assistantApiKey selezionabili per il trasferimento
  • se enableTransferAgent e true, serve almeno un availableAgents con descrizione non vuota
  • se invii availableAgents con enableTransferAgent omesso, il trasferimento viene considerato attivo
  • enableTransferAgent: false resetta transferAgentNotificationText e availableAgents
  • availableAgents
    Type:

    Valore da inviare per availableAgents nella richiesta AssistantHangupRuntimeUpdateRequest.

    Properties: 2
  • enableHangup
    Type: boolean

    Valore da inviare per enableHangup nella richiesta AssistantHangupRuntimeUpdateRequest.

  • enableRedirect
    Type: boolean

    Valore da inviare per enableRedirect nella richiesta AssistantHangupRuntimeUpdateRequest.

  • enableTransferAgent
    Type: boolean

    Valore da inviare per enableTransferAgent nella richiesta AssistantHangupRuntimeUpdateRequest.

  • transferAgentNotificationText
    Type: string | null

    Valore da inviare per transferAgentNotificationText nella richiesta AssistantHangupRuntimeUpdateRequest.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/hangup
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/hangup \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "enableHangup": true,
  "enableRedirect": true
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistantApiKey": "ai4call_sk_example",
    "assistantId": "example-id",
    "service": "hangup",
    "configuration": {
      "enableHangup": true,
      "enableRedirect": true,
      "enableTransferAgent": true,
      "transferAgentNotificationText": "example",
      "availableAgents": [
        {
          "assistantApiKey": "ai4call_sk_example",
          "description": "esempio"
        }
      ]
    }
  }
}

Configurazione runtime hangup aggiornata

Recupera la configurazione salvataggio conversazione dell'assistente

​

Restituisce lo stato corrente del salvataggio conversazione:

  • enabled: se l'invio del riepilogo via email è attivo
  • emails: destinatari configurati (stringa separata da virgola)
  • smtpInstanceName: nome dell'istanza SMTP plugin collegata

Prerequisito: il cliente deve avere almeno una sottoscrizione attiva a un plugin SMTP.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/assistants/{assistantId}/runtime/hangup/save-conversation
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/hangup/save-conversation \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant save-conversation configuration retrieved successfully.",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "configuration": {
      "enabled": true,
      "emails": "admin@example.com, report@example.com",
      "smtpInstanceName": "smtp-principale"
    }
  }
}

Configurazione salvataggio conversazione recuperata

Aggiorna la configurazione salvataggio conversazione dell'assistente

​

Aggiorna la configurazione salvataggio conversazione con semantica PATCH merge.

Parametri modificabili:

  • enabled
  • emails
  • smtpInstanceName

Come recuperare i dati correnti:

  • usa GET /api/v1/assistants/{assistantApiKey}/runtime/hangup/save-conversation

Regole operative:

  • almeno uno tra enabled, emails e smtpInstanceName deve essere presente
  • i campi omessi mantengono il valore corrente
  • smtpInstanceName deve corrispondere all'instanceName di una sottoscrizione SMTP attiva del cliente
  • per ottenere la lista delle istanze SMTP disponibili, controlla le sottoscrizioni plugin del cliente
  • emails accetta una stringa con una o più email separate da virgola
  • impostare smtpInstanceName: null rimuove il collegamento all'istanza SMTP

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

PATCH merge della configurazione salvataggio conversazione dell'assistente.

Regole operative:

  • almeno uno tra enabled, emails e smtpInstanceName deve essere presente
  • i campi omessi mantengono il valore corrente
  • smtpInstanceName corrisponde all'instanceName della sottoscrizione SMTP attiva del cliente
  • se enabled: true, è necessario che sia configurato un plugin SMTP attivo
  • emails accetta una stringa con una o più email separate da virgola
  • emails
    Type: string | null

    Una o più email destinatarie separate da virgola (es: email1@example.com, email2@example.com)

  • enabled
    Type: boolean

    Abilita o disabilita l'invio del riepilogo conversazione via email

  • smtp_instance_name
    Type: string | null
    deprecated

    Alias legacy di smtpInstanceName.

  • smtpInstanceName
    Type: string | null

    Nome dell'istanza del plugin SMTP da usare per l'invio

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/hangup/save-conversation
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/hangup/save-conversation \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "enabled": true,
  "emails": "admin@example.com, report@example.com",
  "smtpInstanceName": "smtp-principale"
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "configuration": {
      "enabled": true,
      "emails": "developer@example.com",
      "smtpInstanceName": "Example"
    }
  }
}

Configurazione salvataggio conversazione aggiornata

Recupera la configurazione del webhook di fine conversazione dell'assistente

​

Restituisce la configurazione attuale del webhook chiamato a fine chiamata:

  • enabled: se l'invio è attivo
  • url: endpoint di destinazione
  • authName: nome dell'autenticazione applicata, null per una chiamata non autenticata
  • payloadFields: campi sempre presenti nel body inviato

Questo canale e alternativo all'invio via email (runtime/hangup/save-conversation) e i due possono essere attivi contemporaneamente.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/assistants/{assistantId}/runtime/hangup/conversation-webhook
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/hangup/conversation-webhook \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant conversation webhook configuration retrieved successfully.",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "configuration": {
      "enabled": true,
      "url": "https://example.com/hooks/ai4call",
      "authName": "crm-bearer",
      "payloadFields": [
        "caller",
        "called",
        "callid",
        "conversation"
      ]
    }
  }
}

Configurazione webhook recuperata

Aggiorna la configurazione del webhook di fine conversazione dell'assistente

​

Aggiorna la configurazione del webhook con semantica PATCH merge.

Parametri modificabili:

  • enabled
  • url
  • authName

Come recuperare i dati attuali:

  • usare GET /api/v1/assistants/{assistantApiKey}/runtime/hangup/conversation-webhook

Regole operative:

  • almeno uno fra enabled, url e authName deve essere presente
  • i campi omessi mantengono il valore attuale
  • abilitare senza un url http:// o https:// valido restituisce 400
  • authName deve corrispondere a un'autenticazione già salvata dal cliente; le credenziali vengono risolte lato server e non transitano in questo payload
  • impostare authName: null invia il webhook senza autenticazione

Body ricevuto dall'endpoint: caller, called, callid e conversation.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

PATCH merge della configurazione del webhook di fine conversazione dell'assistente.

Regole operative:

  • almeno uno fra enabled, url e authName deve essere presente
  • i campi omessi mantengono il valore attuale
  • se enabled: true, url deve essere un indirizzo http:// o https:// valido
  • authName corrisponde al nome di un'autenticazione già salvata dal cliente; le credenziali vengono risolte lato server e non transitano in questo payload
  • impostare authName: null invia il webhook senza autenticazione
  • authName
    Type: string | null

    Nome dell'autenticazione salvata da applicare alla richiesta

  • enabled
    Type: boolean

    Abilita o disabilita l'invio della conversazione al webhook

  • url
    Type: string | null

    Endpoint che riceve la POST a fine chiamata

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/hangup/conversation-webhook
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/hangup/conversation-webhook \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "enabled": true,
  "url": "https://example.com/hooks/ai4call",
  "authName": "crm-bearer"
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "configuration": {
      "enabled": true,
      "url": "https://example.com",
      "authName": "Example",
      "payloadFields": [
        "caller",
        "called",
        "callid",
        "conversation"
      ]
    }
  }
}

Configurazione webhook aggiornata

Recupera la configurazione schema tool di hangup

​

Restituisce la configurazione attuale dello schema inviato al webhook hangup:

  • hangupUrl: URL del webhook chiamato al termine della chiamata
  • schema: array di proprietà che definiscono il body JSON inviato all'hangup URL

Ogni proprietà può essere di tipo string, number, boolean, enum o object. Le proprietà di tipo object supportano campi annidati tramite children. Sugli assistenti voice_to_voice, lo schema viene letto da pbxTools.hangupEndpoint.input_schema.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/assistants/{assistantId}/runtime/hangup/schema
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/hangup/schema \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant hangup schema configuration retrieved successfully.",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "configuration": {
      "hangupUrl": "https://webhook.example.com/hangup",
      "schema": [
        {
          "name": "motivo",
          "type": "string",
          "description": "Motivo dell'hangup",
          "required": true
        },
        {
          "name": "esito",
          "type": "enum",
          "description": "Esito della chiamata",
          "required": true,
          "enumValues": [
            "positivo",
            "negativo",
            "richiamata"
          ]
        },
        {
          "name": "dati_cliente",
          "type": "object",
          "description": "Dati raccolti sul cliente",
          "children": [
            {
              "name": "nome",
              "type": "string",
              "description": "Nome del cliente"
            },
            {
              "name": "email",
              "type": "string",
              "description": "Email del cliente"
            }
          ]
        }
      ]
    }
  }
}

Schema hangup recuperato con successo

Aggiorna la configurazione schema tool di hangup

​

Aggiorna la configurazione dello schema hangup con semantica PATCH merge.

Parametri modificabili:

  • hangupUrl
  • schema
  • schema[].name
  • schema[].type
  • schema[].description
  • schema[].required
  • schema[].enumValues
  • schema[].children

Come recuperare i dati correnti:

  • usa GET /api/v1/assistants/{assistantApiKey}/runtime/hangup/schema

Regole operative

  • Almeno uno tra hangupUrl e schema deve essere presente nel body
  • I campi omessi mantengono il valore corrente
  • Inviare schema sostituisce completamente lo schema corrente (non è un merge)
  • Inviare hangupUrl: null rimuove il webhook URL, disabilita il tool di hangup e azzera automaticamente anche lo schema
  • Inviare schema: [] svuota lo schema mantenendo l'URL corrente
  • Sugli assistenti voice_to_voice, il backend aggiorna pbxTools.hangupEndpoint.endpoint e pbxTools.hangupEndpoint.input_schema

Come costruire il body dello schema

Lo schema è un array di proprietà che definiscono i campi del body JSON inviato all'hangupUrl al termine della chiamata. Ogni proprietà ha la seguente struttura:

Campo Tipo Obbligatorio Descrizione
name string sì Nome del campo nel body JSON
type string sì Tipo del campo: string, number, boolean, enum, object
description string no Descrizione del campo (aiuta il modello LLM a capire cosa inserire)
required boolean no Se true, il campo è obbligatorio nel body hangup
enumValues string[] solo per enum Lista di valori ammessi (solo se type: enum)
children Property[] solo per object Campi annidati (solo se type: object)

Tipi supportati e come usarli

string — campo testo libero:

{ "name": "motivo", "type": "string", "description": "Motivo del termine della chiamata", "required": true }

number — campo numerico:

{ "name": "durata_secondi", "type": "number", "description": "Durata della chiamata in secondi" }

boolean — campo booleano:

{ "name": "cliente_soddisfatto", "type": "boolean", "description": "Il cliente si è dichiarato soddisfatto" }

enum — campo a scelta multipla, richiede enumValues:

{ "name": "esito", "type": "enum", "description": "Esito della chiamata", "required": true, "enumValues": ["positivo", "negativo", "richiamata"] }

object — gruppo di campi annidati, richiede children:

{
  "name": "dati_cliente",
  "type": "object",
  "description": "Dati raccolti durante la chiamata",
  "children": [
    { "name": "nome", "type": "string", "description": "Nome del cliente" },
    { "name": "email", "type": "string", "description": "Email del cliente" }
  ]
}

Esempio di body JSON risultante

Con lo schema sopra, il webhook riceverà un body simile a:

{
  "motivo": "Cliente ha chiesto informazioni sul prodotto X",
  "esito": "positivo",
  "cliente_soddisfatto": true,
  "durata_secondi": 182,
  "dati_cliente": {
    "nome": "Mario Rossi",
    "email": "mario@example.com"
  }
}

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json
  • hangupUrl
    Type: string | null

    URL del webhook hangup (null per rimuoverlo)

  • schema
    Type:

    Definizione dei campi del body (sostituisce lo schema corrente)

    Properties: 6

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/hangup/schema
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/hangup/schema \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "hangupUrl": "https://webhook.example.com/hangup",
  "schema": [
    {
      "name": "motivo",
      "type": "string",
      "description": "Motivo dell'\''hangup",
      "required": true
    },
    {
      "name": "esito",
      "type": "enum",
      "description": "Esito della chiamata",
      "required": true,
      "enumValues": [
        "positivo",
        "negativo",
        "richiamata"
      ]
    },
    {
      "name": "dati_cliente",
      "type": "object",
      "description": "Dati raccolti sul cliente",
      "children": [
        {
          "name": "nome",
          "type": "string",
          "description": "Nome del cliente"
        },
        {
          "name": "email",
          "type": "string",
          "description": "Email del cliente"
        }
      ]
    }
  ]
}'

{
  "success": true,
  "data": {
    "configuration": {
      "hangupUrl": "https://example.com",
      "schema": [
        {
          "name": "Example",
          "type": "string"
        }
      ]
    }
  }
}

Schema hangup aggiornato con successo

Recupera la configurazione hangup dell'assistente

​

Recupera la configurazione hangup dell'assistente

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/assistants/{assistantId}/hangup
curl https://client-api.ai4call.com/api/v1/catalog/assistants/205/hangup \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant hangup configuration retrieved successfully.",
  "requestId": "55e4ea0f-21d2-4d28-b6e1-8f47b18b7d44",
  "data": {
    "configuration": {
      "enableHangup": true,
      "enableRedirect": false,
      "enableTransferAgent": true,
      "transferAgentNotificationText": "Avvisa il cliente prima del passaggio.",
      "availableAgents": [
        {
          "assistantApiKey": "ai4call_sk_transfer_1",
          "assistantName": "Assistente Amministrativo",
          "description": "Trasferisci quando il cliente chiede supporto amministrativo."
        }
      ]
    }
  }
}

Configurazione hangup dell'assistente

Catalog Pre-Call

​

Configurazione pre-call dell'assistente

Catalog Pre-Call Operations

Recupera la configurazione di verifica numero chiamante

​

Restituisce la configurazione corrente del webhook usato per verificare il numero chiamante prima che la chiamata venga connessa all'assistente.

Se nessuna configurazione è ancora stata creata, data.configuration sarà null.

Come funziona la verifica numero

All'arrivo di una chiamata, il sistema esegue una richiesta HTTP al webhook configurato, passando il numero chiamante nel campo indicato (numberParamName), nella posizione indicata (numberLocation). Il webhook deve rispondere con: 

{ "enabled": true }
  • Se enabled è true (o assente): la chiamata prosegue normalmente
  • Se enabled è false: la chiamata viene bloccata

Il webhook può anche restituire un oggetto callerInfo con dati aggiuntivi che verranno resi disponibili all'assistente durante la chiamata.

Nota sulla sicurezza

I campi sensibili (authToken, authPassword) non vengono mai restituiti in chiaro. Al loro posto sono presenti i flag hasAuthToken e hasAuthPassword.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/assistants/{assistantId}/runtime/precall/number-validation
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/precall/number-validation \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'
Configurazione presente
{
  "success": true,
  "message": "Assistant precall validation configuration retrieved successfully.",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "configuration": {
      "name": "Verifica CRM",
      "method": "POST",
      "url": "https://api.example.com/validate-caller",
      "numberLocation": "body",
      "numberParamName": "caller_id",
      "headersJson": {
        "X-Api-Version": "2"
      },
      "authType": "bearer",
      "hasAuthToken": true,
      "hasAuthPassword": false,
      "authUsername": null,
      "timeoutMs": 5000,
      "isActive": true
    }
  }
}

Configurazione verifica numero recuperata

Crea o aggiorna la configurazione di verifica numero chiamante

​

Crea la configurazione se non esiste, altrimenti aggiorna i campi forniti con semantica PATCH merge (i campi omessi mantengono il valore corrente).

Parametri modificabili:

  • name
  • method
  • url
  • numberLocation
  • numberParamName
  • headersJson
  • authType
  • authToken
  • authUsername
  • authPassword
  • timeoutMs
  • isActive

Come recuperare i dati correnti:

  • usa GET /api/v1/assistants/{assistantApiKey}/runtime/precall/number-validation

Regole operative

  • Almeno un campo deve essere presente nel body
  • I campi omessi mantengono il valore corrente (o il default se è la prima creazione)
  • Inviare isActive: false elimina completamente la configurazione — data.configuration sarà null
  • La configurazione è sempre attiva (isActive: true) quando viene creata o aggiornata
  • Inviare authToken: null rimuove il token configurato
  • Inviare authPassword: null rimuove la password configurata
  • Inviare headersJson: null rimuove tutti gli header custom
  • authToken e authPassword non vengono mai restituiti — usare hasAuthToken/hasAuthPassword

Come configurare numberLocation

Valore Dove viene inviato il numero Esempio
query Query string dell'URL GET /validate?caller_id=0391234567
body Body JSON della richiesta POST /validate con body { "caller_id": "0391234567" }
params Segmento dell'URL GET /validate/0391234567 (il numero sostituisce :numberParamName nell'URL)

Autenticazione supportata

authType Campi richiesti Header generato
none — nessuno
bearer authToken Authorization: Bearer <token>
api_key authToken X-Api-Key: <token>
basic authUsername + authPassword Authorization: Basic <base64>

Risposta attesa dal webhook

Il webhook deve rispondere con HTTP 200 e un body JSON contenente almeno:

{ "enabled": true }

Può includere dati aggiuntivi:

{
  "enabled": true,
  "callerInfo": {
    "nome": "Mario Rossi",
    "cliente_id": "C-001",
    "piano": "premium"
  }
}

Se enabled è false, la chiamata viene bloccata prima di raggiungere l'assistente.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json
  • authPassword
    Type: string | null

    Password Basic auth (null per rimuoverla)

  • authToken
    Type: string | null

    Bearer token o API key (null per rimuoverlo)

  • authType
    Type: enum
    values
    nonebearerapi_keybasic
  • authUsername
    Type: string | null

    Valore da inviare per authUsername nella richiesta AssistantPrecallValidationRuntimeUpdateRequest.

  • headersJson
    Type: object | null

    Valore da inviare per headersJson nella richiesta AssistantPrecallValidationRuntimeUpdateRequest.

    Properties: 1
  • isActive
    Type: boolean

    Valore da inviare per isActive nella richiesta AssistantPrecallValidationRuntimeUpdateRequest.

  • method
    Type: enum
    values
    GETPOSTPUTPATCHDELETE
  • name
    Type: string
    min length:  
    1

    Valore da inviare per name nella richiesta AssistantPrecallValidationRuntimeUpdateRequest.

  • numberLocation
    Type: enum

    Dove inserire il numero chiamante nella richiesta HTTP:

    • query — aggiunto come query string (es. ?number=0391234567)
    • body — inserito nel body JSON (es. { "number": "0391234567" })
    • params — sostituisce un segmento dell'URL (es. /validate/0391234567)
    values
    bodyqueryparams
  • numberParamName
    Type: string
    min length:  
    1

    Valore da inviare per numberParamName nella richiesta AssistantPrecallValidationRuntimeUpdateRequest.

  • timeoutMs
    Type: integer
    min:  
    500
    max:  
    30000

    Valore da inviare per timeoutMs nella richiesta AssistantPrecallValidationRuntimeUpdateRequest.

  • url
    Type: stringFormat: uri

    Valore da inviare per url nella richiesta AssistantPrecallValidationRuntimeUpdateRequest.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/precall/number-validation
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/precall/number-validation \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "name": "Verifica CRM",
  "method": "POST",
  "url": "https://api.example.com/validate-caller",
  "numberLocation": "body",
  "numberParamName": "caller_id",
  "headersJson": {
    "X-Api-Version": "2",
    "Accept-Language": "it"
  },
  "authType": "bearer",
  "authToken": "eyJhbGciOiJIUzI1NiJ9...",
  "timeoutMs": 5000,
  "isActive": true
}'

{
  "success": true,
  "data": {
    "configuration": {
      "name": "Example",
      "method": "GET",
      "url": "https://example.com",
      "numberLocation": "body",
      "numberParamName": "Example",
      "headersJson": {},
      "authType": "none",
      "hasAuthToken": true,
      "hasAuthPassword": true,
      "authUsername": "Example",
      "timeoutMs": 500,
      "isActive": true
    }
  }
}

Configurazione verifica numero aggiornata

Recupera la configurazione pre-call dell'assistente

​

Restituisce la configurazione corrente della fase pre-call: impostazioni generali (configuration) e tool associati (tools).

Come funziona la fase pre-call

Prima che la chiamata venga connessa all'assistente, il sistema esegue in sequenza i tool configurati (nell'ordine definito da order). I tool possono essere:

  • custom tool (definiti nel JSON dell'assistente, subscriptionName: null)
  • tool MCP plugin o custom MCP (con subscriptionName valorizzato)

I tool possono recuperare informazioni sul chiamante, eseguire validazioni o arricchire il contesto, e terminare anticipatamente la chiamata se earlyTerminationEnabled è true.

Se waitingAudioText è configurato, viene riprodotto al chiamante durante l'esecuzione. voiceConfig controlla la voce usata per generare audio di attesa/terminazione, mentre modelConfig controlla il modello usato per interpretare i risultati dei tool.

Come leggere tools

I campi toolName e subscriptionName restituiti corrispondono ai campi toolName e subscriptionName da inviare nella PATCH. I tool pre-call possono essere scelti solo tra quelli già associati all'assistente:

  • GET /api/v1/catalog/assistants/{assistantApiKey}/tools

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/assistants/{assistantId}/runtime/precall/mcp-config
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/precall/mcp-config \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'
Tool custom e MCP plugin associati
{
  "success": true,
  "message": "Assistant precall MCP configuration retrieved successfully.",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "configuration": {
      "enabled": true,
      "globalPrompt": "Usa le informazioni recuperate per personalizzare la risposta.",
      "waitingAudioText": "Sto verificando la tua identità, un momento...",
      "earlyTerminationEnabled": true,
      "terminationMessage": "Non sei autorizzato a procedere. Arrivederci.",
      "waitingAudioNonInterruptible": true,
      "modelConfig": {
        "mode": "assistant"
      },
      "voiceConfig": {
        "mode": "assistant"
      },
      "outputVariables": [
        {
          "name": "customer_tier",
          "type": "string",
          "required": true
        }
      ],
      "outputSchema": null
    },
    "tools": [
      {
        "toolName": "verifica_cliente",
        "server": "custom",
        "subscriptionName": null,
        "order": 1
      },
      {
        "toolName": "get_customer_info",
        "server": "crm_plugin",
        "subscriptionName": "CRM Principale",
        "order": 2
      }
    ]
  }
}

Configurazione pre-call recuperata

Aggiorna la configurazione pre-call dell'assistente

​

Aggiorna la configurazione pre-call con semantica PATCH merge. Almeno un campo deve essere presente nel body.

Parametri modificabili:

  • tools
  • tools[].toolName
  • tools[].subscriptionName
  • tools[].order
  • globalPrompt
  • waitingAudioText
  • earlyTerminationEnabled
  • terminationMessage
  • waitingAudioNonInterruptible
  • modelConfig
  • voiceConfig

Come recuperare la configurazione corrente:

  • GET /api/v1/assistants/{assistantApiKey}/runtime/precall/mcp-config

Gestione dei tool

Il campo tools sostituisce completamente i tool pre-call correnti:

Body inviato Effetto
tools omesso mantiene i tool correnti inalterati
tools: [] rimuove tutti i tool pre-call e resetta tutta la configurazione pre-call
tools: [{...}] sostituisce con la lista inviata

Per l'ordinamento:

  • se ogni item include order, viene usato order
  • se order è omesso, viene usato l'ordine dell'array

Come costruire la lista tools

Usa i record di GET /api/v1/catalog/assistants/{assistantApiKey}/tools per ottenere toolName e instanceName. La pre-call accetta solo tool già associati all'assistente:

Tipo tool toolName subscriptionName
custom_tool (tool custom JSON) toolName null
plugin_tool (MCP plugin) toolName instanceName
custom_mcp_tool (MCP custom) toolName instanceName

I tool custom (subscriptionName: null) sono quelli definiti nel JSON dell'assistente e non richiedono subscription.

Configurazione generale

Campo Effetto
globalPrompt: null rimuove il prompt globale
waitingAudioText: null rimuove l'audio di attesa
earlyTerminationEnabled: true abilita terminazione anticipata
terminationMessage: null rimuove il messaggio di terminazione
waitingAudioNonInterruptible: false rende interrompibile l'audio di attesa
modelConfig imposta default/assistant/managed/custom per il modello pre-call
voiceConfig imposta default/assistant/custom per il TTS pre-call

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

Aggiorna la configurazione pre-call con semantica PATCH merge. Almeno un campo deve essere presente.

Gestione dei tool

Il campo tools sostituisce completamente la lista dei tool pre-call.

  • tools: [] rimuove tutti i tool pre-call e resetta globalPrompt, waitingAudioText, earlyTerminationEnabled, terminationMessage, waitingAudioNonInterruptible, modelConfig e voiceConfig
  • tools omesso: mantiene i tool correnti inalterati
  • Se order è presente, l'ordine di esecuzione segue order
  • Se order è omesso, l'ordine di esecuzione segue l'ordine dell'array inviato

Per costruire la lista usa i record di GET /api/v1/catalog/assistants/{assistantApiKey}/tools. La pre-call accetta solo tool già associati all'assistente.

  • earlyTerminationEnabled
    Type: boolean

    Abilita/disabilita la terminazione anticipata.

  • enabled
    Type: boolean

    Abilita o disabilita l'intera fase di pre-call senza perderne la configurazione. Se omesso, mantiene il valore attuale.

  • globalPrompt
    Type: string | null

    Prompt globale pre-call. null per rimuoverlo.

  • modelConfig
    Type:

    Configurazione modello usata dalla fase MCP. Le API key non vengono restituite in chiaro: nelle risposte viene esposto hasApiKey.

    Properties: 5
  • outputSchema
    Type: object

    Schema JSON dell'output atteso dal pre-call, in alternativa a outputVariables.

    Properties: 1
  • outputVariables
    Type:

    Variabili da estrarre dal risultato del pre-call. Sostituisce interamente l'elenco attuale.

    Properties: 4
  • terminationMessage
    Type: string | null

    Messaggio audio di terminazione anticipata. null per rimuoverlo.

  • tools
    Type:

    Lista completa dei tool pre-call da impostare (sostituisce quelli correnti).

  • voiceConfig
    Type:

    Configurazione voce/TTS usata per generare l'audio di attesa e terminazione della pre-call. Le API key non vengono restituite in chiaro: nelle risposte viene esposto hasApiKey.

    Properties: 8
  • waitingAudioNonInterruptible
    Type: boolean

    true riproduce tutto l'audio di attesa, false permette al cliente di parlare sopra l'audio.

  • waitingAudioText
    Type: string | null

    Testo audio di attesa. null per rimuoverlo.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/precall/mcp-config
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/precall/mcp-config \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "tools": [
    {
      "toolName": "verifica_cliente",
      "subscriptionName": null,
      "order": 0
    },
    {
      "toolName": "get_customer_info",
      "subscriptionName": "CRM Principale",
      "order": 1
    }
  ],
  "globalPrompt": "Usa le informazioni recuperate per personalizzare la risposta.",
  "waitingAudioText": "Sto verificando la tua identità, un momento...",
  "earlyTerminationEnabled": true,
  "terminationMessage": "Non sei autorizzato a procedere. Arrivederci.",
  "waitingAudioNonInterruptible": true,
  "modelConfig": {
    "mode": "assistant"
  },
  "voiceConfig": {
    "mode": "assistant"
  }
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "configuration": {
      "enabled": true,
      "globalPrompt": "example",
      "waitingAudioText": "example",
      "earlyTerminationEnabled": true,
      "terminationMessage": "Operation completed successfully.",
      "waitingAudioNonInterruptible": true,
      "modelConfig": {
        "mode": "default"
      },
      "voiceConfig": {
        "mode": "default"
      },
      "outputVariables": [
        {
          "name": "customer_tier",
          "type": "string"
        }
      ],
      "outputSchema": {}
    },
    "tools": [
      {
        "toolName": "Example",
        "server": "example",
        "subscriptionName": "Example",
        "order": 1
      }
    ]
  }
}

Configurazione pre-call aggiornata

Recupera la configurazione pre-call dell'assistente

​

Recupera la configurazione pre-call dell'assistente

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/assistants/{assistantId}/pre-call
curl https://client-api.ai4call.com/api/v1/catalog/assistants/205/pre-call \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant pre-call configuration retrieved successfully.",
  "requestId": "03a61d48-929d-4e18-80d6-2af9da9b1493",
  "data": {
    "configuration": {
      "tools": [
        {
          "server": "google_sheets",
          "method": "sheets_search_rows",
          "executeBeforeCall": true,
          "required": [
            "caller_id",
            "company_name"
          ],
          "metadata": {
            "spreadsheetId": "1AbCdEf"
          }
        }
      ],
      "globalPrompt": "Recupera informazioni utili prima del passaggio all'assistente.",
      "waitingAudioText": "Attendi in linea mentre recupero le informazioni.",
      "earlyTerminationEnabled": false,
      "terminationMessage": "",
      "terminationAudioFile": null
    }
  }
}

Configurazione pre-call

Catalog Post-Call

​

Configurazione post-call MCP dell'assistente

Catalog Post-Call Operations

Recupera la configurazione post-call MCP dell'assistente

​

Restituisce la configurazione corrente della fase post-call MCP: impostazioni generali (configuration) e tool associati (tools).

I campi toolName e subscriptionName restituiti corrispondono ai campi toolName e subscriptionName da inviare nella PATCH. I tool post-call possono essere scelti solo tra quelli già' associati all'assistente:

  • GET /api/v1/catalog/assistants/{assistantApiKey}/tools

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/assistants/{assistantId}/runtime/postcall/mcp-config
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/postcall/mcp-config \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'
Tool post-call associati
{
  "success": true,
  "message": "Assistant postcall MCP configuration retrieved successfully.",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "configuration": {
      "enabled": true,
      "globalPrompt": "Usa i risultati dei tool per aggiornare il CRM.",
      "modelConfig": {
        "mode": "assistant"
      }
    },
    "tools": [
      {
        "toolName": "create_ticket",
        "server": "crm_plugin",
        "subscriptionName": "CRM Principale",
        "order": 0
      }
    ]
  }
}

Configurazione post-call recuperata

Aggiorna la configurazione post-call MCP dell'assistente

​

Aggiorna la configurazione post-call con semantica PATCH merge. Almeno un campo deve essere presente nel body.

Parametri modificabili:

  • tools
  • tools[].toolName
  • tools[].subscriptionName
  • tools[].order
  • globalPrompt
  • modelConfig

Come recuperare la configurazione corrente:

  • GET /api/v1/assistants/{assistantApiKey}/runtime/postcall/mcp-config

Il campo tools sostituisce completamente i tool post-call correnti:

Body inviato Effetto
tools omesso mantiene i tool correnti inalterati
tools: [] rimuove tutti i tool post-call e resetta globalPrompt e modelConfig
tools: [{...}] sostituisce con la lista inviata

Usa i record di GET /api/v1/catalog/assistants/{assistantApiKey}/tools per ottenere toolName e instanceName.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

Aggiorna la configurazione post-call con semantica PATCH merge. Almeno un campo deve essere presente.

Il campo tools sostituisce completamente la lista dei tool post-call.

  • tools: [] rimuove tutti i tool post-call e resetta globalPrompt e modelConfig
  • tools omesso: mantiene i tool correnti inalterati
  • enabled
    Type: boolean

    Abilita o disabilita l'intera fase di post-call senza perderne la configurazione. Quando e false il webhook di fine chiamata non viene inviato. Se omesso, mantiene il valore attuale.

  • globalPrompt
    Type: string | null

    Prompt globale post-call. null per rimuoverlo.

  • modelConfig
    Type:

    Configurazione modello usata dalla fase MCP. Le API key non vengono restituite in chiaro: nelle risposte viene esposto hasApiKey.

    Properties: 5
  • tools
    Type:

    Lista completa dei tool post-call da impostare.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/postcall/mcp-config
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/postcall/mcp-config \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "tools": [
    {
      "toolName": "create_ticket",
      "subscriptionName": "CRM Principale",
      "order": 0
    }
  ],
  "globalPrompt": "Usa i risultati dei tool per aggiornare il CRM.",
  "modelConfig": {
    "mode": "assistant"
  }
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "configuration": {
      "enabled": true,
      "globalPrompt": "example",
      "modelConfig": {
        "mode": "default"
      }
    },
    "tools": [
      {
        "toolName": "Example",
        "server": "example",
        "subscriptionName": "Example",
        "order": 1
      }
    ]
  }
}

Configurazione post-call aggiornata

Catalog Runtime Bindings

​

Binding runtime dell'assistente verso pricing e provider reali

Catalog Runtime Bindings Operations

Recupera i binding runtime dell'assistente verso TTS, ASR e LLM

​

Recupera i binding runtime dell'assistente verso TTS, ASR e LLM

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/assistants/{assistantId}/runtime-bindings
curl https://client-api.ai4call.com/api/v1/catalog/assistants/205/runtime-bindings \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant runtime bindings retrieved successfully.",
  "requestId": "6ce3ab94-4041-4429-86ef-5522dc80c4c4",
  "data": {
    "assistantApiKey": "ast_demo_sales_001",
    "assistantId": "188",
    "runtimeBindings": {
      "tts": {
        "configured": false,
        "sourceMode": "customer",
        "pricingId": null,
        "priceListId": null,
        "providerId": null,
        "providerLabel": null,
        "engineCode": null,
        "modelCode": null,
        "modelLabel": null
      },
      "asr": {
        "configured": true,
        "sourceMode": "ai4call",
        "pricingId": 9,
        "priceListId": 3,
        "providerId": "azure",
        "providerLabel": "AZURE",
        "engineCode": "asr_azure_multi",
        "modelCode": "asr_azure_multi",
        "modelLabel": "asr_azure_multi"
      },
      "llm": {
        "configured": true,
        "sourceMode": "ai4call",
        "pricingId": 16,
        "priceListId": 2,
        "providerId": "openai",
        "providerLabel": "openai",
        "engineCode": "gpt-4.1-mini",
        "modelCode": "gpt-4.1-mini",
        "modelLabel": "GPT-4.1 mini"
      }
    }
  }
}

Binding runtime dell'assistente

Knowledge

​

Risorse knowledge canoniche del cliente e associazioni agli assistenti

Knowledge Operations

Elenca le knowledge del cliente

​

Restituisce le knowledge del cliente più quelle fornite da AI4CALL, dalla più recente. Quelle condivise hanno isShared: true: si possono associare ai propri assistenti ma non modificare.

Ogni voce torna completa dei suoi trigger, ordinati per sortOrder.

Query Parameters

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di elementi restituiti in una pagina con paginazione a cursore. Ometti sia limit sia cursor per mantenere la risposta legacy non paginata.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor dalla pagina precedente.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/knowledge
curl https://client-api.ai4call.com/api/v1/knowledge \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Knowledge items retrieved successfully.",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "knowledges": [
      {
        "id": 7,
        "title": "Orari e sedi",
        "defaultResponse": "Siamo aperti dal lunedì al venerdì, dalle 9 alle 18.",
        "rules": null,
        "defaultPostAction": "ask_if_needs_more",
        "isShared": false,
        "triggers": [
          {
            "id": 21,
            "query": "Quali sono gli orari di apertura?",
            "aiInstructions": null,
            "specificResponse": null,
            "postAction": null,
            "sortOrder": 1
          }
        ],
        "createdAt": "2026-08-01T09:15:00.000Z",
        "updatedAt": "2026-08-20T11:02:00.000Z"
      }
    ]
  },
  "meta": {
    "count": 1
  }
}

Knowledge disponibili per il cliente

Crea una knowledge

​

Crea una knowledge di proprietà del cliente.

Una knowledge è un insieme di richieste riconosciute, i trigger, con cosa l'assistente deve rispondere. Viene inserita nel prompt di ogni assistente a cui è associata, quindi crearla non basta: va associata con PUT /api/v1/catalog/assistants/{assistantApiKey}/knowledge.

Regole operative:

  • triggers può essere omesso o vuoto: la knowledge risponde allora sempre con defaultResponse
  • un trigger senza specificResponse ricade sul defaultResponse della knowledge
  • un trigger senza postAction ricade sul defaultPostAction della knowledge
  • aiInstructions guida come il modello usa la risposta, senza riscrivere la risposta stessa
  • sortOrder è opzionale: se omesso vale l'ordine dell'array

Body·

required
application/json

Creazione di una knowledge.

triggers può essere omesso o vuoto: la knowledge risponde allora sempre con defaultResponse.

  • defaultResponse
    Type: string
    min length:  
    1
    required

    Risposta predefinita usata quando un trigger non ha una risposta specifica.

  • title
    Type: string
    max length:  
    255
    required

    Titolo leggibile della nuova knowledge.

  • defaultPostAction
    Type: string
    max length:  
    50

    Vale ask_if_needs_more se omesso

  • rules
    Type: string | null

    Vincoli opzionali applicati all'intera knowledge.

  • triggers
    Type:

    Lista iniziale dei trigger della knowledge.

    Properties: 5

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/api/v1/knowledge
curl https://client-api.ai4call.com/api/v1/knowledge \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "title": "Orari e sedi",
  "defaultResponse": "Siamo aperti dal lunedì al venerdì, dalle 9 alle 18.",
  "defaultPostAction": "ask_if_needs_more",
  "triggers": [
    {
      "query": "Quali sono gli orari di apertura?"
    },
    {
      "query": "Siete aperti il sabato?",
      "specificResponse": "Il sabato siamo chiusi."
    }
  ]
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "knowledge": {
      "id": 1,
      "title": "Orari e sedi",
      "defaultResponse": "example",
      "rules": "example",
      "defaultPostAction": "ask_if_needs_more",
      "isShared": true,
      "triggers": [
        {
          "id": 1,
          "query": "Quali sono gli orari di apertura?",
          "aiInstructions": "example",
          "specificResponse": "example",
          "postAction": "example",
          "sortOrder": 1
        }
      ],
      "createdAt": "2026-09-28T10:30:00.000Z",
      "updatedAt": "2026-09-28T10:30:00.000Z"
    }
  }
}

Knowledge creata

Recupera una singola knowledge

​

Restituisce una singola knowledge completa dei suoi trigger. Vale per le knowledge del cliente e per quelle condivise.

Path Parameters

  • knowledgeId
    Type: integer
    min:  
    1
    required

    Id della knowledge

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/knowledge/{knowledgeId}
curl https://client-api.ai4call.com/api/v1/knowledge/7 \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "knowledge": {
      "id": 1,
      "title": "Orari e sedi",
      "defaultResponse": "example",
      "rules": "example",
      "defaultPostAction": "ask_if_needs_more",
      "isShared": true,
      "triggers": [
        {
          "id": 1,
          "query": "Quali sono gli orari di apertura?",
          "aiInstructions": "example",
          "specificResponse": "example",
          "postAction": "example",
          "sortOrder": 1
        }
      ],
      "createdAt": "2026-09-28T10:30:00.000Z",
      "updatedAt": "2026-09-28T10:30:00.000Z"
    }
  }
}

Knowledge trovata

Aggiorna una knowledge

​

Aggiorna una knowledge con semantica PATCH merge.

Regole operative:

  • almeno un campo deve essere presente, i campi omessi mantengono il valore attuale
  • triggers, se presente, sostituisce l'intera lista: va inviata completa, oppure omessa per lasciare i trigger invariati. Inviare [] li rimuove tutti
  • le knowledge fornite da AI4CALL (isShared: true) non sono modificabili e rispondono 404

Le modifiche hanno effetto su ogni assistente a cui la knowledge è associata, senza riassociarla.

Path Parameters

  • knowledgeId
    Type: integer
    min:  
    1
    required

    Id della knowledge

Body·

required
application/json

PATCH merge di una knowledge.

Regole operative:

  • almeno un campo deve essere presente
  • i campi omessi mantengono il valore attuale
  • triggers, se presente, sostituisce l'intera lista: va inviata completa, oppure omessa per lasciare i trigger invariati. Inviare [] li rimuove tutti
  • le knowledge con isShared: true non sono modificabili
  • defaultPostAction
    Type: string
    max length:  
    50

    Nuova post-action predefinita per i trigger che non ne definiscono una propria.

  • defaultResponse
    Type: string
    min length:  
    1

    Nuova risposta predefinita della knowledge.

  • rules
    Type: string | null

    Nuovi vincoli opzionali della knowledge.

  • title
    Type: string
    max length:  
    255

    Nuovo titolo della knowledge.

  • triggers
    Type:

    Lista completa sostitutiva dei trigger quando questo campo viene inviato.

    Properties: 5

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/knowledge/{knowledgeId}
curl https://client-api.ai4call.com/api/v1/knowledge/7 \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "defaultResponse": "Siamo aperti dal lunedì al venerdì, dalle 9 alle 19."
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "knowledge": {
      "id": 1,
      "title": "Orari e sedi",
      "defaultResponse": "example",
      "rules": "example",
      "defaultPostAction": "ask_if_needs_more",
      "isShared": true,
      "triggers": [
        {
          "id": 1,
          "query": "Quali sono gli orari di apertura?",
          "aiInstructions": "example",
          "specificResponse": "example",
          "postAction": "example",
          "sortOrder": 1
        }
      ],
      "createdAt": "2026-09-28T10:30:00.000Z",
      "updatedAt": "2026-09-28T10:30:00.000Z"
    }
  }
}

Knowledge aggiornata

Elimina una knowledge

​

Elimina definitivamente la knowledge, i suoi trigger e ogni associazione con gli assistenti del cliente. Gli assistenti coinvolti smettono semplicemente di portarla nel prompt.

Le knowledge fornite da AI4CALL non sono eliminabili e rispondono 404.

Path Parameters

  • knowledgeId
    Type: integer
    min:  
    1
    required

    Id della knowledge

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for delete/api/v1/knowledge/{knowledgeId}
curl https://client-api.ai4call.com/api/v1/knowledge/7 \
  --request DELETE \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "deleted": true
  }
}

Knowledge eliminata

Elenca le knowledge associate a un assistente

​

Restituisce le knowledge inserite nel prompt di questo assistente, nell'ordine in cui vengono applicate, insieme al loro contenuto completo, cosi non serve una seconda chiamata.

Un'associazione che punta a una knowledge eliminata viene scartata dalla risposta.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/assistants/{assistantId}/knowledge
curl https://client-api.ai4call.com/api/v1/assistants/205/knowledge \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant knowledge associations retrieved successfully.",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "assistantApiKey": "ai4call_sk_abc123",
    "associations": [
      {
        "knowledgeId": 7,
        "sortOrder": 1
      }
    ],
    "knowledges": [
      {
        "id": 7,
        "title": "Orari e sedi",
        "defaultResponse": "Siamo aperti dal lunedì al venerdì, dalle 9 alle 18.",
        "rules": null,
        "defaultPostAction": "ask_if_needs_more",
        "isShared": false,
        "triggers": [],
        "createdAt": "2026-08-01T09:15:00.000Z",
        "updatedAt": "2026-08-20T11:02:00.000Z"
      }
    ]
  },
  "meta": {
    "count": 1
  }
}

Knowledge associate

Imposta le knowledge associate a un assistente

​

Sostituisce interamente le associazioni dell'assistente: quello che invii diventa l'elenco completo.

Due forme accettate:

  • associations, quando l'ordine conta e vuoi dichiararlo
  • knowledgeIds, quando basta l'ordine dell'array

Sono alternative. Una lista vuota stacca tutte le knowledge.

Si possono associare sia le knowledge proprie sia quelle condivise; un id che non è né tuo ne condiviso fa fallire l'intera chiamata con 400, senza modifiche parziali.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

Sostituisce interamente le associazioni knowledge dell'assistente.

Inviare associations quando l'ordine conta, knowledgeIds quando basta l'ordine dell'array. Le due forme sono alternative; una lista vuota stacca tutto.

Si possono associare sia le knowledge proprie sia quelle condivise.

  • associations
    Type: array of object

    Valore da inviare per associations nella richiesta AssistantKnowledgeAssociationsRequest.

    Properties: 2
  • knowledgeIds
    Type: array of integer

    Valore da inviare per knowledgeIds nella richiesta AssistantKnowledgeAssociationsRequest.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for put/api/v1/assistants/{assistantId}/knowledge
curl https://client-api.ai4call.com/api/v1/assistants/205/knowledge \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "knowledgeIds": [
    7,
    12
  ]
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistantApiKey": "ai4call_sk_example",
    "associations": [
      {
        "knowledgeId": 1,
        "sortOrder": 1
      }
    ],
    "knowledges": [
      {
        "id": 1,
        "title": "Orari e sedi",
        "defaultResponse": "example",
        "rules": "example",
        "defaultPostAction": "ask_if_needs_more",
        "isShared": true,
        "triggers": [
          {
            "id": 1,
            "query": "Quali sono gli orari di apertura?",
            "aiInstructions": "example",
            "specificResponse": "example",
            "postAction": "example",
            "sortOrder": 1
          }
        ],
        "createdAt": "2026-09-28T10:30:00.000Z",
        "updatedAt": "2026-09-28T10:30:00.000Z"
      }
    ]
  }
}

Associazioni aggiornate

Filler Phrase Lists

​

Liste filler riutilizzabili canoniche e associazioni agli assistenti

Filler Phrase Lists Operations

Lista le liste filler del cliente

​

Lista le liste filler del cliente

Query Parameters

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di elementi restituiti in una pagina con paginazione a cursore. Ometti sia limit sia cursor per mantenere la risposta legacy non paginata.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor dalla pagina precedente.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/filler-phrase-lists
curl https://client-api.ai4call.com/api/v1/filler-phrase-lists \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "lists": [
      {
        "id": "example-id",
        "name": "Example",
        "phrases": [
          "example"
        ],
        "isDefault": true,
        "createdAt": "2026-09-28T10:30:00.000Z",
        "updatedAt": "2026-09-28T10:30:00.000Z"
      }
    ]
  }
}

Liste filler disponibili

Crea una lista filler

​

Crea una lista filler

Body·

required
application/json
  • id
    Type: string
    max length:  
    100
    required

    Valore da inviare per id nella richiesta FillerPhraseListCreateRequest.

  • name
    Type: string
    max length:  
    255
    required

    Valore da inviare per name nella richiesta FillerPhraseListCreateRequest.

  • phrases
    Type: array of string

    Valore da inviare per phrases nella richiesta FillerPhraseListCreateRequest.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/api/v1/filler-phrase-lists
curl https://client-api.ai4call.com/api/v1/filler-phrase-lists \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "id": "support_waiting",
  "name": "Attesa supporto",
  "phrases": [
    "Un attimo, sto verificando.",
    "Rimanga in linea, controllo subito."
  ]
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "list": {
      "id": "example-id",
      "name": "Example",
      "phrases": [
        "example"
      ],
      "isDefault": true,
      "createdAt": "2026-09-28T10:30:00.000Z",
      "updatedAt": "2026-09-28T10:30:00.000Z"
    }
  }
}

Lista filler creata

Aggiorna una lista filler

​

Aggiorna una lista filler

Path Parameters

  • listId
    Type: string
    required

Body·

required
application/json
  • name
    Type: string
    max length:  
    255
    required

    Valore da inviare per name nella richiesta FillerPhraseListUpdateRequest.

  • phrases
    Type: array of string

    Valore da inviare per phrases nella richiesta FillerPhraseListUpdateRequest.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for put/api/v1/filler-phrase-lists/{listId}
curl 'https://client-api.ai4call.com/api/v1/filler-phrase-lists/{listId}' \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "name": "Attesa supporto aggiornata",
  "phrases": [
    "Un attimo, sto verificando."
  ]
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "list": {
      "id": "example-id",
      "name": "Example",
      "phrases": [
        "example"
      ],
      "isDefault": true,
      "createdAt": "2026-09-28T10:30:00.000Z",
      "updatedAt": "2026-09-28T10:30:00.000Z"
    }
  }
}

Lista filler aggiornata

Elimina una lista filler

​

Elimina una lista filler

Path Parameters

  • listId
    Type: string
    required

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for delete/api/v1/filler-phrase-lists/{listId}
curl 'https://client-api.ai4call.com/api/v1/filler-phrase-lists/{listId}' \
  --request DELETE \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "deleted": true
  }
}

Lista filler eliminata

Recupera una lista filler

​

Recupera una lista di frasi filler appartenente al cliente autenticato.

Path Parameters

  • listId
    Type: string
    required

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/filler-phrase-lists/{listId}
curl 'https://client-api.ai4call.com/api/v1/filler-phrase-lists/{listId}' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "list": {
      "id": "example-id",
      "name": "Example",
      "phrases": [
        "example"
      ],
      "isDefault": true,
      "createdAt": "2026-09-28T10:30:00.000Z",
      "updatedAt": "2026-09-28T10:30:00.000Z"
    }
  }
}

Lista filler trovata

Recupera le liste filler associate all'assistente

​

Recupera le liste filler associate all'assistente

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/assistants/{assistantId}/filler-phrase-lists
curl https://client-api.ai4call.com/api/v1/assistants/205/filler-phrase-lists \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant filler phrase list associations retrieved successfully.",
  "requestId": "c3d93c2c-8f89-4a2e-b9ad-67d2746c9d16",
  "data": {
    "associations": {
      "waitingListIds": [
        "default_waiting",
        "support_waiting"
      ],
      "toolListIds": [
        "default_tool"
      ]
    }
  }
}

Associazioni liste filler

Salva le liste filler associate all'assistente

​

Salva le liste filler associate all'assistente

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json
  • toolListIds
    Type: array of string
    required
  • waitingListIds
    Type: array of string
    required

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for put/api/v1/assistants/{assistantId}/filler-phrase-lists
curl https://client-api.ai4call.com/api/v1/assistants/205/filler-phrase-lists \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "waitingListIds": [
    "default_waiting",
    "support_waiting"
  ],
  "toolListIds": [
    "default_tool"
  ]
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "associations": {
      "waitingListIds": [
        "example"
      ],
      "toolListIds": [
        "example"
      ]
    }
  }
}

Associazioni liste filler salvate

RAG

​

Gestione canonica delle collezioni RAG del cliente e dei relativi documenti

RAG Operations

Elenca tutte le collezioni RAG del cliente

​

Restituisce tutte le collection RAG disponibili per il cliente autenticato.

Usa questa risposta per compilare name nella PATCH /api/v1/assistants/{assistantApiKey}/runtime/rag.

Query Parameters

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di elementi restituiti in una pagina con paginazione a cursore. Ometti sia limit sia cursor per mantenere la risposta legacy non paginata.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor dalla pagina precedente.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/rag/collections
curl https://client-api.ai4call.com/api/v1/rag/collections \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "All client RAG collections retrieved successfully.",
  "requestId": "6cd7751e-0d03-4228-b607-c0e1e3c7c6be",
  "meta": {
    "count": 2
  },
  "data": {
    "collections": [
      {
        "id": "42",
        "name": "Listino AI4Call",
        "description": "Collezione demo documentazione prodotto",
        "collectionName": "ai4call-listino",
        "isActive": true,
        "maxChunkSize": 5000,
        "maxChunksPerFile": null,
        "createdAt": "2026-04-21T12:00:00.000Z",
        "updatedAt": "2026-04-21T12:00:00.000Z",
        "publicRagId": "rag_8K2mP9zQ4xL7"
      },
      {
        "id": "43",
        "name": "FAQ Globale",
        "description": "Collezione non ancora agganciata a un assistente",
        "collectionName": "faq-global",
        "isActive": true,
        "maxChunkSize": 5000,
        "maxChunksPerFile": null,
        "createdAt": "2026-04-21T12:05:00.000Z",
        "updatedAt": "2026-04-21T12:05:00.000Z",
        "publicRagId": "rag_4FaQ2zX8mN6"
      }
    ]
  }
}

Lista completa collezioni RAG del cliente, anche non associate ad alcun assistente

Crea una collezione RAG

​

Crea una collezione RAG del cliente e provisiona la relativa collezione nel vector store.

Body·

required
application/json

Crea una collezione RAG del cliente e provisiona la corrispondente collezione nel vector store.

  • name
    Type: string
    min length:  
    1
    required

    Valore da inviare per name nella richiesta RagCollectionCreateRequest.

  • description
    Type: string | null

    Valore da inviare per description nella richiesta RagCollectionCreateRequest.

  • maxChunkSize
    Type: integer
    min:  
    500
    max:  
    10000

    Valore da inviare per maxChunkSize nella richiesta RagCollectionCreateRequest.

  • maxChunksPerFile
    Type: integer | null
    min:  
    1

    Valore da inviare per maxChunksPerFile nella richiesta RagCollectionCreateRequest.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/api/v1/rag/collections
curl https://client-api.ai4call.com/api/v1/rag/collections \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "name": "Product Knowledge",
  "description": "Documentazione prodotto",
  "maxChunkSize": 5000,
  "maxChunksPerFile": null
}'

{
  "success": true,
  "message": "RAG collection created successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "collection": {
      "id": "42",
      "publicRagId": "rag_8K2mP9zQ4xL7",
      "name": "Product Knowledge",
      "description": "Documentazione prodotto",
      "collectionName": "collection_clNe_abC1234",
      "isActive": true,
      "maxChunkSize": 5000,
      "maxChunksPerFile": null,
      "createdAt": "2026-09-28T10:30:00.000Z",
      "updatedAt": "2026-09-28T10:30:00.000Z"
    }
  }
}

Collezione RAG creata

Elimina una collezione RAG

​

Elimina una collezione RAG del cliente non utilizzata e i metadati dei documenti memorizzati.

Path Parameters

  • ragId
    Type: string
    required

    publicRagId stabile della collection RAG. I valori legacy collectionName e name restano accettati.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for delete/api/v1/rag/collections/{ragId}
curl 'https://client-api.ai4call.com/api/v1/rag/collections/{ragId}' \
  --request DELETE \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "RAG collection deleted successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "id": "42",
    "name": "Product Knowledge",
    "collectionName": "collection_clNe_abC1234",
    "deleted": true
  }
}

Collezione RAG eliminata

Stima token e costo dei file RAG prima dell'upload

​

Stima token e costo dei file da caricare, usando lo stesso calcolo esposto dal portale prima della conferma upload.

Invia i file come multipart/form-data nel campo ripetibile files.

Body

required
application/json

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/api/v1/rag/documents/estimate
curl https://client-api.ai4call.com/api/v1/rag/documents/estimate \
  --request POST \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --form 'files=listino.pdf' \
  --form 'files=faq.txt'

{
  "success": true,
  "message": "RAG document upload token estimate retrieved successfully.",
  "requestId": "41d1c282-d1e4-48ff-b783-eb0c870e32b1",
  "data": {
    "totalTokens": 1200,
    "estimatedCost": 0.00042,
    "fileCount": 2,
    "processingTime": 34,
    "fileDetails": [
      {
        "name": "listino.pdf",
        "tokens": 1000
      }
    ],
    "raw": {
      "success": true
    }
  }
}

Stima token upload

Recupera lo stato di un upload RAG

​

Usa uploadId restituito dalla POST di upload per seguire lo stato della vettorializzazione, come nel portale.

Path Parameters

  • uploadId
    Type: string
    required

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/rag/uploads/{uploadId}
curl 'https://client-api.ai4call.com/api/v1/rag/uploads/{uploadId}' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "RAG document upload status retrieved successfully.",
  "requestId": "4801b93d-fac5-4a31-af92-f220ef3bb566",
  "data": {
    "uploadId": "upl_01HTZK",
    "status": "processing",
    "progress": 65,
    "processedFiles": 1,
    "totalFiles": 2,
    "currentFile": "faq.txt",
    "errors": [],
    "totalCost": 0.00042,
    "totalTokens": 1200,
    "results": [],
    "raw": {
      "status": "processing",
      "progress": 65
    }
  }
}

Stato corrente dell'upload

Elenca i file caricati in una collection RAG

​

Recupera i file della collezione RAG del cliente autenticato.

ragId è il publicRagId stabile restituito dall'elenco delle collezioni. I valori legacy collectionName e name restano accettati.

Path Parameters

  • ragId
    Type: string
    required

    publicRagId stabile della collection RAG. I valori legacy collectionName e name restano accettati.

Query Parameters

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di elementi restituiti in una pagina con paginazione a cursore. Ometti sia limit sia cursor per mantenere la risposta legacy non paginata.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor dalla pagina precedente.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/rag/collections/{ragId}/documents
curl 'https://client-api.ai4call.com/api/v1/rag/collections/{ragId}/documents' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "RAG collection documents retrieved successfully.",
  "requestId": "7a70be67-5988-4986-b082-d54a64cc6b01",
  "meta": {
    "count": 1
  },
  "data": {
    "documents": [
      {
        "id": "138",
        "collectionName": "collection_clNe_xvk6bab",
        "fileName": "listino.pdf",
        "fileSize": 245760,
        "uploadDate": "2026-04-21T12:00:00.000Z"
      }
    ]
  }
}

File presenti nella collection RAG

Carica file in una collection RAG

​

Carica uno o più file nella collezione RAG, avvia la vettorizzazione su Chroma e salva il dettaglio del file per renderlo visibile nelle GET successive.

Invia i file come multipart/form-data nel campo ripetibile files. ragId è il publicRagId stabile restituito dall'elenco delle collezioni. I valori legacy collectionName e name restano accettati.

Path Parameters

  • ragId
    Type: string
    required

    publicRagId stabile della collection RAG. I valori legacy collectionName e name restano accettati.

Body

required
application/json

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/api/v1/rag/collections/{ragId}/documents
curl 'https://client-api.ai4call.com/api/v1/rag/collections/{ragId}/documents' \
  --request POST \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --form 'files=listino.pdf' \
  --form 'files=faq.txt'

{
  "success": true,
  "message": "RAG collection documents upload started successfully.",
  "requestId": "9bb4c2e8-676a-4a86-93f0-c7ce53b43ac2",
  "meta": {
    "count": 2
  },
  "data": {
    "collectionName": "collection_clNe_xvk6bab",
    "name": "Listino AI4Call",
    "uploadId": "upl_01HTZK",
    "backupFiles": [
      "listino.pdf_124",
      "faq.txt_124"
    ],
    "documents": [
      {
        "id": "138",
        "collectionName": "collection_clNe_xvk6bab",
        "fileName": "listino.pdf",
        "fileSize": 245760,
        "uploadDate": "2026-04-21T12:00:00.000Z"
      },
      {
        "id": "139",
        "collectionName": "collection_clNe_xvk6bab",
        "fileName": "faq.txt",
        "fileSize": 8192,
        "uploadDate": "2026-04-21T12:00:01.000Z"
      }
    ],
    "upstream": {
      "success": true,
      "uploadId": "upl_01HTZK"
    }
  }
}

Upload accettato e metadata file salvati

Elimina un file da una collection RAG

​

Elimina il documento dal vector store Chroma e rimuove il dettaglio del file dall'elenco della collezione.

ragId è il publicRagId stabile restituito dall'elenco delle collezioni. I valori legacy collectionName e name restano accettati.

Path Parameters

  • ragId
    Type: string
    required

    publicRagId stabile della collection RAG. I valori legacy collectionName e name restano accettati.

  • fileName
    Type: string
    required

    Nome file da eliminare, preso da data.documents[].fileName.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for delete/api/v1/rag/collections/{ragId}/documents/{fileName}
curl 'https://client-api.ai4call.com/api/v1/rag/collections/{ragId}/documents/{fileName}' \
  --request DELETE \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "RAG collection document deleted successfully.",
  "requestId": "93f5bcd1-625b-4a7c-a653-1fb742ef80cf",
  "data": {
    "collectionName": "collection_clNe_xvk6bab",
    "name": "Listino AI4Call",
    "fileName": "listino.pdf",
    "metadataDeleted": true,
    "backupFilesDeleted": [
      "listino.pdf_124"
    ],
    "upstream": {
      "success": true,
      "message": "Documento eliminato"
    }
  }
}

File eliminato dalla collection RAG

Restituisce la configurazione RAG corrente di uno specifico assistente

​

Restituisce lo stato RAG runtime dell'assistente.

Se enabled è true, usa il campo name di questa risposta per compilare la PATCH /api/v1/assistants/{assistantApiKey}/runtime/rag quando vuoi mantenere, sostituire o disabilitare la collection corrente.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/assistants/{assistantId}/rag/collections
curl https://client-api.ai4call.com/api/v1/assistants/205/rag/collections \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant RAG configuration retrieved successfully.",
  "data": {
    "enabled": true,
    "name": "Listino AI4Call",
    "returnedChunks": 4,
    "kbPrompt": "Usa la knowledge base come fonte prioritaria."
  },
  "requestId": "7f0d2f4a-c9a8-4f8d-8cbb-4e55c4e0f6bd"
}

Configurazione RAG runtime dell'assistente

Catalog Tools

​

Tool runtime disponibili lato cliente e tool associati all'assistente

Catalog Tools Operations

Aggiorna le associazioni tool dell'assistente

​

Aggiorna le associazioni tool dell'assistente con semantica PATCH merge, replicando il comportamento del portale.

Parametri modificabili:

  • tools
  • tools[].toolName
  • tools[].subscriptionName
  • deleteTools
  • deleteTools[].toolName
  • deleteTools[].subscriptionName
  • toolIds
  • mcpToolsBySubscription
  • mcpToolsBySubscription.{subscription}.{plugin}.tools
  • mcpToolsBySubscription.{subscription}.{plugin}.description
  • mcpToolsBySubscription.{subscription}.{plugin}.subscriptionName

Il payload consigliato è quello high-level by-name:

  • tools: lista di { toolName, subscriptionName } da aggiungere
  • deleteTools: lista di { toolName, subscriptionName } da rimuovere
  • se aggiungi un custom_tool, usa toolName = toolName e subscriptionName = null
  • se aggiungi o rimuovi un plugin_tool, usa toolName = toolName e subscriptionName = instanceName
  • se aggiungi o rimuovi un custom_mcp_tool, usa toolName = toolName e subscriptionName = instanceName

Come recuperare i valori:

  • per aggiungere tool parti da GET /api/v1/catalog/tools
  • per rimuovere tool parti da GET /api/v1/catalog/assistants/{assistantApiKey}/tools
  • riusa sempre toolName come toolName
  • riusa sempre instanceName come subscriptionName per i target MCP
  • se instanceName è null, il tool è un custom_tool classico e va inviato con subscriptionName: null

Il payload low-level portale (toolIds + mcpToolsBySubscription) resta supportato per compatibilità avanzata. Sugli assistenti voice_to_voice, i tool HTTP vengono scritti in endpointTools e i tool MCP in mcpServers nel root JSON voice-llm.

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

Payload di aggiornamento associazioni tool.

Puoi aggiornare solo i tool classici, solo i tool MCP oppure entrambi nella stessa chiamata. Se usi la shape by-name, i valori vanno sempre ricavati dai GET catalog documentati sopra.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/tools
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/tools \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "tools": [
    {
      "toolName": "send_email",
      "subscriptionName": null
    },
    {
      "toolName": "create_ticket",
      "subscriptionName": "Webhook CRM"
    },
    {
      "toolName": "sheets_append_row",
      "subscriptionName": "Google Sheets Produzione"
    }
  ],
  "deleteTools": [
    {
      "toolName": "send_sms",
      "subscriptionName": null
    },
    {
      "toolName": "sheets_search_rows",
      "subscriptionName": "Google Sheets Produzione"
    }
  ]
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistantApiKey": "ai4call_sk_example",
    "assistantId": "example-id",
    "service": "tools",
    "configuration": {
      "toolIds": [
        "example"
      ],
      "mcpToolsBySubscription": {},
      "hasMcpTools": true
    }
  }
}

Associazioni tool aggiornate

Elenca tutti i tool runtime disponibili del cliente

​

Restituisce il catalogo completo dei tool che il cliente può associare a un assistente.

Usa questa risposta per compilare tools nella PATCH /api/v1/assistants/{assistantApiKey}/runtime/tools:

  • riusa toolName come toolName
  • se toolType e custom_tool, invia subscriptionName: null
  • se toolType e plugin_tool, invia subscriptionName uguale a instanceName
  • se toolType e custom_mcp_tool, invia subscriptionName uguale a instanceName

Query Parameters

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di elementi restituiti in una pagina con paginazione a cursore. Ometti sia limit sia cursor per mantenere la risposta legacy non paginata.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor dalla pagina precedente.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/tools
curl https://client-api.ai4call.com/api/v1/catalog/tools \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Available tools retrieved successfully.",
  "requestId": "21715377-4492-44af-91a7-af50058a4bac",
  "meta": {
    "count": 4,
    "customToolCount": 1,
    "pluginToolCount": 2,
    "customMcpToolCount": 1
  },
  "data": {
    "tools": [
      {
        "toolType": "custom_tool",
        "toolName": "crm-search",
        "instanceName": null,
        "pluginName": null,
        "description": "Cerca un lead nel CRM aziendale",
        "parameters": null,
        "method": "POST",
        "endpoint": "https://crm.example.com/api/search"
      },
      {
        "toolType": "plugin_tool",
        "toolName": "list_workflows",
        "instanceName": "Marketing",
        "pluginName": "n8n",
        "description": "Elenca i workflow disponibili",
        "parameters": {
          "type": "object"
        },
        "method": null,
        "endpoint": null
      },
      {
        "toolType": "plugin_tool",
        "toolName": "execute_workflow",
        "instanceName": "Marketing",
        "pluginName": "n8n",
        "description": "Esegue un workflow n8n",
        "parameters": {
          "type": "object"
        },
        "method": null,
        "endpoint": null
      },
      {
        "toolType": "custom_mcp_tool",
        "toolName": "search_contact",
        "instanceName": "CRM Custom",
        "pluginName": "CRM Custom",
        "description": "Cerca un contatto nel CRM",
        "parameters": {
          "type": "object"
        },
        "method": null,
        "endpoint": null
      }
    ]
  }
}

Lista unificata di plugin tool, custom MCP tool e custom tool senza assistantApiKey in input

Elenca i tool runtime associati all'assistente

​

Restituisce i tool attualmente associati all'assistente.

Usa questa risposta per compilare deleteTools nella PATCH /api/v1/assistants/{assistantApiKey}/runtime/tools:

  • riusa toolName come toolName
  • se toolType e custom_tool, invia subscriptionName: null
  • se toolType e plugin_tool, invia subscriptionName uguale a instanceName
  • se toolType e custom_mcp_tool, invia subscriptionName uguale a instanceName

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/catalog/assistants/{assistantId}/tools
curl https://client-api.ai4call.com/api/v1/catalog/assistants/205/tools \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Assistant associated tools retrieved successfully.",
  "requestId": "5e6fe40d-8f7f-4406-95c0-d3a5c4c90fd3",
  "meta": {
    "count": 3,
    "customToolCount": 1,
    "pluginToolCount": 1,
    "customMcpToolCount": 1
  },
  "data": {
    "tools": [
      {
        "toolType": "custom_tool",
        "toolName": "crm-search",
        "instanceName": null,
        "pluginName": null,
        "description": "Cerca un lead nel CRM aziendale",
        "parameters": null,
        "method": "POST",
        "endpoint": "https://crm.example.com/api/search"
      },
      {
        "toolType": "plugin_tool",
        "toolName": "execute_workflow",
        "instanceName": "Marketing",
        "pluginName": "n8n",
        "description": "Esegue un workflow n8n",
        "parameters": {
          "type": "object"
        },
        "method": null,
        "endpoint": null
      },
      {
        "toolType": "custom_mcp_tool",
        "toolName": "search_contact",
        "instanceName": "CRM Custom",
        "pluginName": "CRM Custom",
        "description": "Cerca un contatto nel CRM",
        "parameters": {
          "type": "object"
        },
        "method": null,
        "endpoint": null
      }
    ]
  }
}

Lista unificata di plugin tool, custom MCP tool e custom tool associati all'assistente

Catalog RAG

​

Alias legacy sotto catalog per le collezioni RAG del cliente e degli assistenti. Mantenuti solo per la compatibilità v1.

Catalog RAG Operations

Aggiorna la configurazione runtime RAG dell'assistente

​

Aggiorna la configurazione RAG dell'assistente con semantica PATCH merge, allineata al portale.

Parametri modificabili:

  • enabled
  • name
  • returnedChunks
  • kbPrompt

Come recuperare i dati:

  • usa GET /api/v1/catalog/rag/collections per ottenere le collection RAG disponibili
  • riusa name della collection come name

Regole operative:

  • enabled: true abilita il RAG e richiede una collection valida
  • enabled: false rimuove la knowledge base RAG dall'assistente
  • returnedChunks replica il setting del portale
  • kbPrompt aggiorna le istruzioni knowledge base dell'assistente
  • i campi omessi mantengono il valore attuale, se presente
  • sugli assistenti voice_to_voice il backend aggiorna knowledgeBases nel root JSON voice-llm

Path Parameters

  • assistantId
    Type: string
    min length:  
    1
    max length:  
    128
    required

    Identificativo pubblico dell'assistente. L'attuale assistantId numerico è canonico; il valore legacy assistantApiKey resta accettato durante il periodo di compatibilità v1.

Body·

required
application/json

PATCH merge della configurazione RAG dell'assistente, allineata al comportamento del portale.

Regole operative:

  • almeno uno tra enabled, name, returnedChunks, kbPrompt deve essere presente
  • usa GET /api/v1/catalog/rag/collections per recuperare il name
  • enabled: true richiede una collection valida e attiva
  • inviando name con una collection valida, il RAG viene attivato se non è esplicitamente disabilitato
  • enabled: false rimuove la knowledge base RAG dall'assistente e pulisce returnedChunks e kbPrompt
  • returnedChunks segue il setting del portale e deve stare tra 1 e 10
  • kbPrompt: null rimuove le istruzioni knowledge base dell'assistente
  • i campi omessi mantengono il valore corrente, se già presente
  • enabled
    Type: boolean

    Abilita o disabilita il RAG per l'assistente. Se false, la knowledge base RAG viene rimossa.

  • kbPrompt
    Type: string | null

    Istruzioni knowledge base dell'assistente. Se null, il campo viene rimosso dal runtime LLM.

  • name
    Type: string | null

    Nome della collection RAG da associare. Va recuperato da GET /api/v1/catalog/rag/collections. Se null, la selection viene azzerata.

  • returnedChunks
    Type: integer
    min:  
    1
    max:  
    10

    Numero di frammenti rilevanti da ritornare dalla knowledge base.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/rag
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/rag \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "enabled": true,
  "name": "Listino AI4Call",
  "returnedChunks": 4,
  "kbPrompt": "Usa la knowledge base come fonte prioritaria."
}'

{
  "success": true,
  "message": "Operation completed successfully.",
  "requestId": "00000000-0000-4000-8000-000000000000",
  "data": {
    "assistantApiKey": "ai4call_sk_example",
    "assistantId": "example-id",
    "service": "rag",
    "configuration": {
      "enabled": true,
      "returnedChunks": 1
    }
  }
}

Configurazione runtime RAG aggiornata

Account Analytics

​

Storico chiamate, ricariche, RAG, SMS e tool responses del cliente autenticato

Account Analytics Operations

Recupera lo storico chiamate inbound del cliente autenticato

​

Restituisce le chiamate inbound del cliente con dettaglio costi e token per ogni sessione.

Filtri disponibili:

  • startDate e endDate filtrano per data di creazione (createdAt)
  • entrambi sono opzionali; se omessi, il backend restituisce tutto lo storico disponibile

Come leggere i costi:

  • tutti i costi sono in EUR
  • totalCost = llmInputCost + llmOutputCost + ttsCost + asrCost + ragCost + trafficCost + trafficCostOutbound

Query Parameters

  • startDate
    Type: stringFormat: date

    Data inizio filtro (YYYY-MM-DD, inclusa)

  • endDate
    Type: stringFormat: date

    Data fine filtro (YYYY-MM-DD, inclusa)

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di record. Se omesso insieme a cursor, mantiene il comportamento legacy non paginato.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor per leggere la pagina successiva.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/analytics/calls
curl 'https://client-api.ai4call.com/api/v1/account/analytics/calls?startDate=2026-04-01&endDate=2026-04-24&limit=50' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Account analytics calls retrieved successfully.",
  "requestId": "9755db58-3e8d-4a09-b3a1-c68fd6f70c8a",
  "data": {
    "records": [
      {
        "cdrId": 1042,
        "assistantApiKey": "ai4call_sk_abc123",
        "assistantName": "Assistente Demo",
        "callerNumber": "+393331234567",
        "uuid": "7e4c2a91-1234-5678-abcd-ef0123456789",
        "billsec": 92,
        "dialstatus": "ANSWERED",
        "inputTokens": 320,
        "outputTokens": 180,
        "ragTokens": 0,
        "llmInputCost": 0.0003,
        "llmOutputCost": 0.0002,
        "ttsCost": 0.0015,
        "asrCost": 0.001,
        "ragCost": 0,
        "trafficCost": 0.0046,
        "trafficCostOutbound": 0,
        "totalCost": 0.0076,
        "createdAt": "2026-04-24T10:15:00.000Z"
      }
    ]
  },
  "meta": {
    "count": 1
  }
}

Storico chiamate inbound

Recupera lo storico chiamate outbound del cliente autenticato

​

Restituisce le chiamate outbound del cliente con dettaglio costi di traffico per ogni sessione.

Filtri disponibili:

  • startDate e endDate filtrano per data di creazione (createdAt)
  • internalId filtra una singola chiamata outbound usando l'identificativo interno generato da AI4Call
  • il filtro del cliente autenticato viene applicato sempre, anche quando internalId è presente
  • se internalId e omesso, il backend restituisce lo storico disponibile del cliente autenticato

Query Parameters

  • internalId
    Type: Format: uuid

    Filtra per l'UUID outbound generato da AI4Call.

    UUID generato da AI4Call per correlare richiesta outbound, callback e ricerca dello stato finale di chiamata.

  • internal_id
    Type: Format: uuid
    deprecated

    Alias legacy di internalId.

    UUID generato da AI4Call per correlare richiesta outbound, callback e ricerca dello stato finale di chiamata.

  • startDate
    Type: stringFormat: date

    Data inizio filtro (YYYY-MM-DD, inclusa)

  • endDate
    Type: stringFormat: date

    Data fine filtro (YYYY-MM-DD, inclusa)

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di record. Se omesso insieme a cursor, mantiene il comportamento legacy non paginato.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor per leggere la pagina successiva.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/analytics/calls-outbound
curl 'https://client-api.ai4call.com/api/v1/account/analytics/calls-outbound?internalId=4f9ab147-ef47-4b54-9987-1dd30288c610&internal_id=4f9ab147-ef47-4b54-9987-1dd30288c610&startDate=2026-04-01&endDate=2026-04-24&limit=50' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Account analytics calls outbound retrieved successfully.",
  "requestId": "9755db58-3e8d-4a09-b3a1-c68fd6f70c8b",
  "data": {
    "records": [
      {
        "uuid": "9f1a3b72-5678-1234-dcba-ab9876543210",
        "callId": "CALL-20260424-001",
        "internalId": "4f9ab147-ef47-4b54-9987-1dd30288c610",
        "internal_id": "4f9ab147-ef47-4b54-9987-1dd30288c610",
        "assistantApiKey": "ai4call_sk_abc123",
        "assistantName": "Assistente Demo",
        "destination": "+390212345678",
        "dialstatus": "ANSWERED",
        "process": "outbound_campaign",
        "billsec": 65,
        "listId": "42",
        "listCall": "Campagna Aprile",
        "callResultUrl": "https://example.com/webhooks/ai4call/outbound-result",
        "url_esito_chiamata": "https://example.com/webhooks/ai4call/outbound-result",
        "trafficCostOutbound": 0.0033,
        "createdAt": "2026-04-24T11:00:00.000Z"
      }
    ]
  },
  "meta": {
    "count": 1
  }
}

Storico chiamate outbound

Recupera lo storico chiamate Pre-Call MCP del cliente autenticato

​

Restituisce le invocazioni Pre-Call MCP del cliente con dettaglio token e costi LLM per ogni richiesta.

Il Pre-Call MCP esegue validazioni numeriche e configurazioni MCP prima che la chiamata venga instradata all'assistente.

Filtri disponibili:

  • startDate e endDate filtrano per data di creazione (createdAt)
  • entrambi sono opzionali; se omessi, il backend restituisce tutto lo storico disponibile

Query Parameters

  • startDate
    Type: stringFormat: date

    Data inizio filtro (YYYY-MM-DD, inclusa)

  • endDate
    Type: stringFormat: date

    Data fine filtro (YYYY-MM-DD, inclusa)

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di record. Se omesso insieme a cursor, mantiene il comportamento legacy non paginato.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor per leggere la pagina successiva.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/analytics/pre-call
curl 'https://client-api.ai4call.com/api/v1/account/analytics/pre-call?startDate=2026-04-01&endDate=2026-04-24&limit=50' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Account analytics pre-call retrieved successfully.",
  "requestId": "9755db58-3e8d-4a09-b3a1-c68fd6f70c8c",
  "data": {
    "records": [
      {
        "cdrId": "501",
        "assistantApiKey": "ai4call_sk_abc123",
        "assistantName": "Assistente Demo",
        "callerId": "+393331234567",
        "uuid": null,
        "inputTokens": 120,
        "outputTokens": 60,
        "inputCost": 0.00012,
        "outputCost": 0.00006,
        "totalCost": 0.00018,
        "createdAt": "2026-04-24T10:14:55.000Z"
      }
    ]
  },
  "meta": {
    "count": 1
  }
}

Storico invocazioni Pre-Call MCP

Recupera lo storico chiamate Post-Call MCP del cliente autenticato

​

Restituisce le invocazioni Post-Call MCP del cliente con dettaglio token e costi LLM per ogni richiesta.

Il Post-Call MCP esegue tool e automazioni dopo la chiusura della chiamata, usando il contesto della conversazione conclusa.

Filtri disponibili:

  • startDate e endDate filtrano per data di creazione (createdAt)
  • entrambi sono opzionali; se omessi, il backend restituisce tutto lo storico disponibile

Query Parameters

  • startDate
    Type: stringFormat: date

    Data inizio filtro (YYYY-MM-DD, inclusa)

  • endDate
    Type: stringFormat: date

    Data fine filtro (YYYY-MM-DD, inclusa)

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di record. Se omesso insieme a cursor, mantiene il comportamento legacy non paginato.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor per leggere la pagina successiva.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/analytics/post-call
curl 'https://client-api.ai4call.com/api/v1/account/analytics/post-call?startDate=2026-04-01&endDate=2026-04-24&limit=50' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Account analytics post-call retrieved successfully.",
  "requestId": "9755db58-3e8d-4a09-b3a1-c68fd6f70c8c",
  "data": {
    "records": [
      {
        "cdrId": "501",
        "assistantApiKey": "ai4call_sk_abc123",
        "assistantName": "Assistente Demo",
        "callerId": "+393331234567",
        "uuid": null,
        "inputTokens": 120,
        "outputTokens": 60,
        "inputCost": 0.00012,
        "outputCost": 0.00006,
        "totalCost": 0.00018,
        "createdAt": "2026-04-24T10:14:55.000Z"
      }
    ]
  },
  "meta": {
    "count": 1
  }
}

Storico invocazioni Post-Call MCP

Recupera lo storico ricariche del cliente autenticato

​

Restituisce i movimenti di ricarica del credito del cliente.

Filtri disponibili:

  • startDate e endDate filtrano per data di creazione (createdAt)
  • entrambi sono opzionali; se omessi, il backend restituisce tutto lo storico disponibile

Valori di status:

  • completed — ricarica completata e credito accreditato
  • pending — transazione in attesa di conferma dal gateway
  • failed — transazione fallita
  • cancelled — transazione annullata

Query Parameters

  • startDate
    Type: stringFormat: date

    Data inizio filtro (YYYY-MM-DD, inclusa)

  • endDate
    Type: stringFormat: date

    Data fine filtro (YYYY-MM-DD, inclusa)

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di record. Se omesso insieme a cursor, mantiene il comportamento legacy non paginato.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor per leggere la pagina successiva.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/analytics/recharges
curl 'https://client-api.ai4call.com/api/v1/account/analytics/recharges?startDate=2026-04-01&endDate=2026-04-24&limit=50' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Account analytics recharges retrieved successfully.",
  "requestId": "9755db58-3e8d-4a09-b3a1-c68fd6f70c8d",
  "data": {
    "records": [
      {
        "id": 301,
        "amount": "50.00",
        "status": "completed",
        "currency": "978",
        "orderId": "ORD-20260424-001",
        "createdAt": "2026-04-24T09:00:00.000Z",
        "updatedAt": "2026-04-24T09:00:05.000Z"
      }
    ]
  },
  "meta": {
    "count": 1
  }
}

Storico ricariche

Recupera lo storico consumi RAG del cliente autenticato

​

Restituisce il dettaglio dei consumi di embedding RAG del cliente, aggregati per collezione.

Filtri disponibili:

  • startDate e endDate filtrano per data di creazione del record di consumo (createdAt)
  • entrambi sono opzionali; se omessi, il backend restituisce tutto lo storico disponibile

Come leggere i dati:

  • totalToken — token totali di embedding processati per quella collezione nel periodo
  • totalCost — costo totale di embedding in EUR per quella collezione nel periodo
  • fileCount — numero di file indicizzati nella collezione al momento del record

Query Parameters

  • startDate
    Type: stringFormat: date

    Data inizio filtro (YYYY-MM-DD, inclusa)

  • endDate
    Type: stringFormat: date

    Data fine filtro (YYYY-MM-DD, inclusa)

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di record. Se omesso insieme a cursor, mantiene il comportamento legacy non paginato.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor per leggere la pagina successiva.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/analytics/rag
curl 'https://client-api.ai4call.com/api/v1/account/analytics/rag?startDate=2026-04-01&endDate=2026-04-24&limit=50' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Account analytics RAG retrieved successfully.",
  "requestId": "9755db58-3e8d-4a09-b3a1-c68fd6f70c8e",
  "data": {
    "records": [
      {
        "id": 88,
        "assistantApiKey": "ai4call_sk_abc123",
        "ragId": 12,
        "ragName": "Knowledge Base Prodotti",
        "ragDescription": "Documentazione prodotti aziendali",
        "collectionName": "kb_prodotti_v2",
        "collectionIsActive": true,
        "embeddingProvider": "openai",
        "embeddingModel": "text-embedding-3-small",
        "vectorStoreEngine": "chroma",
        "fileCount": 14,
        "totalToken": 48200,
        "totalCost": "0.0048",
        "collectionCreatedAt": "2026-03-10T08:00:00.000Z",
        "collectionUpdatedAt": "2026-04-20T14:30:00.000Z",
        "createdAt": "2026-04-24T08:00:00.000Z"
      }
    ]
  },
  "meta": {
    "count": 1
  }
}

Storico consumi RAG

Recupera le ricerche RAG tariffate del cliente autenticato

​

Restituisce il dettaglio delle ricerche RAG addebitate al cliente, un record per ricerca.

Diverso da /api/v1/account/analytics/rag, che riguarda il costo di caricamento dei documenti nelle raccolte: questo endpoint riguarda il costo di interrogarle.

Filtri disponibili:

  • startDate e endDate filtrano per data della ricerca (createdAt)
  • entrambi sono opzionali; se omessi, il backend restituisce tutto lo storico disponibile

Come leggere i dati:

  • queryTokens - token della query, la quantità su cui la ricerca viene tariffata
  • pricePerTokenNoVat - prezzo unitario applicato dal listino del cliente
  • totalCost - importo addebitato, IVA inclusa; totalCostNoVat è lo stesso importo al netto
  • resultCount - chunk restituiti, al massimo 10 per ricerca

Se il cliente non ha mai eseguito una ricerca tariffata l'elenco è vuoto.

Query Parameters

  • startDate
    Type: stringFormat: date

    Data inizio filtro (YYYY-MM-DD, inclusa)

  • endDate
    Type: stringFormat: date

    Data fine filtro (YYYY-MM-DD, inclusa)

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di record. Se omesso insieme a cursor, mantiene il comportamento legacy non paginato.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor per leggere la pagina successiva.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/analytics/rag-searches
curl 'https://client-api.ai4call.com/api/v1/account/analytics/rag-searches?startDate=2026-08-01&endDate=2026-08-28&limit=50' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Account analytics RAG searches retrieved successfully.",
  "requestId": "9755db58-3e8d-4a09-b3a1-c68fd6f70c8e",
  "data": {
    "records": [
      {
        "id": "6f1c0a1e-6f0e-4a55-9a35-2f6b6d3c1f77",
        "ragId": 12,
        "ragName": "Knowledge Base Prodotti",
        "collectionName": "kb_prodotti_v2",
        "queryTokens": 128,
        "resultCount": 5,
        "ragCost": 0.0000047,
        "totalCost": 0.0000047,
        "totalCostNoVat": 0.0000038,
        "pricePerTokenNoVat": 3e-8,
        "pricePerTokenWithVat": 3.66e-8,
        "source": "call",
        "createdAt": "2026-08-27T10:12:44.000Z"
      }
    ]
  },
  "meta": {
    "count": 1
  }
}

Storico delle ricerche RAG tariffate

Recupera lo storico SMS del cliente autenticato

​

Restituisce i messaggi SMS inviati dal cliente tramite gli assistenti.

Filtri disponibili:

  • startDate e endDate filtrano per data di invio (createdAt)
  • entrambi sono opzionali; se omessi, il backend restituisce tutto lo storico disponibile

Come leggere i dati:

  • usageSms — numero di SMS scalati dal credito SMS per questo messaggio (dipende dalla lunghezza del testo)
  • alias — nome dell'assistente o etichetta configurata per il canale SMS

Query Parameters

  • startDate
    Type: stringFormat: date

    Data inizio filtro (YYYY-MM-DD, inclusa)

  • endDate
    Type: stringFormat: date

    Data fine filtro (YYYY-MM-DD, inclusa)

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di record. Se omesso insieme a cursor, mantiene il comportamento legacy non paginato.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor per leggere la pagina successiva.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/analytics/sms
curl 'https://client-api.ai4call.com/api/v1/account/analytics/sms?startDate=2026-04-01&endDate=2026-04-24&limit=50' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Account analytics SMS retrieved successfully.",
  "requestId": "9755db58-3e8d-4a09-b3a1-c68fd6f70c8f",
  "data": {
    "records": [
      {
        "assistantApiKey": "ai4call_sk_abc123",
        "alias": "Assistente Demo",
        "destinationNumber": "+393331234567",
        "text": "Grazie per averci contattato. Le invieremo una conferma via email.",
        "usageSms": 1,
        "createdAt": "2026-04-24T10:20:00.000Z"
      }
    ]
  },
  "meta": {
    "count": 1
  }
}

Storico SMS inviati

Recupera lo storico risposte tool del cliente autenticato

​

Restituisce le risposte dei tool invocati dagli assistenti durante le chiamate.

Filtri disponibili:

  • startDate e endDate filtrano per data di creazione (createdAt)
  • entrambi sono opzionali; se omessi, il backend restituisce tutto lo storico disponibile

Come leggere i dati:

  • toolName — nome del tool invocato (corrisponde al name del tool configurato sull'assistente)
  • toolCallId — identificativo univoco dell'invocazione generato dal LLM
  • callUuid — UUID della chiamata telefonica che ha originato l'invocazione
  • toolResponse — payload di risposta restituito dal tool; la struttura varia per ogni tool

Query Parameters

  • startDate
    Type: stringFormat: date

    Data inizio filtro (YYYY-MM-DD, inclusa)

  • endDate
    Type: stringFormat: date

    Data fine filtro (YYYY-MM-DD, inclusa)

  • limit
    Type: integer
    min:  
    1
    max:  
    100

    Numero massimo di record. Se omesso insieme a cursor, mantiene il comportamento legacy non paginato.

  • cursor
    Type: string

    Cursore opaco restituito in meta.nextCursor per leggere la pagina successiva.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for get/api/v1/account/analytics/tool-responses
curl 'https://client-api.ai4call.com/api/v1/account/analytics/tool-responses?startDate=2026-04-01&endDate=2026-04-24&limit=50' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN'

{
  "success": true,
  "message": "Account analytics tool responses retrieved successfully.",
  "requestId": "9755db58-3e8d-4a09-b3a1-c68fd6f70c90",
  "data": {
    "records": [
      {
        "id": 4501,
        "callUuid": "7e4c2a91-1234-5678-abcd-ef0123456789",
        "toolName": "get_calendar_availability",
        "toolCallId": "call_abc123xyz",
        "toolResponse": {
          "available": true,
          "slots": [
            {
              "date": "2026-04-25",
              "time": "10:00"
            },
            {
              "date": "2026-04-25",
              "time": "15:00"
            }
          ]
        },
        "createdAt": "2026-04-24T10:15:30.000Z"
      }
    ]
  },
  "meta": {
    "count": 1
  }
}

Storico risposte tool

Public RAG

​

Ricerca RAG pubblica tramite API key cliente

Public RAG Operations

Cerca chunk in una collezione RAG pubblica

​

Esegue una ricerca vettoriale su una collezione RAG tramite l'ID API pubblico della collezione.

L'endpoint usa il dominio dedicato https://rag.ai4call.com e richiede una API key cliente generata dal portale AI4Call nella sezione Sicurezza -> API Key.

Il campo rag_id e' l'ID API pubblico mostrato nella UI di gestione RAG, non l'ID numerico interno del database. La ricerca restituisce al massimo 4 chunk.

Body·

required
application/json

Richiesta di ricerca Public RAG accettata dal servizio RAG dedicato.

  • query
    Type: string
    required

    Testo da cercare semanticamente nella collezione RAG

  • rag_id
    Type: string
    required

    ID API pubblico della collezione RAG mostrato nella UI del portale

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/public/v1/rag/search
curl https://rag.ai4call.com/public/v1/rag/search \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "rag_id": "rag_8K2mP9zQ4xL7",
  "query": "coca"
}'

{
  "success": true,
  "data": {
    "query": "coca",
    "rag_id": "rag_8K2mP9zQ4xL7",
    "count": 2,
    "results": [
      {
        "content": "1 lattina Coca Cola costa 1,50 EURO",
        "score": 1.4087,
        "metadata": {
          "filename": "Catalogo Prodotti Autorizzati.txt",
          "chunkIndex": "0",
          "totalChunks": "4"
        }
      }
    ]
  }
}

Risultati della ricerca RAG

Outbound

​

Webhook per avviare chiamate outbound con PBX cliente o trunk AI4CALL

Outbound Operations

Chiamata in uscita usando la configurazione telefonica del cliente

​

Avvia una chiamata outbound usando la configurazione telefonica del cliente.

Sono disponibili due modalità:

  • Modalità PBX IP (predefinita): ometti method_uac o impostalo a false, e fornisci ip_pbx e sip_port. ip_pbx deve essere uno degli IP pubblici autorizzati disponibili in GESTIONE -> Abilita IP.
  • Modalità UAC registrato: imposta method_uac a true e ometti ip_pbx e sip_port.

La chiave API nell'header deve essere generata dal portale nella sezione SICUREZZA -> API Key.

Body·

required
application/json

Responses

  • application/json
  • application/json
  • application/json
Request Example for post/webhook/outbound_call_pbx
curl https://outcall.ai4call.com/webhook/outbound_call_pbx \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-APIKEY-SECRET-AI4CALL: YOUR_SECRET_TOKEN' \
  --data '{
  "dst": "331XXXXXXXXX",
  "callerId": "02825XXXXX",
  "assistantApiKey": "ai4call_sk_xxxxxxxx",
  "ipPbx": "xxx.xxx.xxx.xxx",
  "sipPort": "5060",
  "addPrompt": "Saluta sempre l'\''utente per nome, si chiama MARIO ROSSI",
  "callResultUrl": "https://example.com/webhooks/ai4call/outbound-result"
}'

{
  "success": true,
  "message": "Outbound call accepted.",
  "requestId": "9755db58-3e8d-4a09-b3a1-c68fd6f70c8b",
  "data": {
    "internalId": "4f9ab147-ef47-4b54-9987-1dd30288c610",
    "status": "accepted",
    "callbackConfigured": true,
    "callId": "CALL-20260504-001"
  }
}

Richiesta di chiamata accettata

Chiamata in uscita con trunk AI4CALL

​

Avvia una chiamata outbound usando i trunk VoIP AI4CALL. Non richiede configurazione PBX del cliente.

callerId deve essere un numero AI4CALL demo o acquistato presente nell'account. Puoi vedere numeri demo e acquistati in NUMERI AI4CALL -> Routing.

La chiave API nell'header deve essere generata dal portale nella sezione SICUREZZA -> API Key.

Body·

required
application/json

Responses

  • application/json
  • application/json
  • application/json
Request Example for post/webhook/outbound_call
curl https://outcall.ai4call.com/webhook/outbound_call \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-APIKEY-SECRET-AI4CALL: YOUR_SECRET_TOKEN' \
  --data '{
  "dst": "+39331XXXXXXXXX",
  "callerId": "+3902825XXXXX",
  "assistantApiKey": "ai4call_sk_xxxxxxxx",
  "addPrompt": "Saluta sempre l'\''utente per nome, si chiama MARIO ROSSI",
  "callResultUrl": "https://example.com/webhooks/ai4call/outbound-result"
}'

{
  "success": true,
  "message": "Outbound call accepted.",
  "requestId": "9755db58-3e8d-4a09-b3a1-c68fd6f70c8b",
  "data": {
    "internalId": "4f9ab147-ef47-4b54-9987-1dd30288c610",
    "status": "accepted",
    "callbackConfigured": true,
    "callId": "CALL-20260504-001"
  }
}

Richiesta di chiamata accettata

Recupera lo stato persistito di una chiamata outbound

​

Recupera il CDR outbound finale usando l'internal_id ricevuto nel callback dell'esito.

Il callback può arrivare quando duration è 0; i client possono ripetere questa richiesta finché il CDR non è stato persistito. La chiave API deve appartenere al cliente che ha avviato la chiamata outbound.

Path Parameters

  • uuid
    Type: Format: uuid
    required

    Identificativo interno outbound ricevuto nel callback.

    UUID generato da AI4Call per correlare richiesta outbound, callback e ricerca dello stato finale di chiamata.

Responses

  • application/json
  • application/json
  • application/json
Request Example for get/getDialstatus/{uuid}
curl https://outcall.ai4call.com/getDialstatus/4f9ab147-ef47-4b54-9987-1dd30288c610 \
  --header 'X-APIKEY-SECRET-AI4CALL: YOUR_SECRET_TOKEN'

{
  "dialStatus": "ANSWER",
  "billSec": 42,
  "trafficCost": "0.003300"
}

Stato persistito della chiamata outbound

Models

​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​
​