v1.2.0
OpenAPI 3.0.3

API client AI4Call

AI4Call technical support
Proprietary
Conditions d’utilisation

Contrat OpenAPI public pour les API AI4Call côté client.

Le service principal sur https://client-api.ai4call.com couvre la gestion authentifiée du compte, les assistants et leur configuration d'exécution, le portefeuille de fournisseurs, les ressources de catalogue, les connaissances, la gestion des documents RAG, les outils et les analyses du compte.

Flux d'authentification actuel de la Client API :

  1. POST /api/v1/auth/portal/login valide email et portalApiKey. Il n'émet pas de jeton d'accès et ne crée pas de session côté serveur.
  2. Les appels métier acceptent Authorization: Bearer <portalApiKey> ou la paire historique x-client-email et x-portal-api-key.
  3. Les opérations sur un assistant utilisent assistantId ; les valeurs de chemin historiques assistantApiKey restent acceptées pendant la période de compatibilité v1.

Ce document contient aussi des opérations hébergées par des services dédiés. Les opérations Public RAG utilisent leur propre authentification Bearer et les opérations outbound leur propre en-tête de clé API ; chaque opération déclare son serveur et son schéma de sécurité dédiés.

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

Production de clients API

Aucune authentification sélectionnée
Bibliothèques clientes
Shell Curl

Health

​

Vérifier la disponibilité du service API

Health Opérations

Bilan de santé du service

​

Bilan de santé du service

Réponses

  • 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"
  }
}

Service actif

Auth

​

Authentification client du portail par e-mail et portalApiKey

Auth Opérations

Authentifier un client du portail avec e-mail et portalApiKey

​

Valide les identifiants statiques du portail et renvoie les données du client. Aucun jeton ni session côté serveur n'est créé.

Corps·

obligatoire
application/json

Identifiants utilisés pour vérifier un client du portail. Cette requête ne crée pas de session et n'émet pas de jeton d'accès.

  • email
    Type: stringFormat: email
    obligatoire

    E-mail du client du portail.

  • portalApiKey
    Type: string
    longueur min.:  
    10
    obligatoire

    Clé API statique du portail associée au compte client.

Réponses

  • 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
    }
  }
}

Client authentifié

Account

​

Gestion des comptes clients authentifiés

Account Opérations

Récupérer les IP autorisées du compte authentifié

​

Récupérer les IP autorisées du compte authentifié

Réponses

  • 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": "Bureau principal"
        },
        {
          "ip": "192.168.1.20",
          "description": null
        }
      ]
    }
  },
  "meta": {
    "count": 2
  }
}

Liste blanche IP du compte

Mettre à jour les adresses IP autorisées du compte authentifié

​

Met à jour la liste blanche d'adresses IP du compte avec la sémantique PATCH merge.

Paramètres modifiables :

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

Comment récupérer les données actuelles :

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

Règles de fonctionnement :

  • allowedIps remplace toute la liste
  • addIps ajoute de nouvelles IP ou met à jour la description des IP déjà présentes
  • deleteIps supprime les IP indiquées
  • ne combinez pas allowedIps avec addIps ou deleteIps
  • allowedIps: [] efface complètement la liste
  • après la mise à jour de la base de données, le backend synchronise également immédiatement le pare-feu

Corps·

obligatoire
application/json

PATCH fusionne la configuration IP autorisée du compte.

Règles de fonctionnement :

  • allowedIps remplace complètement la liste actuelle
  • addIps ajoute de nouvelles IP ou met à jour le description d'une IP déjà existante
  • deleteIps supprime les IP indiquées
  • allowedIps ne peut pas être combiné avec addIps ou deleteIps
  • allowedIps: [] supprime toutes les adresses IP
  • description: null ou une chaîne vide supprime la description IP
  • addIps
    Type:

    Valeur à envoyer pour addIps dans la requête AccountAllowedIpsUpdateRequest.

    Propriétés : 2
  • allowedIps
    Type:

    Valeur à envoyer pour allowedIps dans la requête AccountAllowedIpsUpdateRequest.

    Propriétés : 2
  • deleteIps
    Type: array of stringFormat: ipv4

    Valeur à envoyer pour deleteIps dans la requête AccountAllowedIpsUpdateRequest.

Réponses

  • 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": "Bureau principal"
    },
    {
      "ip": "192.168.1.20",
      "description": "Maison"
    }
  ]
}'

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

Liste blanche IP mise à jour

Récupère les limites d'appels du compte authentifié

​

Renvoie les limites d’appels simultanés au niveau du compte pour tous les assistants clients.

Comment utiliser la réponse :

  • utilisez assistants[].assistantApiKey dans PATCH
  • configuredLimit et la valeur économisée côté locataire
  • maxConcurrentCalls et la valeur réelle affichée sur le portail
  • si configuredLimit et null, le backend utilise defaultLimit

Réponses

  • 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": "Assistance client",
          "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"
}

Limites d'appels du compte

Mettre à jour les limites d'appels du compte authentifié

​

Mettez à jour les limites d’appels simultanés au niveau du compte avec la sémantique PATCH merge.

Paramètres modifiables :

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

Comment récupérer des données :

  • utilisez GET /api/v1/account/call-limits
  • réutiliser assistants[].assistantApiKey

Règles de fonctionnement :

  • chaque élément modifie uniquement l'assistant indiqué
  • maxConcurrentCalls: null supprime la limite configurée et l'assistant revient à defaultLimit
  • si un assistant n'est pas présent dans le payload, sa limite ne change pas

Corps·

obligatoire
application/json

PATCH fusionne les limites d'appels simultanés du compte.

Règles de fonctionnement :

  • assistants est obligatoire
  • chaque élément met à jour uniquement l'assistant indiqué
  • maxConcurrentCalls: null supprime la limite configurée pour ce assistant
  • si un assistant n'est pas envoyé, sa limite actuelle ne change pas
  • maxConcurrentCalls doit être un entier supérieur ou égal à 0
  • assistants
    Type:
    obligatoire

    Valeur à envoyer pour assistants dans la requête AccountCallLimitsUpdateRequest.

    Propriétés : 2

Réponses

  • 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
  }
}

Limites d'appels mises à jour

Récupérer les numéros de routage du compte authentifié

​

Renvoie les numéros de routage au niveau du compte du portail :

  • assistants
  • demoNumbers
  • purchasedNumbers
  • userNumbers

Comment utiliser la réponse :

  • utiliser assistants[].assistantApiKey dans les charges utiles PATCH
  • utilisez phoneNumber des listes respectives dans les charges utiles PATCH
  • assistantApiKey et assistantName à l'intérieur de chaque numéro indiquent le assistant actuellement connecté

Réponses

  • 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"
}

Numéros de compte de routage

Mettre à jour les numéros de routage du compte authentifié

​

Mettez à jour le routage des numéros au niveau du compte avec la sémantique PATCH merge.

Paramètres modifiables :

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

Comment récupérer des données :

  • utilisez GET /api/v1/account/number-routing
  • réutiliser assistants[].assistantApiKey
  • réutiliser demoNumbers[].phoneNumber, purchasedNumbers[].phoneNumber, userNumbers[].phoneNumber

Règles de fonctionnement :

  • chaque élément modifie uniquement le numéro indiqué
  • assistantApiKey: null libère le numéro
  • si le numéro était déjà associé à un autre assistant, il est déplacé vers le nouveau
  • pour les numéros de démo, en attribuant à un assistant un numéro de démo, toute autre démo déjà connectée à cet assistant est libérée
  • les champs omis ne sont pas modifiés

Corps·

obligatoire
application/json

PATCH de fusion du routage des numéros de compte.

Règles de fonctionnement :

  • au moins un des demoNumbers, purchasedNumbers, userNumbers doit être présent
  • chaque élément met à jour uniquement le numéro indiqué
  • assistantApiKey: null libère le numéro
  • assistantApiKey: "..." connecter ou déplacer le numéro vers cet assistant
  • si un numéro était connecté à un autre assistant, il est supprimé et reconnecté au nouveau
  • pour les numéros de démo, si l'assistant cible possédait déjà un autre numéro de démo, l'ancien est libéré
  • les champs omis ne sont pas modifiés
  • demoNumbers
    Type:

    Valeur à envoyer pour demoNumbers dans la requête AccountNumberRoutingUpdateRequest.

    Propriétés : 2
  • purchasedNumbers
    Type:

    Valeur à envoyer pour purchasedNumbers dans la requête AccountNumberRoutingUpdateRequest.

    Propriétés : 2
  • userNumbers
    Type:

    Valeur à envoyer pour userNumbers dans la requête AccountNumberRoutingUpdateRequest.

    Propriétés : 2

Réponses

  • 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
  }
}

Routage des numéros mis à jour

Récupère tous les plugins achetables du compte authentifié

​

Renvoie les plugins pouvant être achetés pour le client authentifié selon sa grille de prix.

Comment utiliser les données :

  • réutiliser directement pluginName dans le PATCH PATCH /api/v1/account/plugins/purchase
  • aucun identifiant de plugin n'est nécessaire

Réponses

  • 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": "Intégration avec Google Sheets",
          "category": "data_integrations",
          "pluginType": "paid",
          "purchasePrice": 9.9,
          "monthlyPrice": 4.9,
          "priceListName": "Standard",
          "activeInstanceCount": 1
        }
      ]
    }
  },
  "meta": {
    "count": 1
  }
}

Liste des plugins achetables

Récupère toutes les instances de plugin actives achetées par le compte authentifié

​

Renvoie les instances de plugin actives du client authentifié.

Utilisation canonique :

  • utilisez l'instanceId stable avec PATCH /api/v1/account/plugins/instances/{instanceId}
  • utilisez le même instanceId avec DELETE /api/v1/account/plugins/instances/{instanceId}

Le PATCH historique basé sur les noms reste disponible pour compatibilité.

Paramètres de requête

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximal d'éléments renvoyés dans une page paginée par curseur. Omettez limit et cursor pour conserver la réponse historique non paginée.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor par la page précédente.

Réponses

  • 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": "Intégration avec 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
  }
}

Liste des instances de plugin actives achetées

Créer une instance de plugin achetée

​

Achète un plugin et crée une nouvelle instance de plugin du compte. La réponse expose l'instanceId stable utilisé par les routes canoniques de l'instance.

Corps·

obligatoire
application/json

Achetez un plugin en utilisant le nom du plugin renvoyé par GET /api/v1/account/plugins/available.

Règles de fonctionnement :

  • pluginName doit correspondre à la valeur renvoyée par le catalogue
  • instanceName et en option
  • si instanceName n'est pas présent, le backend génère automatiquement Istanza N
  • Les anciens alias Snake_case restent acceptés mais sont obsolètes

Réponses

  • 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"
    }
  }
}

Instance de plugin créée avec succès

Renommer une instance de plugin achetée

​

Renomme une instance de plugin active à l'aide de son instanceId stable.

Paramètres de chemin

  • instanceId
    Type: string
    obligatoire

    Identifiant stable de l'abonnement de plugin renvoyé par la liste des instances ou l'opération de création.

Corps·

obligatoire
application/json

Renomme une instance de plugin achetée identifiée par son instanceId stable.

Réponses

  • 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"
    }
  }
}

Instance de plugin mise à jour

Annuler une instance de plugin achetée

​

Annule une instance de plugin active à l'aide de son instanceId stable.

Paramètres de chemin

  • instanceId
    Type: string
    obligatoire

    Identifiant stable de l'abonnement de plugin renvoyé par la liste des instances ou l'opération de création.

Réponses

  • 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"
    }
  }
}

Instance de plugin annulée

Récupérer la configuration d'une instance de plugin acquise

​

Récupère la configuration d'une instance de plugin acquise. Utilisez l'instanceId stable renvoyé par GET /api/v1/account/plugins/instances. La route historique basée sur le nom reste prise en charge.

Paramètres de chemin

  • instanceId
    Type: string
    obligatoire

    Identifiant stable de l'instance de plugin acquise.

Réponses

  • 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
    }
  }
}

Configuration du plugin

Mettre à jour la configuration d'une instance de plugin acquise

​

Met à jour la configuration avec l'instanceId stable. Les noms du plugin et de l'instance sont résolus côté serveur ; les clients envoient donc uniquement les champs de configuration à fusionner.

Paramètres de chemin

  • instanceId
    Type: string
    obligatoire

    Identifiant stable de l'instance de plugin acquise.

Corps·

obligatoire
application/json

Corps PATCH de configuration adressé par un instanceId de plugin stable.

  • configuration
    Type: object
    obligatoire

    Champs spécifiques au plugin à fusionner dans la configuration enregistrée.

    Propriétés : 1

Réponses

  • 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
    }
  }
}

Configuration du plugin mise à jour

Assistants

​

Gestion des assistants clients authentifiés

Assistants Opérations

Répertorie les assistants du client authentifié

​

Répertorie les assistants du client authentifié

Paramètres de requête

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximal d'éléments renvoyés dans une page paginée par curseur. Omettez limit et cursor pour conserver la réponse historique non paginée.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor par la page précédente.

Réponses

  • 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"
      }
    ]
  }
}

Liste des assistants

Créer un nouvel assistant pré-initialisé pour le client authentifié

​

Crée l'assistant en reproduisant la même logique que le portail AI4Call.

Pour un assistant classique, seuls name et description sont requis. Pour un assistant audio-à-audio, envoyez mode: audio_to_audio et, si vous souhaitez remplacer les valeurs par défaut, le bloc canonique audioToAudio. Le mode historique voice_to_voice et le champ voiceToVoice restent acceptés pour compatibilité.

Le backend effectue automatiquement :

  • génération de assistantApiKey au format ai4call_sk_*
  • allocation progressive de jsonFilename au format FLLM*.json
  • génération du virtualNumber de démonstration au format 0000********
  • initialisation du JSON d'exécution avec les valeurs par défaut du portail
  • déclenchement du provisioning backend
  • tentative best-effort d'enregistrer l'assistant sur le tenant MCP

Valeurs initiales :

  • TTS tts_live_azure_multi avec la voix it-IT-ElsaNeural
  • ASR asr_azure_multi
  • LLM openai avec le modèle gpt-4o
  • premier message non configuré (firstMessage.text vide)
  • prompt initial préconfiguré
  • état initial draft

Si mode vaut audio_to_audio, le backend initialise un JSON configType: voice-llm avec une racine audio-à-audio compatible avec le portail.

Corps·

obligatoire
application/json

Charge utile de création minimale. Le backend réplique la logique du portail : génère assistantApiKey, virtualNumber et jsonFilename, initialise le runtime JSON avec les valeurs par défaut d'AI4Call et commence à provisionner l'assistant. Le nom de l'assistant est normalisé en remplaçant les espaces par _.

  • description
    Type: string
    longueur min.:  
    1
    longueur max.:  
    500
    obligatoire

    Description fonctionnelle de l'assistant.

  • name
    Type: string
    longueur min.:  
    3
    longueur max.:  
    100
    obligatoire

    Nom de l'assistant. S'il contient des espaces, le backend les convertit automatiquement en _.

  • audioToAudio
    Type:
    obsolète

    Configuration audio-à-audio initiale, utilisée lorsqu'elle s'applique au mode sélectionné.

    Propriétés : 6
  • mode
    Type: enum

    Mode d'exécution à utiliser lors de la création de l'assistant.

    valeurs
    textaudio_to_audiovoice_to_voice
  • voiceToVoice
    Type:
    obsolète

    Alias historique de audioToAudio.

    Propriétés : 6

Réponses

  • 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": "Assistant de démonstration pour les campagnes commerciales entrantes.",
  "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"
    }
  }
}

Assistant créé

Récupère un assistant spécifique au client authentifié

​

Récupère un assistant spécifique au client authentifié

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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"
    }
  }
}

Assistant trouvé

Mettre à jour les métadonnées, l'état et la configuration de base de l'assistant

​

Met à jour les champs généraux de l'assistant.

Pour les assistants text, le bloc firstMessage met à jour le premier message statique avec une sémantique PATCH merge. Envoyez firstMessage.text: null ou firstMessage.text: "" pour le supprimer.

Pour les assistants audio-à-audio, le bloc canonique audioToAudio met à jour le JSON voice-llm avec une sémantique PATCH merge. Le champ historique voiceToVoice reste accepté pour compatibilité.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

Charge utile PATCH utilisée pour mettre à jour les champs modifiables de l'assistant.

  • audioToAudio
    Type:
    obsolète

    Mise à jour partielle de la configuration audio-à-audio.

    Propriétés : 6
  • description
    Type: string | null
    longueur max.:  
    500

    Nouvelle description fonctionnelle ; null supprime la description actuelle.

  • firstMessage
    Type:

    Mise à jour partielle de la configuration du premier message de l'assistant.

    Propriétés : 3
  • metadata
    Type: object

    Métadonnées libres à stocker avec l'assistant.

    Propriétés : 1
  • name
    Type: string
    longueur min.:  
    3
    longueur max.:  
    100

    S'il contient des espaces, le backend les convertit automatiquement en _.

  • network
    Type: object

    Paramètres réseau à mettre à jour sur l'assistant.

    Propriétés : 1
  • numbers
    Type: object

    Valeurs de remplacement pour les listes de numéros de l'assistant lorsqu'elles sont fournies.

    Propriétés : 2
  • settings
    Type: object

    Paramètres principaux de l'assistant à mettre à jour.

    Propriétés : 5
  • status
    Type: "draft" or "active" or "disabled"enum

    Nouvel état du cycle de vie de l'assistant.

  • voiceToVoice
    Type:
    obsolète

    Alias historique de audioToAudio.

    Propriétés : 6

Réponses

  • 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"
    }
  }
}

Assistant mis à jour

Supprimer un assistant

​

Supprime l'assistant, libère ses numéros de téléphone attribués, supprime son JSON d'exécution et actualise la table de routage. La suppression est refusée lorsqu'un autre assistant du même compte utilise cet assistant comme cible de transfert.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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
  }
}

Assistant supprimé

Met a jour les numeros routes vers l'assistant

​

Met a jour le routage des numeros du client vers cet assistant, avec une semantique PATCH merge entre les trois listes.

Parametres modifiables :

  • demoNumbers
  • purchasedNumbers
  • userNumbers

Comment recuperer les donnees actuelles :

  • utiliser GET /api/v1/catalog/assistants/{assistantApiKey}/number-routing pour les numeros deja attribues et ceux encore disponibles sur le compte

Regles operationnelles :

  • au moins une des trois listes doit etre presente
  • une liste omise conserve la valeur actuelle
  • une liste presente remplace entierement la precedente : envoyer [] pour liberer tous les numeros de ce type
  • attribuer un numero deja route vers un autre assistant le deplace vers celui-ci

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

PATCH merge des numeros routes vers l'assistant.

Regles operationnelles :

  • au moins un parmi demoNumbers, purchasedNumbers et userNumbers doit etre present
  • les listes omises conservent la valeur actuelle
  • chaque liste remplace entierement la precedente : pour supprimer tous les numeros d'un type, envoyer []
  • seuls les numeros deja disponibles sur le compte du client peuvent etre attribues
  • un numero attribue a un autre assistant est deplace vers celui-ci
  • demoNumbers
    Type: array of string

    Numeros demo a router vers cet assistant

  • purchasedNumbers
    Type: array of string

    Numeros achetes a router vers cet assistant

  • userNumbers
    Type: array of string

    Numeros propres du client (PBX propre) a router vers cet assistant

Réponses

  • 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"
      ]
    }
  }
}

Routage mis a jour

Liste les numeros du client avec leur etat de routage

​

Renvoie tous les numeros du client, repartis en demo, achetes et propres, chacun avec l'assistant vers lequel il est actuellement route.

A utiliser avant PATCH /api/v1/assistants/{assistantApiKey}/runtime/number-routing pour savoir quels numeros sont libres et lesquels sont deja attribues ailleurs.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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
  }
}

Numeros avec leur etat de routage

Assistant Prompt

​

Invite de l'assistant modifiable, premier message et options associées

Assistant Prompt Opérations

Récupérer l'invite modifiable et la configuration du premier message de l'assistant

​

Renvoie la configuration rapide de l'assistant dans le même modèle conceptuel utilisé par le portail.

Ce qui revient

  • prompt.text : uniquement la partie modifiable de l'invite
  • firstMessage.text : le premier message statique, si présent
  • firstMessage.callerSpeaksFirst : option qui indique si l'appelant parle en premier
  • firstMessage.uninterruptible : option qui indique si le premier message ne peut pas être interrompu

Remarque importante

Les sections automatiques déjà présentes dans le JSON, telles que les blocs système ou les connaissances, ne sont pas renvoyées dans prompt.text. Sur les serveurs voice_to_voice, prompt.text correspond au champ racine prompt du JSON voice-llm ; le premier message n'est pas utilisé.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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
      }
    }
  }
}

Configuration rapide récupérée

Mettre à jour l'invite modifiable et la configuration du premier message de l'assistant

​

Mettez à jour la configuration de l’invite de l’assistant avec la sémantique PATCH merge.

Paramètres modifiables :

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

Si vous mettez à jour l'invite

  • Envoyer prompt.text
  • Le backend met à jour uniquement la partie modifiable
  • Toutes les sections automatiques déjà présentes dans le JSON, comme le système et les connaissances, restent préservées

Si vous mettez à jour le premier message

  • Envoyez firstMessage.text pour le régler ou le remplacer
  • Envoyez firstMessage.text: null ou "" pour le supprimer
  • Envoyez firstMessage.callerSpeaksFirst: true si vous souhaitez que l'appelant parle en premier
  • Si callerSpeaksFirst=true, le backend supprime le premier message statique et force uninterruptible=false

Remarque sur la fusion

  • Les champs omis conservent leur valeur actuelle
  • Vous pouvez mettre à jour uniquement l'invite, uniquement le premier message ou les deux au cours du même appel.
  • sur les assistants voice_to_voice, seul prompt.text est mis à jour dans la racine JSON voice-llm ; Les champs firstMessage sont ignorés par le runtime audio-audio

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

Charge utile de mise à jour de l’invite et du premier message.

Utilisez l'un des exemples ci-dessous en fonction de ce que vous souhaitez modifier :

  • invite uniquement
  • premier message uniquement
  • passer à callerSpeaksFirst

PATCH fusionne la configuration de l'invite de l'assistant.

Règles de fonctionnement :

  • les champs omis conservent leur valeur actuelle
  • prompt.text met à jour uniquement la partie modifiable de l'invite
  • toutes les sections automatiques déjà présentes dans le JSON, comme le système et les connaissances, sont conservées
  • pour supprimer le premier message statique, envoyez firstMessage.text: null ou firstMessage.text: ""
  • si après la fusion firstMessage.callerSpeaksFirst=true, le backend :
    • supprimer le premier message statique
    • allez firstMessage.uninterruptible=false
  • firstMessage
    Type: object

    Valeur à envoyer pour firstMessage dans la requête AssistantPromptUpdateRequest.

    Propriétés : 3
  • prompt
    Type: object

    Valeur à envoyer pour prompt dans la requête AssistantPromptUpdateRequest.

    Propriétés : 1

Réponses

  • 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
      }
    }
  }
}

Configuration d'invite mise à jour

Provider Wallet

​

Identifiants fournisseur du client, reutilisables entre assistants sans envoyer de cles en clair

Provider Wallet Opérations

Liste les fournisseurs qui acceptent vos propres identifiants

​

Renvoie le catalogue des fournisseurs pris en charge par le portefeuille, chacun avec les champs exacts requis pour enregistrer un identifiant.

A lire avant POST /api/v1/account/provider-wallet : serviceType, provider et engine du payload de creation doivent correspondre a l'une de ces entrees, et config n'accepte que les cles listees dans ses fields.

ai4call: true signale un fournisseur egalement utilisable via la grille tarifaire AI4CALL, sans identifiants propres ; byok: true signale qu'il accepte vos identifiants.

Le catalogue est statique et ne depend pas du client authentifie.

Réponses

  • 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": "Modeles phares de la famille GPT et de la serie o",
        "ai4call": true,
        "byok": true,
        "fields": [
          {
            "key": "apiKey",
            "label": "API key",
            "type": "password",
            "required": true,
            "secret": true
          }
        ]
      }
    ]
  },
  "meta": {
    "count": 29
  }
}

Catalogue des fournisseurs pris en charge

Liste les identifiants enregistres dans le portefeuille

​

Renvoie les identifiants du client, tries par service et par fournisseur.

La configuration ne revient jamais en clair : preview contient les valeurs non secretes ainsi que les secrets tronques a leurs premiers caracteres, juste assez pour distinguer deux identifiants.

L'id de chaque identifiant est la valeur a envoyer comme providerWalletId sur les endpoints runtime de l'assistant, au lieu de mettre une cle API dans le payload.

Paramètres de requête

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximal d'éléments renvoyés dans une page paginée par curseur. Omettez limit et cursor pour conserver la réponse historique non paginée.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor par la page précédente.

Réponses

  • 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
  }
}

Identifiants enregistres

Enregistre un nouvel identifiant dans le portefeuille

​

Enregistre un identifiant fournisseur. La valeur est chiffree au repos et ne revient jamais en clair.

Comment construire le payload :

  • lire GET /api/v1/account/provider-wallet/catalog
  • copier serviceType, provider et engine depuis l'entree choisie
  • remplir config avec les cles listees dans les fields de cette entree

Regles operationnelles :

  • config n'accepte que les cles declarees : toute autre cle renvoie 400
  • chaque champ marque required doit etre present et non vide
  • les champs avec options n'acceptent que les valeurs listees
  • name est du texte libre, il sert a reconnaitre l'identifiant ensuite

L'id dans la reponse est la valeur a utiliser comme providerWalletId sur les runtimes de l'assistant.

Corps·

obligatoire
application/json

Creation d'un identifiant dans le portefeuille.

Regles operationnelles :

  • serviceType, provider et engine doivent correspondre a une entree renvoyee par GET /api/v1/account/provider-wallet/catalog
  • config n'accepte que les cles declarees dans les fields de cette entree ; toute autre cle est rejetee
  • chaque champ marque required doit etre present et non vide
  • config
    Type: object
    obligatoire

    Valeurs des champs declares par l'entree du catalogue

    Propriétés : 1
  • engine
    Type: string
    obligatoire

    Code moteur sélectionné dans le catalogue du portefeuille de fournisseurs.

  • name
    Type: string
    longueur max.:  
    120
    obligatoire

    Nom défini par le client pour l'identifiant enregistré.

  • provider
    Type: string
    obligatoire

    Code fournisseur sélectionné dans le catalogue du portefeuille de fournisseurs.

  • serviceType
    Type: enum
    obligatoire

    Catégorie de service sélectionnée dans le catalogue du portefeuille de fournisseurs.

    valeurs
    llmttsasrvoice_llm

Réponses

  • 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"
    }
  }
}

Identifiant enregistre

Liste les identifiants du portefeuille associes a un assistant

​

Renvoie quel identifiant utilise chaque runtime de l'assistant, une entree par scopeKey (par exemple le llm, le tts, l'asr).

Les endpoints runtime ne rapportent que hasProviderWallet, un booleen : c'est ici que l'on decouvre quel identifiant est applique.

Les associations ne s'ecrivent pas ici : elles se creent en envoyant providerWalletId sur l'endpoint runtime correspondant, et se suppriment en envoyant providerWalletId: null.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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
  }
}

Associations de l'assistant

Recupere un identifiant du portefeuille

​

Renvoie un seul identifiant. Comme dans la liste, la configuration revient uniquement sous forme de preview, avec les secrets masques.

Paramètres de chemin

  • providerWalletId
    Type: integer
    min.:  
    1
    obligatoire

    Id de l'identifiant, renvoye a la creation ou par l'endpoint de liste

Réponses

  • 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"
    }
  }
}

Identifiant trouve

Met a jour un identifiant du portefeuille

​

Met a jour un identifiant avec une semantique PATCH merge.

Parametres modifiables :

  • name
  • isActive
  • config

Regles operationnelles :

  • au moins un des trois doit etre present
  • serviceType, provider et engine ne changent pas : pour changer de fournisseur, creer un nouvel identifiant
  • dans config, un champ omis ou vide conserve la valeur deja enregistree. C'est ce qui permet de renommer un identifiant sans renvoyer une cle API que le client ne peut jamais relire
  • desactiver avec isActive: false conserve l'identifiant mais cesse de l'appliquer aux runtimes

Paramètres de chemin

  • providerWalletId
    Type: integer
    min.:  
    1
    obligatoire

    Id de l'identifiant, renvoye a la creation ou par l'endpoint de liste

Corps·

obligatoire
application/json

PATCH merge d'un identifiant.

Regles operationnelles :

  • au moins un parmi name, isActive et config doit etre present
  • serviceType, provider et engine ne changent pas : pour changer de fournisseur, creer un nouvel identifiant
  • dans config, un champ omis ou vide conserve la valeur deja enregistree - utile pour les secrets, que le client ne peut jamais relire
  • config
    Type: object

    Champs d'identification à fusionner dans la configuration enregistrée.

    Propriétés : 1
  • isActive
    Type: boolean

    Indique si l'identifiant enregistré peut être utilisé par les exécutions d'assistant.

  • name
    Type: string
    longueur max.:  
    120

    Nouveau nom d'identifiant défini par le client.

Réponses

  • 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"
    }
  }
}

Identifiant mis a jour

Supprime un identifiant du portefeuille

​

Supprime definitivement l'identifiant et toutes ses associations avec les assistants du client.

Les assistants concernes reviennent aux valeurs ecrites directement dans leur propre configuration ; ils ne sont pas arretes. Pour savoir lesquels, verifier d'abord les associations avec GET /api/v1/account/provider-wallet/assistants/{assistantApiKey}.

Paramètres de chemin

  • providerWalletId
    Type: integer
    min.:  
    1
    obligatoire

    Id de l'identifiant, renvoye a la creation ou par l'endpoint de liste

Réponses

  • 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
  }
}

Identifiant supprime

Catalog TTS

​

Mise à jour du runtime du fournisseur TTS, des voix et de l'assistant TTS

Catalog TTS Opérations

Mettre à jour la configuration d'exécution TTS de l'assistant

​

Mettez à jour la configuration d'exécution TTS de l'assistant avec la sémantique PATCH merge.

Paramètres modifiables :

  • sourceMode
  • engineCode
  • voiceCode
  • API key
  • region

Si vous utilisez ai4call

  • Envoyer sourceMode: ai4call
  • Envoyer voiceCode
  • engineCode et facultatif
  • N'envoyez pas API key
  • N'envoyez pas region

Si vous utilisez customer

  • Envoyer sourceMode: customer
  • Envoyer engineCode
  • Envoyer voiceCode
  • Envoyer API key
  • Si vous utilisez Azure, envoyez également region

Remarque sur la fusion

  • Les champs omis conservent la valeur actuelle, s'ils sont déjà présents
  • La réponse renvoie la configuration finale résultante

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

Choisissez l'un des exemples ci-dessous en fonction du mode que vous souhaitez définir.

  • ai4call : sélection d'un article du catalogue AI4Call
  • customer : configuration directe avec paramètres client fournisseur

Fusion PATCH de la configuration TTS du assistant.

Règles de fonctionnement :

  • sourceMode et toujours obligatoire
  • les champs omis conservent la valeur actuelle déjà enregistrée, si présente
  • dans ai4call le backend résout la configuration à partir de voiceCode
  • dans customer la configuration utilise des paramètres client directs

Contraintes d'application :

  • customer : engineCode, voiceCode et API key doivent être complétés après la fusion
  • customer avec Azure : region doit être complété après la fusion
  • ai4call : utilisez voiceCode ; engineCode est facultatif et sert uniquement de contrôle de cohérence
  • sourceMode
    Type: "ai4call" or "customer"enum
    obligatoire

    Mode de sourcing d’exécution.

    • ai4call : utilise un fournisseur/modèle présent dans les tarifs AI4Call du client
    • customer : utiliser les informations d'identification et la configuration directes du client
  • apiKey
    Type: string | null
    écriture seule

    Clé API du fournisseur TTS du client. Il ne doit être envoyé qu’en customer. Dans ai4call, il doit être omis.

  • engineCode
    Type: string | null

    Code du moteur/fournisseur TTS. Dans customer identifie le moteur à utiliser. Dans ai4call, il est facultatif et, s'il est envoyé, il est uniquement utilisé pour vérifier que le voiceCode appartient à ce moteur.

  • providerWalletId
    Type: integer | null

    Id d'un identifiant enregistre dans le portefeuille de fournisseurs du client, a utiliser a la place de l'envoi de apiKey en clair.

    Quand il est present, les identifiants sont lus depuis le portefeuille, appliques au runtime et l'association est enregistree sur l'assistant. null supprime l'association et revient aux valeurs envoyees explicitement.

    Les identifiants du portefeuille se creent et se gerent depuis le portail AI4CALL.

  • region
    Type: string | null

    Zone région/fournisseur demandée par certains clients moteurs, notamment Azure. Requis pour Azure dans customer. Dans ai4call, il doit être omis.

  • voiceCode
    Type: string | null

    Code vocal TTS. Dans ai4call se trouve le paramètre principal pour sélectionner l'entrée dans le catalogue AI4Call. Dans customer, il doit identifier l'entrée valide pour le fournisseur/moteur choisi.

Réponses

  • 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"
    }
  }
}

Configuration d'exécution TTS mise à jour

Répertorie les fournisseurs TTS disponibles pour le client

​

Répertorie les fournisseurs TTS disponibles pour le client

Réponses

  • 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
      }
    ]
  }
}

Liste des fournisseurs TTS

Répertorie les entrées TTS résolues par la configuration du runtime de l'assistant

​

Répertorie les entrées TTS résolues par la configuration du runtime de l'assistant

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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
      }
    ]
  }
}

Liste vocale de l'assistant TTS

Catalog ASR

​

Mise à jour du fournisseur ASR, des modèles et de l'assistant d'exécution ASR

Catalog ASR Opérations

Mettre à jour la configuration d'exécution ASR de l'assistant

​

Mettez à jour la configuration d'exécution ASR de l'assistant avec la sémantique PATCH merge.

Paramètres modifiables :

  • sourceMode
  • engineCode
  • API key

Si vous utilisez ai4call

  • Envoyer sourceMode: ai4call
  • Envoyer engineCode
  • N'envoyez pas API key

Si vous utilisez customer

  • Envoyer sourceMode: customer
  • Envoyer engineCode
  • Envoyer API key

Remarque sur la fusion

  • Les champs omis conservent la valeur actuelle, s'ils sont déjà présents
  • La réponse renvoie la configuration finale résultante

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

Choisissez l'un des exemples ci-dessous en fonction du mode que vous souhaitez définir.

  • ai4call : sélection d'un moteur ASR dans le catalogue AI4Call
  • customer : configuration directe avec le moteur et la clé API du client

PATCH fusionne la configuration ASR du assistant.

Règles de fonctionnement :

  • sourceMode et toujours obligatoire
  • les champs omis conservent la valeur actuelle déjà enregistrée, si présente
  • dans ai4call, le backend sélectionne un moteur disponible dans les listes de prix AI4Call du client
  • dans customer la configuration utilise des paramètres client directs

Contraintes d'application :

  • customer : engineCode et API key doivent être complétés après la fusion
  • ai4call : engineCode doit identifier un moteur disponible dans le catalogue AI4Call du client
  • sourceMode
    Type: "ai4call" or "customer"enum
    obligatoire

    Mode de sourcing d’exécution.

    • ai4call : utilise un moteur ASR présent dans les tarifs AI4Call du client
    • customer : utiliser les informations d'identification et la configuration directes du client
  • apiKey
    Type: string | null
    écriture seule

    Clé API du fournisseur ASR du client. Il ne doit être envoyé qu’en customer. Dans ai4call, il doit être omis.

  • engineCode
    Type: string | null

    Code du moteur/fournisseur ASR. Dans ai4call identifie le moteur AI4Call à associer. Dans customer identifie le moteur du fournisseur du client.

  • providerWalletId
    Type: integer | null

    Id d'un identifiant enregistre dans le portefeuille de fournisseurs du client, a utiliser a la place de l'envoi de apiKey en clair.

    Quand il est present, les identifiants sont lus depuis le portefeuille, appliques au runtime et l'association est enregistree sur l'assistant. null supprime l'association et revient aux valeurs envoyees explicitement.

    Les identifiants du portefeuille se creent et se gerent depuis le portail AI4CALL.

Réponses

  • 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"
    }
  }
}

Configuration d'exécution ASR mise à jour

Répertorie les fournisseurs ASR disponibles pour le client

​

Répertorie les fournisseurs ASR disponibles pour le client

Réponses

  • 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"
        ]
      }
    ]
  }
}

Liste des fournisseurs ASR

Répertorie les modèles ASR résolus par la configuration du runtime de l'assistant

​

Répertorie les modèles ASR résolus par la configuration du runtime de l'assistant

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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"
      }
    ]
  }
}

Liste des modèles assistants ASR

Catalog LLM

​

Mise à jour du fournisseur LLM, des modèles et de l'assistant LLM Runtime

Catalog LLM Opérations

Mettre à jour la configuration d'exécution LLM de l'assistant

​

Mettez à jour la configuration d'exécution LLM de l'assistant avec la sémantique PATCH merge.

Paramètres modifiables :

  • sourceMode
  • engineCode
  • modelCode
  • API key
  • baseUrl

Si vous utilisez ai4call

  • Envoyer sourceMode: ai4call
  • Envoyer modelCode
  • engineCode et facultatif
  • N'envoyez pas API key
  • N'envoyez pas baseUrl

Si vous utilisez customer

  • Envoyer sourceMode: customer
  • Envoyer engineCode
  • Envoyer modelCode
  • Si engineCode = ollama, envoyez baseUrl
  • Pour tous les autres moteurs, envoyer API key

Remarque sur la fusion

  • Les champs omis conservent la valeur actuelle, s'ils sont déjà présents
  • La réponse renvoie la configuration finale résultante

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

Choisissez l'un des exemples ci-dessous en fonction du mode que vous souhaitez définir.

  • ai4call : sélection d'un modèle dans le catalogue AI4Call
  • customer : configuration directe avec le fournisseur du client

PATCH fusionne la configuration LLM du assistant.

Règles de fonctionnement :

  • sourceMode et toujours obligatoire
  • les champs omis conservent la valeur actuelle déjà enregistrée, si présente
  • dans ai4call le backend résout la configuration à partir de modelCode
  • dans customer la configuration utilise des paramètres client directs

Contraintes d'application :

  • customer : engineCode et modelCode doivent être complétés après la fusion
  • customer avec ollama : baseUrl doit être complété après la fusion
  • customer avec des moteurs autres que ollama : API key doit être complété après la fusion
  • ai4call : utilisez modelCode ; engineCode est facultatif et sert uniquement de contrôle de cohérence
  • sourceMode
    Type: "ai4call" or "customer"enum
    obligatoire

    Mode de sourcing d’exécution.

    • ai4call : utilise un modèle présent dans les tarifs AI4Call du client
    • customer : utiliser les informations d'identification et la configuration directes du client
  • apiKey
    Type: string | null
    écriture seule

    Clé API du fournisseur LLM du client. Il doit être envoyé en customer pour les prestataires qui en font la demande. Pour ollama, cela n’est normalement pas nécessaire. Dans ai4call, il doit être omis.

  • baseUrl
    Type: string | null

    URL personnalisée de base du fournisseur LLM. Généralement utilisé pour les points de terminaison ollama ou auto-hébergés compatibles OpenAI. En customer avec ollama et obligatoire. Dans ai4call, il doit être omis.

  • engineCode
    Type: string | null

    Code du moteur/fournisseur LLM. Dans customer identifie le fournisseur à utiliser. Dans ai4call, il est facultatif et, s'il est envoyé, il est uniquement utilisé pour vérifier que le modelCode appartient à ce moteur.

  • modelCode
    Type: string | null

    Code du modèle LLM. Dans ai4call se trouve le paramètre principal pour sélectionner le modèle dans le catalogue AI4Call. Dans customer, il doit identifier le modèle valide pour le fournisseur choisi.

  • providerWalletId
    Type: integer | null

    Id d'un identifiant enregistre dans le portefeuille de fournisseurs du client, a utiliser a la place de l'envoi de apiKey en clair.

    Quand il est present, les identifiants sont lus depuis le portefeuille, appliques au runtime et l'association est enregistree sur l'assistant. null supprime l'association et revient aux valeurs envoyees explicitement.

    Les identifiants du portefeuille se creent et se gerent depuis le portail AI4CALL.

Réponses

  • 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"
    }
  }
}

Configuration d'exécution LLM mise à jour

Répertorie les prestataires LLM disponibles pour le client

​

Répertorie les prestataires LLM disponibles pour le client

Réponses

  • 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"
        ]
      }
    ]
  }
}

Liste des prestataires LLM

Répertorie les modèles LLM résolus par la configuration du runtime de l'assistant

​

Répertorie les modèles LLM résolus par la configuration du runtime de l'assistant

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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"
      }
    ]
  }
}

Liste des modèles LLM d'assistant

Catalog Audio-to-Audio

​

Fournisseurs, modèles, voix et exécutions canoniques pour les assistants audio-à-audio

Catalog Audio-to-Audio Opérations

Met a jour la configuration runtime audio-to-audio de l'assistant

​

Route canonique pour les assistants realtime audio-to-audio.

PATCH /api/v1/assistants/{assistantApiKey}/runtime/voice-to-voice reste un alias historique : meme handler, meme payload, meme reponse.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

PATCH merge de la configuration d'exécution audio-à-audio.

Met à jour le JSON serveur configType: voice-llm. Au moins un champ doit être présent parmi engineCode, modelCode, voiceCode, providerWalletId, apiKey, baseUrl ou prompt.

  • apiKey
    Type: string | null
    écriture seule

    API du fournisseur de clés client. Envoyez null pour le supprimer du JSON.

  • baseUrl
    Type: string | null

    URL personnalisée de base. Envoyez null pour le supprimer du JSON.

  • engineCode
    Type: string

    LLM voix fournisseur/moteur.

  • modelCode
    Type: string

    Code du modèle vocal LLM.

  • prompt
    Type: string

    Prompt principal du runtime audio-to-audio.

  • providerWalletId
    Type: integer | null

    Id d'un identifiant enregistre dans le portefeuille de fournisseurs du client, a utiliser a la place de l'envoi de apiKey en clair.

    Quand il est present, les identifiants sont lus depuis le portefeuille, appliques au runtime et l'association est enregistree sur l'assistant. null supprime l'association et revient aux valeurs envoyees explicitement.

    Les identifiants du portefeuille se creent et se gerent depuis le portail AI4CALL.

  • voiceCode
    Type: string

    Code article du modèle.

Réponses

  • 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-à-audio mis à jour

Répertorie les fournisseurs de voix LLM disponibles pour le client

​

Répertorie les fournisseurs de voix LLM disponibles pour le client

Réponses

  • 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"
        ]
      }
    ]
  }
}

Liste des fournisseurs de voix LLM

Répertorie les modèles LLM vocaux

​

Répertorie les modèles LLM vocaux

Paramètres de requête

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

Réponses

  • 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"
      }
    ]
  }
}

Liste des modèles vocaux LLM

Répertorie les voix disponibles pour un modèle vocal LLM

​

Répertorie les voix disponibles pour un modèle vocal LLM

Paramètres de requête

  • modelCode
    Type: string
    obligatoire

Réponses

  • 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"
      }
    ]
  }
}

Liste des entrées vocales LLM

Répertorie les modèles vocaux LLM cohérents avec l'assistant

​

Répertorie les modèles vocaux LLM cohérents avec l'assistant

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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"
      }
    ]
  }
}

Liste des modèles LLM d'assistant vocal

Répertorie les entrées vocales LLM disponibles pour un assistant

​

Répertorie les entrées vocales LLM disponibles pour un assistant

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Paramètres de requête

  • modelCode
    Type: string
    obligatoire

Réponses

  • 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"
      }
    ]
  }
}

Liste des entrées LLM assistant vocal

Catalog DTMF

​

Configuration de l'assistant DTMF et mise à jour du runtime DTMF

Catalog DTMF Opérations

Mettre à jour la configuration d'exécution DTMF de l'assistant

​

Mettez à jour la configuration DTMF de l'assistant avec la sémantique PATCH merge.

Paramètres modifiables :

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

Comment récupérer les données actuelles :

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

Règles de fonctionnement :

  • si vous souhaitez modifier un seul champ, envoyez uniquement ce champ
  • enabled: false réinitialise tous les paramètres DTMF
  • playEnabled reste indépendant de la bascule DTMF reçue
  • sur les assistants voice_to_voice le backend met à jour dtmf et pbxTools.dtmf/playDtmf dans le JSON voice-llm

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

Fusion PATCH de la configuration DTMF de l'assistant.

Règles de fonctionnement :

  • au moins un des enabled, playEnabled, acceptTimeout, minLength, maxLength, terminationChars doit être présent
  • les champs omis conservent la valeur actuelle
  • en envoyant l'un des paramètres DTMF avec enabled omis, DTMF est considéré comme activé
  • enabled: false réinitialise acceptTimeout, minLength, maxLength et terminationChars
  • playEnabled contrôle l'envoi DTMF pendant l'appel
  • acceptTimeout
    Type: integer | null
    min.:  
    0

    Valeur à envoyer pour acceptTimeout dans la requête AssistantDtmfRuntimeUpdateRequest.

  • enabled
    Type: boolean

    Activez ou désactivez la réception DTMF.

  • maxLength
    Type: integer | null
    min.:  
    0

    Valeur à envoyer pour maxLength dans la requête AssistantDtmfRuntimeUpdateRequest.

  • minLength
    Type: integer | null
    min.:  
    0

    Valeur à envoyer pour minLength dans la requête AssistantDtmfRuntimeUpdateRequest.

  • playEnabled
    Type: boolean

    Activez ou désactivez l'envoi DTMF pendant l'appel.

  • terminationChars
    Type: string | null

    Valeur à envoyer pour terminationChars dans la requête AssistantDtmfRuntimeUpdateRequest.

Réponses

  • 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"
    }
  }
}

Configuration d'exécution DTMF mise à jour

Récupérer la configuration DTMF de l'assistant

​

Récupérer la configuration DTMF de l'assistant

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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": "#"
    }
  }
}

Assistant configuration DTMF

Catalog Settings

​

Paramètres de l'assistant et paramètres avancés

Catalog Settings Opérations

Mettre à jour les paramètres de l'assistant

​

Mettez à jour les paramètres de l’assistant avec la sémantique PATCH merge.

Paramètres modifiables :

  • 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

Comment récupérer les données actuelles :

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

Règles de fonctionnement :

  • si vous souhaitez modifier un seul champ, envoyez uniquement ce champ
  • filler, reprompt et callPermissions fusionnent uniquement les champs présents
  • country, prefixMobile et prefixFixed peuvent être réglés sur null
  • sur les assistants voice_to_voice, les paramètres conversationnels sont écrits dans la racine JSON voice-llm ; les autorisations d'appel restent sur la base de données comme dans le portail

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

PATCH fusion des paramètres du serveur.

Comment récupérer les données actuelles :

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

Règles de fonctionnement :

  • envoyer uniquement les champs à modifier
  • filler, reprompt et callPermissions utilisent une fusion partielle sur les champs envoyés
  • callPermissions utilise une fusion partielle sur les champs envoyés
  • country, prefixMobile et prefixFixed peuvent être envoyés à null pour supprimer la valeur enregistrée
  • asrInitialDelayMs
    Type: integer
    min.:  
    0
    max.:  
    10000

    Valeur à envoyer pour asrInitialDelayMs dans la requête AssistantSettingsRuntimeUpdateRequest.

  • asrSilenceMs
    Type: integer
    min.:  
    500
    max.:  
    5000

    Valeur à envoyer pour asrSilenceMs dans la requête AssistantSettingsRuntimeUpdateRequest.

  • callPermissions
    Type: object

    Valeur à envoyer pour callPermissions dans la requête AssistantSettingsRuntimeUpdateRequest.

    Propriétés : 8
  • dynamicTimeoutMs
    Type: integer
    min.:  
    5000
    max.:  
    300000

    Valeur à envoyer pour dynamicTimeoutMs dans la requête AssistantSettingsRuntimeUpdateRequest.

  • filler
    Type: object

    Valeur à envoyer pour filler dans la requête AssistantSettingsRuntimeUpdateRequest.

    Propriétés : 6
  • maxResponseLength
    Type: integer
    min.:  
    1000
    max.:  
    10000000

    Valeur à envoyer pour maxResponseLength dans la requête AssistantSettingsRuntimeUpdateRequest.

  • reprompt
    Type: object

    Valeur à envoyer pour reprompt dans la requête AssistantSettingsRuntimeUpdateRequest.

    Propriétés : 5
  • truncateInitialAudio
    Type: boolean

    Valeur à envoyer pour truncateInitialAudio dans la requête AssistantSettingsRuntimeUpdateRequest.

  • ttsInterruptionInConversation
    Type: boolean

    Valeur à envoyer pour ttsInterruptionInConversation dans la requête AssistantSettingsRuntimeUpdateRequest.

  • vad
    Type: boolean

    Valeur à envoyer pour vad dans la requête AssistantSettingsRuntimeUpdateRequest.

  • vadMinVoiceMs
    Type: integer
    min.:  
    0

    Valeur à envoyer pour vadMinVoiceMs dans la requête AssistantSettingsRuntimeUpdateRequest.

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

    Valeur à envoyer pour vadThreshold dans la requête AssistantSettingsRuntimeUpdateRequest.

Réponses

  • 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"
      }
    }
  }
}

Paramètres mis à jour

Mettre à jour les paramètres avancés de l'assistant

​

Mettez à jour les paramètres avancés de l'assistant avec la sémantique PATCH merge.

Paramètres modifiables :

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

Comment récupérer les données actuelles :

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

Règles de fonctionnement :

  • si vous souhaitez modifier un seul champ, envoyez uniquement ce champ
  • les champs numériques peuvent être envoyés à null pour être supprimés
  • stopSequences: null ou stopSequences: [] réinitialise la liste
  • sur les assistants voice_to_voice ces valeurs sont écrites à la racine JSON voice-llm

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

PATCH fusion des paramètres avancés de l'assistant.

Comment récupérer les données actuelles :

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

Règles de fonctionnement :

  • envoyer uniquement les champs à modifier
  • les champs numériques peuvent être envoyés à null pour être supprimés
  • stopSequences: null ou stopSequences: [] réinitialise la liste
  • freqPenalty
    Type: number | null
    min.:  
    -2
    max.:  
    2

    Valeur à envoyer pour freqPenalty dans la requête AssistantAdvancedSettingsRuntimeUpdateRequest.

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

    Valeur à envoyer pour maxTokens dans la requête AssistantAdvancedSettingsRuntimeUpdateRequest.

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

    Valeur à envoyer pour presencePenalty dans la requête AssistantAdvancedSettingsRuntimeUpdateRequest.

  • stopSequences
    Type: array of string | null

    Valeur à envoyer pour stopSequences dans la requête AssistantAdvancedSettingsRuntimeUpdateRequest.

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

    Valeur à envoyer pour temperature dans la requête AssistantAdvancedSettingsRuntimeUpdateRequest.

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

    Valeur à envoyer pour topK dans la requête AssistantAdvancedSettingsRuntimeUpdateRequest.

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

    Valeur à envoyer pour topP dans la requête AssistantAdvancedSettingsRuntimeUpdateRequest.

Réponses

  • 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"
      ]
    }
  }
}

Paramètres avancés mis à jour

Récupérer les paramètres de l'assistant

​

Récupérer les paramètres de l'assistant

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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"
      }
    }
  }
}

Paramètres de l'assistant

Récupérer les paramètres avancés de l'assistant

​

Récupérer les paramètres avancés de l'assistant

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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"
      ]
    }
  }
}

Paramètres avancés de l'assistant

Catalog Hangup

​

Configuration du raccrochage, redirection et transfert du assistant

Catalog Hangup Opérations

Mettre à jour la configuration d'exécution du raccrochage de l'assistant

​

Mettez à jour la configuration de raccrochage, de redirection et de transfert avec la sémantique PATCH merge.

Paramètres modifiables :

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

Comment récupérer les données actuelles :

  • utilisez GET /api/v1/catalog/assistants/{assistantApiKey}/hangup
  • utiliser GET /api/v1/assistants pour récupérer les assistantApiKey sélectionnables pour le transfert

Règles de fonctionnement :

  • si vous souhaitez modifier un seul paramètre, envoyez uniquement ce paramètre
  • enableTransferAgent: false réinitialise les notifications et les assistants connectés
  • si enableTransferAgent est actif, il faut au moins un assistant avec une description non vide
  • sur les assistants voice_to_voice, le backend met à jour pbxTools.hangup, pbxTools.redirect et pbxTools.transferAgent

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

Fusion PATCH de la configuration de blocage/redirection/transfert du assistant.

Règles de fonctionnement :

  • au moins un des enableHangup, enableRedirect, enableTransferAgent, transferAgentNotificationText, availableAgents doit être présent
  • les champs omis conservent la valeur actuelle
  • utilisez GET /api/v1/catalog/assistants/{assistantApiKey}/hangup pour lire l'état actuel
  • utilisez GET /api/v1/assistants pour récupérer le assistantApiKey sélectionnable pour le transfert
  • si enableTransferAgent et true, il vous faut au moins un availableAgents avec une description non vide
  • si vous envoyez availableAgents avec enableTransferAgent omis, le transfert est considéré comme actif
  • enableTransferAgent: false réinitialise transferAgentNotificationText et availableAgents
  • availableAgents
    Type:

    Valeur à envoyer pour availableAgents dans la requête AssistantHangupRuntimeUpdateRequest.

    Propriétés : 2
  • enableHangup
    Type: boolean

    Valeur à envoyer pour enableHangup dans la requête AssistantHangupRuntimeUpdateRequest.

  • enableRedirect
    Type: boolean

    Valeur à envoyer pour enableRedirect dans la requête AssistantHangupRuntimeUpdateRequest.

  • enableTransferAgent
    Type: boolean

    Valeur à envoyer pour enableTransferAgent dans la requête AssistantHangupRuntimeUpdateRequest.

  • transferAgentNotificationText
    Type: string | null

    Valeur à envoyer pour transferAgentNotificationText dans la requête AssistantHangupRuntimeUpdateRequest.

Réponses

  • 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": "exemple"
        }
      ]
    }
  }
}

Configuration d'exécution de raccrochage mise à jour

Récupérer la configuration de sauvegarde des conversations de l'assistant

​

Renvoie l'état actuel d'enregistrement de la conversation :

  • enabled : si l'envoi du récapitulatif par email est actif
  • emails : destinataires configurés (chaîne séparée par des virgules)
  • smtpInstanceName : nom de l'instance du plugin SMTP connectée

Prérequis : Le client doit disposer d'au moins un abonnement actif à un plugin SMTP.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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"
    }
  }
}

Configuration de sauvegarde de conversation récupérée

Mettre à jour la configuration de sauvegarde des conversations de l'assistant

​

Mettez à jour la configuration de sauvegarde des conversations avec la sémantique PATCH merge.

Paramètres modifiables :

  • enabled
  • emails
  • smtpInstanceName

Comment récupérer les données actuelles :

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

Règles de fonctionnement :

  • au moins un parmi enabled, emails et smtpInstanceName doit être présent
  • les champs omis conservent la valeur actuelle
  • smtpInstanceName doit correspondre au instanceName de l'abonnement SMTP actif d'un client
  • pour obtenir la liste des instances SMTP disponibles, vérifiez les abonnements aux plugins du client
  • emails accepte une chaîne avec un ou plusieurs emails séparés par des virgules
  • le paramètre smtpInstanceName: null supprime la connexion à l'instance SMTP

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

Fusion PATCH de la configuration de sauvegarde des conversations de l'assistant.

Règles de fonctionnement :

  • au moins un parmi enabled, emails et smtpInstanceName doit être présent
  • les champs omis conservent la valeur actuelle
  • smtpInstanceName correspond au instanceName de l'abonnement SMTP actif du client
  • si enabled: true, un plugin SMTP actif doit être configuré
  • emails accepte une chaîne avec un ou plusieurs emails séparés par des virgules
  • emails
    Type: string | null

    Un ou plusieurs e-mails de destinataire séparés par des virgules (par exemple, email1@example.com, email2@example.com)

  • enabled
    Type: boolean

    Activer ou désactiver l'envoi du résumé de la conversation par email

  • smtp_instance_name
    Type: string | null
    obsolète

    Alias ​​hérité de smtpInstanceName.

  • smtpInstanceName
    Type: string | null

    Nom de l'instance du plugin SMTP à utiliser pour l'envoi

Réponses

  • 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"
    }
  }
}

Configuration d'enregistrement des conversations mise à jour

Recupere la configuration du webhook de fin de conversation de l'assistant

​

Renvoie la configuration actuelle du webhook appele en fin d'appel :

  • enabled : si l'envoi est actif
  • url : endpoint de destination
  • authName : nom de l'authentification appliquee, null pour un appel non authentifie
  • payloadFields : champs toujours presents dans le body envoye

Ce canal est une alternative a l'envoi par email (runtime/hangup/save-conversation) et les deux peuvent etre actifs en meme temps.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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"
      ]
    }
  }
}

Configuration webhook recuperee

Met a jour la configuration du webhook de fin de conversation de l'assistant

​

Met a jour la configuration du webhook avec une semantique PATCH merge.

Parametres modifiables :

  • enabled
  • url
  • authName

Comment recuperer les donnees actuelles :

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

Regles operationnelles :

  • au moins un parmi enabled, url et authName doit etre present
  • les champs omis conservent la valeur actuelle
  • activer sans une url http:// ou https:// valide renvoie 400
  • authName doit correspondre a une authentification deja enregistree par le client ; les identifiants sont resolus cote serveur et ne transitent pas dans ce payload
  • definir authName: null envoie le webhook sans authentification

Body recu par l'endpoint : caller, called, callid et conversation.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

PATCH merge de la configuration du webhook de fin de conversation de l'assistant.

Regles operationnelles :

  • au moins un parmi enabled, url et authName doit etre present
  • les champs omis conservent la valeur actuelle
  • si enabled: true, url doit etre une adresse http:// ou https:// valide
  • authName correspond au nom d'une authentification deja enregistree par le client ; les identifiants sont resolus cote serveur et ne transitent pas dans ce payload
  • definir authName: null envoie le webhook sans authentification
  • authName
    Type: string | null

    Nom de l'authentification enregistree a appliquer a la requete

  • enabled
    Type: boolean

    Active ou desactive l'envoi de la conversation au webhook

  • url
    Type: string | null

    Endpoint qui recoit le POST en fin d'appel

Réponses

  • 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"
      ]
    }
  }
}

Configuration webhook mise a jour

Récupérer la configuration du schéma de l'outil de raccrochage

​

Renvoie la configuration actuelle du schéma envoyé au webhook de raccrochage :

  • hangupUrl : URL du webhook appelé en fin d'appel
  • schema : tableau de propriétés qui définissent le corps JSON envoyé à l'URL de raccrochage

Chaque propriété peut être de type string, number, boolean, enum ou object. Les propriétés de type object prennent en charge les champs imbriqués via children. Sur les assistants voice_to_voice, le motif est lu à partir de pbxTools.hangupEndpoint.input_schema.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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": "Raison du raccrochage",
          "required": true
        },
        {
          "name": "esito",
          "type": "enum",
          "description": "Résultat de l'appel",
          "required": true,
          "enumValues": [
            "positivo",
            "negativo",
            "richiamata"
          ]
        },
        {
          "name": "dati_cliente",
          "type": "object",
          "description": "Données collectées sur le client",
          "children": [
            {
              "name": "nome",
              "type": "string",
              "description": "Nom du client"
            },
            {
              "name": "email",
              "type": "string",
              "description": "E-mail du client"
            }
          ]
        }
      ]
    }
  }
}

Modèle de raccrochage récupéré avec succès

Mettre à jour la configuration du schéma de l'outil de raccrochage

​

Mettez à jour la configuration du schéma de raccrochage avec la sémantique PATCH merge.

Paramètres modifiables :

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

Comment récupérer les données actuelles :

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

Règles de fonctionnement

  • Au moins un entre hangupUrl et schema doit être présent dans le body
  • Les champs omis conservent la valeur actuelle
  • L'envoi de schema remplace complètement le schéma actuel (ce n'est pas une fusion)
  • L'envoi de hangupUrl: null supprime le webhook d'URL, désactive l'outil de raccrochage et efface également automatiquement le schéma
  • L'envoi de schema: [] efface le schéma en conservant l'URL actuelle
  • Sur les assistants voice_to_voice, le backend met à jour pbxTools.hangupEndpoint.endpoint et pbxTools.hangupEndpoint.input_schema

Comment construire le corps du schéma

Le schema est un tableau de propriétés qui définissent les champs du corps JSON envoyé à hangupUrl à la fin de l'appel. Chaque propriété a la structure suivante :

Champ Tapez Obligatoire Descriptif
name string oui Nom du champ dans le corps JSON
type string oui Type de champ : string, number, boolean, enum, object
description string non Description du champ (aide le modèle LLM à comprendre ce qu'il faut saisir)
required boolean non Si true, le champ est obligatoire dans le corps raccrocher
enumValues string[] uniquement pour enum Liste des valeurs autorisées (uniquement si type: enum)
children Property[] uniquement pour object Champs imbriqués (uniquement si type: object)

Types pris en charge et comment les utiliser

string — champ de texte libre :

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

number — champ numérique :

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

boolean — champ booléen :

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

enum — champ à choix multiples, nécessite enumValues :

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

object — groupe de champs imbriqué, nécessite 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" }
  ]
}

Exemple de corps JSON résultant

Avec le schéma ci-dessus, le webhook recevra un corps similaire à :

{
  "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"
  }
}

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json
  • hangupUrl
    Type: string | null

    URL du webhook de raccrochage (nul à supprimer)

  • schema
    Type:

    Définir les champs du corps (remplace le schéma actuel)

    Propriétés : 6

Réponses

  • 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": "Raison du raccrochage",
      "required": true
    },
    {
      "name": "esito",
      "type": "enum",
      "description": "Résultat de l'\''appel",
      "required": true,
      "enumValues": [
        "positivo",
        "negativo",
        "richiamata"
      ]
    },
    {
      "name": "dati_cliente",
      "type": "object",
      "description": "Données collectées sur le client",
      "children": [
        {
          "name": "nome",
          "type": "string",
          "description": "Nom du client"
        },
        {
          "name": "email",
          "type": "string",
          "description": "E-mail du client"
        }
      ]
    }
  ]
}'

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

Diagramme de raccrochage mis à jour avec succès

Récupérer la configuration de raccrochage de l'assistant

​

Récupérer la configuration de raccrochage de l'assistant

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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": "Transfert lorsque le client demande un soutien administratif."
        }
      ]
    }
  }
}

Configuration du raccrochage de l'assistant

Catalog Pre-Call

​

Configuration de l'assistant de pré-appel

Catalog Pre-Call Opérations

Récupérer la configuration de vérification du numéro d'appelant

​

Renvoie la configuration actuelle du webhook utilisé pour vérifier le numéro l’appelant avant que l’appel ne soit connecté à l’assistant.

Si aucune configuration n'a encore été créée, data.configuration sera null.

Comment fonctionne la vérification du numéro

Lorsqu'un appel arrive, le système envoie une requête HTTP au webhook configuré, en passant le numéro de l'appelant dans le champ indiqué (numberParamName), à la position indiqué (numberLocation). Le webhook doit répondre avec : 

{ "enabled": true }
  • Si enabled est true (ou absent) : l'appel continue normalement
  • Si enabled est false : l'appel est bloqué

Le webhook peut également renvoyer un objet callerInfo avec des données supplémentaires qui sera mis à la disposition de l'assistant lors de l'appel.

Consigne de sécurité

Les champs sensibles (authToken, authPassword) ne sont jamais renvoyés en texte clair. A leur place se trouvent les drapeaux hasAuthToken et hasAuthPassword.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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'
Configuration présente
{
  "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
    }
  }
}

Configuration de vérification du numéro récupérée

Créer ou mettre à jour la configuration de vérification du numéro d'appelant

​

Créez la configuration si elle n'existe pas, sinon mettez à jour les champs fournis avec la sémantique PATCH merge (les champs omis conservent la valeur actuelle).

Paramètres modifiables :

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

Comment récupérer les données actuelles :

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

Règles de fonctionnement

  • Au moins un champ doit être présent dans le corps
  • Les champs omis conservent la valeur actuelle (ou la valeur par défaut s'il s'agit de la première création)
  • Envoyer isActive: false supprime complètement la configuration — data.configuration sera null
  • La configuration est toujours active (isActive: true) lors de sa création ou de sa mise à jour
  • L'envoi de authToken: null supprime le token configuré
  • L'envoi de authPassword: null supprime le mot de passe configuré
  • L'envoi de headersJson: null supprime tous les en-têtes personnalisés
  • authToken et authPassword ne sont jamais retournés — utilisez hasAuthToken/hasAuthPassword

Comment configurer numberLocation

Valeur Où le numéro est envoyé Exemple
query Chaîne de requête URL GET /validate?caller_id=0391234567
body Corps JSON de la requête POST /validate avec justaucorps { "caller_id": "0391234567" }
params Segment d'URL GET /validate/0391234567 (le numéro remplace :numberParamName dans l'URL)

Authentification prise en charge

authType Champs obligatoires En-tête généré
none — aucun
bearer authToken Authorization: Bearer <token>
api_key authToken X-Api-Key: <token>
basic authUsername + authPassword Authorization: Basic <base64>

Réponse attendue du webhook

Le webhook doit répondre avec HTTP 200 et un corps JSON contenant au moins :

{ "enabled": true }

Peut inclure des données supplémentaires :

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

Si enabled est false, l'appel est bloqué avant d'atteindre l'assistant.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json
  • authPassword
    Type: string | null

    Mot de passe d'authentification de base (nul pour le supprimer)

  • authToken
    Type: string | null

    Jeton porteur ou clé API (null pour le supprimer)

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

    Valeur à envoyer pour authUsername dans la requête AssistantPrecallValidationRuntimeUpdateRequest.

  • headersJson
    Type: object | null

    Valeur à envoyer pour headersJson dans la requête AssistantPrecallValidationRuntimeUpdateRequest.

    Propriétés : 1
  • isActive
    Type: boolean

    Valeur à envoyer pour isActive dans la requête AssistantPrecallValidationRuntimeUpdateRequest.

  • method
    Type: enum
    valeurs
    GETPOSTPUTPATCHDELETE
  • name
    Type: string
    longueur min.:  
    1

    Valeur à envoyer pour name dans la requête AssistantPrecallValidationRuntimeUpdateRequest.

  • numberLocation
    Type: enum

    Où insérer le numéro appelant dans la requête HTTP :

    • query — ajouté en tant que chaîne de requête (par exemple ?number=0391234567)
    • body — inséré dans le corps JSON (par exemple { "number": "0391234567" })
    • params — remplace un segment de l'URL (par exemple /validate/0391234567)
    valeurs
    bodyqueryparams
  • numberParamName
    Type: string
    longueur min.:  
    1

    Valeur à envoyer pour numberParamName dans la requête AssistantPrecallValidationRuntimeUpdateRequest.

  • timeoutMs
    Type: integer
    min.:  
    500
    max.:  
    30000

    Valeur à envoyer pour timeoutMs dans la requête AssistantPrecallValidationRuntimeUpdateRequest.

  • url
    Type: stringFormat: uri

    Valeur à envoyer pour url dans la requête AssistantPrecallValidationRuntimeUpdateRequest.

Réponses

  • 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
    }
  }
}

Configuration de vérification du numéro mise à jour

Récupérer la configuration de pré-appel de l'assistant

​

Renvoie la configuration actuelle de la phase de pré-appel : paramètres généraux (configuration) et outils associés (tools).

Comment fonctionne la phase de pré-appel

Avant que l'appel ne soit connecté à l'assistant, le système effectue séquentiellement les outils configurés (dans l'ordre défini par order). Les outils peuvent être :

  • outils personnalisés (définis dans le serveur JSON, subscriptionName: null)
  • plugin outil MCP ou MCP personnalisé (avec subscriptionName amélioré)

Les outils peuvent récupérer les informations de l'appelant, effectuer une validation ou enrichir le contexte et mettre fin à l'appel plus tôt si earlyTerminationEnabled est true.

Si waitingAudioText est configuré, il est joué à l'appelant pendant l'exécution. voiceConfig contrôle la voix utilisée pour générer l'audio d'attente/terminaison, tandis que modelConfig contrôle le modèle utilisé pour interpréter les résultats des outils.

Comment lire tools

Les champs toolName et subscriptionName retournés correspondent aux champs toolName et subscriptionName pour envoyer le PATCH. Les outils de pré-appel ne peuvent être choisis que parmi ceux déjà associés à l'assistant :

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

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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'
Outils personnalisés et plugins MCP associés
{
  "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
      }
    ]
  }
}

Configuration pré-appel récupérée

Mettre à jour la configuration de pré-appel de l'assistant

​

Mettez à jour la configuration préalable à l'appel avec la sémantique PATCH merge. Au moins un champ doit être présent dans le body.

Paramètres modifiables :

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

Comment récupérer la configuration actuelle : -GET /api/v1/assistants/{assistantApiKey}/runtime/precall/mcp-config

Gestion des outils

Le champ tools remplace complètement les outils de pré-appel actuels :

Corps posté Effet
tools omis conserve les outils actuels inchangés
tools: [] supprime tous les outils de pré-appel et réinitialise toute la configuration de pré-appel
tools: [{...}] remplace par la liste envoyée

Pour le tri :

  • si chaque élément comprend order, order est utilisé
  • si order est omis, l'ordre du tableau est utilisé

Comment construire la liste tools

Utilisez les enregistrements de GET /api/v1/catalog/assistants/{assistantApiKey}/tools pour obtenir toolName et instanceName. Le pré-appel n'accepte que les outils déjà associés à l'assistant :

Type d'outil toolName subscriptionName
custom_tool (outil JSON personnalisé) toolName null
plugin_tool (plug-in MCP) toolName instanceName
custom_mcp_tool (MCP personnalisé) toolName instanceName

Les outils personnalisés (subscriptionName: null) sont ceux définis dans le JSON de l'assistant et ils ne nécessitent pas d'abonnement.

Configuration générale

Champ Effet
globalPrompt: null supprime l'invite globale
waitingAudioText: null supprime l'audio d'attente
earlyTerminationEnabled: true permettre une résiliation anticipée
terminationMessage: null supprime le message de résiliation
waitingAudioNonInterruptible: false rend l'audio de maintien interrompu
modelConfig définir par défaut/assistant/géré/personnalisé pour le modèle de pré-appel
voiceConfig définir par défaut/assistant/personnalisé pour le TTS pré-appel

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

Mettez à jour la configuration préalable à l'appel avec la sémantique PATCH merge. Au moins un champ doit être présent.

Gestion des outils

Le champ tools remplace complètement la liste des outils de pré-appel.

  • tools: [] supprime tous les outils de pré-appel et réinitialise globalPrompt, waitingAudioText, earlyTerminationEnabled, terminationMessage, waitingAudioNonInterruptible, modelConfig et voiceConfig
  • tools omis : conserver les outils actuels inchangés
  • Si order est présent, l'ordre d'exécution suit order
  • Si order est omis, l'ordre d'exécution suit l'ordre du tableau envoyé

Pour construire la liste, utilisez les enregistrements de GET /api/v1/catalog/assistants/{assistantApiKey}/tools. Le pré-appel n'accepte que les outils déjà associés à l'assistant.

  • earlyTerminationEnabled
    Type: boolean

    Activer/désactiver la résiliation anticipée.

  • enabled
    Type: boolean

    Active ou desactive toute la phase de pre-call sans en perdre la configuration. S'il est omis, conserve la valeur actuelle.

  • globalPrompt
    Type: string | null

    Invite de pré-appel globale. null pour le supprimer.

  • modelConfig
    Type:

    Configuration du modèle utilisée par la phase MCP. Les clés API ne sont pas renvoyées en texte clair : hasApiKey est exposé dans les réponses.

    Propriétés : 5
  • outputSchema
    Type: object

    Schema JSON de la sortie attendue du pre-call, en alternative a outputVariables.

    Propriétés : 1
  • outputVariables
    Type:

    Variables a extraire du resultat du pre-call. Remplace entierement la liste actuelle.

    Propriétés : 4
  • terminationMessage
    Type: string | null

    Message audio de résiliation anticipée. null pour le supprimer.

  • tools
    Type:

    Liste complète des outils de pré-appel à paramétrer (remplace ceux actuels).

  • voiceConfig
    Type:

    Configuration vocale/TTS utilisée pour générer l'audio de mise en attente et de terminaison avant l'appel. Les clés API ne sont pas renvoyées en texte clair : hasApiKey est exposé dans les réponses.

    Propriétés : 8
  • waitingAudioNonInterruptible
    Type: boolean

    true lit tout l'audio en attente, false permet au client de parler via l'audio.

  • waitingAudioText
    Type: string | null

    Texte audio en attente. null pour le supprimer.

Réponses

  • 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
      }
    ]
  }
}

Configuration de pré-appel mise à jour

Récupérer la configuration de pré-appel de l'assistant

​

Récupérer la configuration de pré-appel de l'assistant

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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
    }
  }
}

Configuration pré-appel

Catalog Post-Call

​

Configuration de l'assistant MCP après appel

Catalog Post-Call Opérations

Récupérer la configuration post-appel MCP de l'assistant

​

Renvoie la configuration actuelle de la phase post-appel MCP : paramètres généraux (configuration) et outils associés (tools).

Les champs toolName et subscriptionName renvoyés correspondent aux champs toolName et subscriptionName pour envoyer le PATCH. Les outils post-appel ne peuvent être choisis que parmi ceux déjà associés à l'assistant :

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

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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'
Outils post-appel associés
{
  "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
      }
    ]
  }
}

Configuration post-appel récupérée

Mettre à jour la configuration post-appel MCP de l'assistant

​

Mettez à jour la configuration post-appel avec la sémantique PATCH merge. Au moins un champ doit être présent dans le body.

Paramètres modifiables :

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

Comment récupérer la configuration actuelle :

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

Le champ tools remplace complètement les outils post-appel actuels :

Corps posté Effet
tools omis conserve les outils actuels inchangés
tools: [] supprime tous les outils post-appel et réinitialise globalPrompt et modelConfig
tools: [{...}] remplace par la liste envoyée

Utiliser les enregistrements de GET /api/v1/catalog/assistants/{assistantApiKey}/tools pour obtenir toolName et instanceName.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

Mettez à jour la configuration post-appel avec la sémantique PATCH merge. Au moins un champ doit être présent.

Le champ tools remplace complètement la liste des outils post-appel.

  • tools: [] supprime tous les outils post-appel et réinitialise globalPrompt et modelConfig
  • tools omis : conserver les outils actuels inchangés
  • enabled
    Type: boolean

    Active ou desactive toute la phase de post-call sans en perdre la configuration. Quand il est false, le webhook de fin d'appel n'est pas envoye. S'il est omis, conserve la valeur actuelle.

  • globalPrompt
    Type: string | null

    Invite globale post-appel. null pour le supprimer.

  • modelConfig
    Type:

    Configuration du modèle utilisée par la phase MCP. Les clés API ne sont pas renvoyées en texte clair : hasApiKey est exposé dans les réponses.

    Propriétés : 5
  • tools
    Type:

    Liste complète des outils post-appel à mettre en place.

Réponses

  • 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
      }
    ]
  }
}

Configuration post-appel mise à jour

Catalog Runtime Bindings

​

Liaison d'exécution de l'assistant aux prix et fournisseurs réels

Catalog Runtime Bindings Opérations

Récupère les liaisons d'exécution de l'assistant vers TTS, ASR et LLM

​

Récupère les liaisons d'exécution de l'assistant vers TTS, ASR et LLM

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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"
      }
    }
  }
}

Liaison d'exécution de l'Assistant

Knowledge

​

Ressources knowledge canoniques du client et associations aux assistants

Knowledge Opérations

Liste les knowledge du client

​

Renvoie les knowledge du client ainsi que celles fournies par AI4CALL, de la plus recente. Celles partagees portent isShared: true : elles peuvent etre associees a vos assistants mais pas modifiees.

Chaque entree revient complete avec ses declencheurs, tries par sortOrder.

Paramètres de requête

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximal d'éléments renvoyés dans une page paginée par curseur. Omettez limit et cursor pour conserver la réponse historique non paginée.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor par la page précédente.

Réponses

  • 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": "Horaires et sites",
        "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 disponibles pour le client

Cree une knowledge

​

Cree une knowledge appartenant au client.

Une knowledge est un ensemble de demandes reconnues, les declencheurs, avec ce que l'assistant doit repondre. Elle est inseree dans le prompt de chaque assistant auquel elle est associee, donc la creer ne suffit pas : il faut l'associer avec PUT /api/v1/catalog/assistants/{assistantApiKey}/knowledge.

Regles operationnelles :

  • triggers peut etre omis ou vide : la knowledge repond alors toujours avec defaultResponse
  • un declencheur sans specificResponse retombe sur le defaultResponse de la knowledge
  • un declencheur sans postAction retombe sur le defaultPostAction de la knowledge
  • aiInstructions guide la facon dont le modele utilise la reponse, sans reecrire la reponse
  • sortOrder est optionnel : s'il est omis, l'ordre du tableau est utilise

Corps·

obligatoire
application/json

Creation d'une knowledge.

triggers peut etre omis ou vide : la knowledge repond alors toujours avec defaultResponse.

  • defaultResponse
    Type: string
    longueur min.:  
    1
    obligatoire

    Réponse par défaut utilisée lorsqu'un déclencheur n'a pas de réponse spécifique.

  • title
    Type: string
    longueur max.:  
    255
    obligatoire

    Titre lisible de la nouvelle knowledge.

  • defaultPostAction
    Type: string
    longueur max.:  
    50

    Vaut ask_if_needs_more s'il est omis

  • rules
    Type: string | null

    Contraintes facultatives appliquées à l'ensemble de la knowledge.

  • triggers
    Type:

    Liste initiale des déclencheurs de la knowledge.

    Propriétés : 5

Réponses

  • 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": "Horaires et sites",
  "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": "Horaires et sites",
      "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 creee

Recupere une seule knowledge

​

Renvoie une seule knowledge complete avec ses declencheurs. Vaut pour les knowledge du client et pour celles partagees.

Paramètres de chemin

  • knowledgeId
    Type: integer
    min.:  
    1
    obligatoire

    Id de la knowledge

Réponses

  • 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": "Horaires et sites",
      "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 trouvee

Met a jour une knowledge

​

Met a jour une knowledge avec une semantique PATCH merge.

Regles operationnelles :

  • au moins un champ doit etre present, les champs omis conservent la valeur actuelle
  • triggers, s'il est present, remplace toute la liste : l'envoyer complet, ou l'omettre pour laisser les declencheurs inchanges. Envoyer [] les supprime tous
  • les knowledge fournies par AI4CALL (isShared: true) ne sont pas modifiables et renvoient 404

Les modifications prennent effet sur chaque assistant auquel la knowledge est associee, sans la reassocier.

Paramètres de chemin

  • knowledgeId
    Type: integer
    min.:  
    1
    obligatoire

    Id de la knowledge

Corps·

obligatoire
application/json

PATCH merge d'une knowledge.

Regles operationnelles :

  • au moins un champ doit etre present
  • les champs omis conservent la valeur actuelle
  • triggers, s'il est present, remplace toute la liste : l'envoyer complet, ou l'omettre pour laisser les declencheurs inchanges. Envoyer [] les supprime tous
  • les knowledge avec isShared: true ne sont pas modifiables
  • defaultPostAction
    Type: string
    longueur max.:  
    50

    Nouvelle action postérieure par défaut pour les déclencheurs qui n'en définissent pas.

  • defaultResponse
    Type: string
    longueur min.:  
    1

    Nouvelle réponse par défaut de la knowledge.

  • rules
    Type: string | null

    Nouvelles contraintes facultatives de la knowledge.

  • title
    Type: string
    longueur max.:  
    255

    Nouveau titre de la knowledge.

  • triggers
    Type:

    Liste complète de remplacement des déclencheurs lorsque ce champ est fourni.

    Propriétés : 5

Réponses

  • 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": "Horaires et sites",
      "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 mise a jour

Supprime une knowledge

​

Supprime definitivement la knowledge, ses declencheurs et toutes ses associations avec les assistants du client. Les assistants concernes cessent simplement de la porter dans leur prompt.

Les knowledge fournies par AI4CALL ne sont pas supprimables et renvoient 404.

Paramètres de chemin

  • knowledgeId
    Type: integer
    min.:  
    1
    obligatoire

    Id de la knowledge

Réponses

  • 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 supprimee

Liste les knowledge associees a un assistant

​

Renvoie les knowledge inserees dans le prompt de cet assistant, dans l'ordre ou elles sont appliquees, avec leur contenu complet, ainsi un second appel n'est pas necessaire.

Une association pointant vers une knowledge supprimee est ecartee de la reponse.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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": "Horaires et sites",
        "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 associees

Definit les knowledge associees a un assistant

​

Remplace entierement les associations de l'assistant : ce que vous envoyez devient la liste complete.

Deux formes acceptees :

  • associations, quand l'ordre compte et que vous voulez le declarer
  • knowledgeIds, quand l'ordre du tableau suffit

Elles sont exclusives. Une liste vide detache toutes les knowledge.

On peut associer aussi bien ses propres knowledge que celles partagees ; un id qui n'est ni le votre ni partage fait echouer tout l'appel avec 400, sans modification partielle.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

Remplace entierement les associations knowledge de l'assistant.

Envoyer associations quand l'ordre compte, knowledgeIds quand l'ordre du tableau suffit. Les deux formes sont exclusives ; une liste vide detache tout.

On peut associer aussi bien ses propres knowledge que celles partagees.

  • associations
    Type: array of object

    Valeur à envoyer pour associations dans la requête AssistantKnowledgeAssociationsRequest.

    Propriétés : 2
  • knowledgeIds
    Type: array of integer

    Valeur à envoyer pour knowledgeIds dans la requête AssistantKnowledgeAssociationsRequest.

Réponses

  • 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": "Horaires et sites",
        "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"
      }
    ]
  }
}

Associations mises a jour

Filler Phrase Lists

​

Listes de phrases de remplissage réutilisables canoniques et associations aux assistants

Filler Phrase Lists Opérations

Répertorier les listes de remplissage du client

​

Répertorier les listes de remplissage du client

Paramètres de requête

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximal d'éléments renvoyés dans une page paginée par curseur. Omettez limit et cursor pour conserver la réponse historique non paginée.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor par la page précédente.

Réponses

  • 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"
      }
    ]
  }
}

Listes de remplissage disponibles

Créer une liste de remplissage

​

Créer une liste de remplissage

Corps·

obligatoire
application/json
  • id
    Type: string
    longueur max.:  
    100
    obligatoire

    Valeur à envoyer pour id dans la requête FillerPhraseListCreateRequest.

  • name
    Type: string
    longueur max.:  
    255
    obligatoire

    Valeur à envoyer pour name dans la requête FillerPhraseListCreateRequest.

  • phrases
    Type: array of string

    Valeur à envoyer pour phrases dans la requête FillerPhraseListCreateRequest.

Réponses

  • 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"
    }
  }
}

Liste de remplissage créée

Mettre à jour une liste de remplissage

​

Mettre à jour une liste de remplissage

Paramètres de chemin

  • listId
    Type: string
    obligatoire

Corps·

obligatoire
application/json
  • name
    Type: string
    longueur max.:  
    255
    obligatoire

    Valeur à envoyer pour name dans la requête FillerPhraseListUpdateRequest.

  • phrases
    Type: array of string

    Valeur à envoyer pour phrases dans la requête FillerPhraseListUpdateRequest.

Réponses

  • 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"
    }
  }
}

Liste de remplissage mise à jour

Supprimer une liste de remplissage

​

Supprimer une liste de remplissage

Paramètres de chemin

  • listId
    Type: string
    obligatoire

Réponses

  • 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
  }
}

Liste de remplissage supprimée

Récupérer une liste de remplissage

​

Récupère une liste de phrases de remplissage appartenant au client authentifié.

Paramètres de chemin

  • listId
    Type: string
    obligatoire

Réponses

  • 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"
    }
  }
}

Liste de remplissage trouvée

Récupère les listes de remplissage associées à l'assistant

​

Récupère les listes de remplissage associées à l'assistant

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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"
      ]
    }
  }
}

Associations de listes de remplissage

Sauvegarder les listes de remplissage associées à l'assistant

​

Sauvegarder les listes de remplissage associées à l'assistant

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

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

Réponses

  • 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"
      ]
    }
  }
}

Associations de listes de remplissage enregistrées

RAG

​

Gestion canonique des collections RAG du client et de leurs documents

RAG Opérations

Répertorie toutes les collections RAG des clients

​

Renvoie toutes les collections RAG disponibles pour le client authentifié.

Utilisez cette réponse pour remplir name dans le PATCH /api/v1/assistants/{assistantApiKey}/runtime/rag.

Paramètres de requête

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximal d'éléments renvoyés dans une page paginée par curseur. Omettez limit et cursor pour conserver la réponse historique non paginée.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor par la page précédente.

Réponses

  • 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": "Collection de démonstrations de documentation produit",
        "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": "Collection pas encore rattachée à un assistant",
        "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"
      }
    ]
  }
}

Liste complète des collections RAG du client, même celles non associées à un assistant

Créer une collection RAG

​

Crée une collection RAG appartenant au client et provisionne sa collection dans le magasin vectoriel.

Corps·

obligatoire
application/json

Crée une collection RAG appartenant au client et provisionne la collection correspondante dans le magasin vectoriel.

  • name
    Type: string
    longueur min.:  
    1
    obligatoire

    Valeur à envoyer pour name dans la requête RagCollectionCreateRequest.

  • description
    Type: string | null

    Valeur à envoyer pour description dans la requête RagCollectionCreateRequest.

  • maxChunkSize
    Type: integer
    min.:  
    500
    max.:  
    10000

    Valeur à envoyer pour maxChunkSize dans la requête RagCollectionCreateRequest.

  • maxChunksPerFile
    Type: integer | null
    min.:  
    1

    Valeur à envoyer pour maxChunksPerFile dans la requête RagCollectionCreateRequest.

Réponses

  • 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": "Documentation produit",
  "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": "Documentation produit",
      "collectionName": "collection_clNe_abC1234",
      "isActive": true,
      "maxChunkSize": 5000,
      "maxChunksPerFile": null,
      "createdAt": "2026-09-28T10:30:00.000Z",
      "updatedAt": "2026-09-28T10:30:00.000Z"
    }
  }
}

Collection RAG créée

Supprimer une collection RAG

​

Supprime une collection RAG du client inutilisée et les métadonnées de documents stockées.

Paramètres de chemin

  • ragId
    Type: string
    obligatoire

    publicRagId stable de la collection RAG. Les valeurs historiques collectionName et name restent acceptées.

Réponses

  • 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
  }
}

Collection RAG supprimée

Estimez le jeton et le coût des fichiers RAG avant de les télécharger

​

Estimez le jeton et le coût des fichiers à télécharger, en utilisant le même calcul indiqué depuis le portail avant de confirmer le téléchargement.

Soumettez les fichiers sous la forme multipart/form-data dans le champ répétable files.

Corps

obligatoire
application/json

Réponses

  • 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
    }
  }
}

Télécharger l'estimation du jeton

Récupérer le statut d'un téléchargement RAG

​

Utilisez uploadId renvoyé par le POST de téléchargement pour suivre l'état du vectorisation, comme dans le portail.

Paramètres de chemin

  • uploadId
    Type: string
    obligatoire

Réponses

  • 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
    }
  }
}

État de téléchargement actuel

Répertorie les fichiers chargés dans une collection RAG

​

Récupère les fichiers de la collection RAG du client authentifié.

ragId est le publicRagId stable renvoyé par la liste des collections. Les valeurs historiques collectionName et name restent acceptées.

Paramètres de chemin

  • ragId
    Type: string
    obligatoire

    publicRagId stable de la collection RAG. Les valeurs historiques collectionName et name restent acceptées.

Paramètres de requête

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximal d'éléments renvoyés dans une page paginée par curseur. Omettez limit et cursor pour conserver la réponse historique non paginée.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor par la page précédente.

Réponses

  • 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"
      }
    ]
  }
}

Fichiers présents dans la collection RAG

Charger des fichiers dans une collection RAG

​

Charge un ou plusieurs fichiers dans la collection RAG, démarre la vectorisation sur Chroma et enregistre le détail du fichier afin de le rendre visible dans les GET suivantes.

Envoyez les fichiers en multipart/form-data dans le champ répétable files. ragId est le publicRagId stable renvoyé par la liste des collections. Les valeurs historiques collectionName et name restent acceptées.

Paramètres de chemin

  • ragId
    Type: string
    obligatoire

    publicRagId stable de la collection RAG. Les valeurs historiques collectionName et name restent acceptées.

Corps

obligatoire
application/json

Réponses

  • 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"
    }
  }
}

Téléchargement accepté et métadonnées du fichier enregistrées

Supprimer un fichier d'une collection RAG

​

Supprime le document du magasin vectoriel Chroma et retire le détail du fichier de la liste de la collection.

ragId est le publicRagId stable renvoyé par la liste des collections. Les valeurs historiques collectionName et name restent acceptées.

Paramètres de chemin

  • ragId
    Type: string
    obligatoire

    publicRagId stable de la collection RAG. Les valeurs historiques collectionName et name restent acceptées.

  • fileName
    Type: string
    obligatoire

    Nom du fichier à supprimer, extrait de data.documents[].fileName.

Réponses

  • 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"
    }
  }
}

Fichier supprimé de la collection RAG

Renvoie la configuration RAG actuelle d'un assistant spécifique

​

Renvoie l’état RAG d’exécution de l’assistant.

Si enabled est true, utilisez le champ name dans cette réponse pour remplir le PATCH /api/v1/assistants/{assistantApiKey}/runtime/rag quand vous souhaitez conserver, remplacer ou désactiver la collection actuelle.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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"
}

Configuration RAG d'exécution de l'assistant

Catalog Tools

​

Outils d'exécution disponibles côté client et outils associés à l'assistant

Catalog Tools Opérations

Mettre à jour les liaisons de l'outil Assistant

​

Met à jour les associations d’outils d’assistant avec la sémantique PATCH merge, répliquant le comportement du portail.

Paramètres modifiables :

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

La charge utile recommandée est celle de haut niveau par nom :

  • tools : liste des { toolName, subscriptionName } à ajouter
  • deleteTools : liste des { toolName, subscriptionName } à supprimer
  • si vous ajoutez un custom_tool, utilisez toolName = toolName et subscriptionName = null
  • si vous ajoutez ou supprimez un plugin_tool, utilisez toolName = toolName et subscriptionName = instanceName
  • si vous ajoutez ou supprimez un custom_mcp_tool, utilisez toolName = toolName et subscriptionName = instanceName

Comment récupérer les valeurs :

  • pour ajouter des pièces d'outils de GET /api/v1/catalog/tools
  • pour retirer les pièces d'outils de GET /api/v1/catalog/assistants/{assistantApiKey}/tools
  • réutilisez toujours toolName comme toolName
  • réutilisez toujours instanceName comme subscriptionName pour les cibles MCP
  • si instanceName et null, l'outil est un custom_tool classique et doit être envoyé avec subscriptionName: null

La charge utile de bas niveau du portail (toolIds + mcpToolsBySubscription) reste prise en charge pour une compatibilité améliorée. Sur les assistants voice_to_voice, les outils HTTP sont écrits en endpointTools et les outils MCP dans mcpServers dans la racine JSON voice-llm.

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

Charge utile de mise à jour de l’association d’outils.

Vous pouvez mettre à jour uniquement les outils classiques, uniquement les outils MCP, ou les deux au cours du même appel. Si vous utilisez la forme par nom, les valeurs doivent toujours provenir des catalogues GET documentés ci-dessus.

Réponses

  • 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
    }
  }
}

Associations d'outils mises à jour

Répertorie tous les outils d'exécution client disponibles

​

Renvoie le catalogue complet des outils que le client peut associer à un assistant.

Utilisez cette réponse pour compiler tools en PATCH /api/v1/assistants/{assistantApiKey}/runtime/tools :

  • réutiliser toolName comme toolName
  • si toolType et custom_tool, envoyer subscriptionName: null
  • si toolType et plugin_tool, envoyer subscriptionName égal à instanceName
  • si toolType et custom_mcp_tool, envoyer subscriptionName égal à instanceName

Paramètres de requête

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximal d'éléments renvoyés dans une page paginée par curseur. Omettez limit et cursor pour conserver la réponse historique non paginée.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor par la page précédente.

Réponses

  • 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": "Rechercher un lead dans le CRM de l'entreprise",
        "parameters": null,
        "method": "POST",
        "endpoint": "https://crm.example.com/api/search"
      },
      {
        "toolType": "plugin_tool",
        "toolName": "list_workflows",
        "instanceName": "Marketing",
        "pluginName": "n8n",
        "description": "Répertorie les flux de travail disponibles",
        "parameters": {
          "type": "object"
        },
        "method": null,
        "endpoint": null
      },
      {
        "toolType": "plugin_tool",
        "toolName": "execute_workflow",
        "instanceName": "Marketing",
        "pluginName": "n8n",
        "description": "Exécute un workflow n8n",
        "parameters": {
          "type": "object"
        },
        "method": null,
        "endpoint": null
      },
      {
        "toolType": "custom_mcp_tool",
        "toolName": "search_contact",
        "instanceName": "CRM Custom",
        "pluginName": "CRM Custom",
        "description": "Rechercher un contact dans le CRM",
        "parameters": {
          "type": "object"
        },
        "method": null,
        "endpoint": null
      }
    ]
  }
}

Liste unifiée d'outils de plug-in, d'outils MCP personnalisés et d'outils personnalisés sans assistantApiKey en entrée

Répertorie les outils d'exécution associés à l'assistant

​

Renvoie les outils actuellement associés à l'assistant.

Utilisez cette réponse pour compiler deleteTools en PATCH /api/v1/assistants/{assistantApiKey}/runtime/tools :

  • réutiliser toolName comme toolName
  • si toolType et custom_tool, envoyer subscriptionName: null
  • si toolType et plugin_tool, envoyer subscriptionName égal à instanceName
  • si toolType et custom_mcp_tool, envoyer subscriptionName égal à instanceName

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Réponses

  • 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": "Rechercher un lead dans le CRM de l'entreprise",
        "parameters": null,
        "method": "POST",
        "endpoint": "https://crm.example.com/api/search"
      },
      {
        "toolType": "plugin_tool",
        "toolName": "execute_workflow",
        "instanceName": "Marketing",
        "pluginName": "n8n",
        "description": "Exécute un workflow n8n",
        "parameters": {
          "type": "object"
        },
        "method": null,
        "endpoint": null
      },
      {
        "toolType": "custom_mcp_tool",
        "toolName": "search_contact",
        "instanceName": "CRM Custom",
        "pluginName": "CRM Custom",
        "description": "Rechercher un contact dans le CRM",
        "parameters": {
          "type": "object"
        },
        "method": null,
        "endpoint": null
      }
    ]
  }
}

Liste unifiée des outils de plug-in, des outils MCP personnalisés et des outils personnalisés associés à l'assistant

Catalog RAG

​

Alias historiques du catalogue pour les collections RAG du client et des assistants. Conservés uniquement pour la compatibilité v1.

Catalog RAG Opérations

Mettre à jour la configuration d'exécution RAG de l'assistant

​

Mettez à jour la configuration RAG de l'assistant avec la sémantique PATCH merge, alignée sur le portail.

Paramètres modifiables :

  • enabled
  • name
  • returnedChunks
  • kbPrompt

Comment récupérer des données :

  • utilisez GET /api/v1/catalog/rag/collections pour obtenir les collections RAG disponibles
  • réutiliser name de la collection comme name

Règles de fonctionnement :

  • enabled: true active RAG et nécessite une collection valide
  • enabled: false supprime la base de connaissances RAG de l'assistant
  • returnedChunks reproduit le paramètre du portail
  • kbPrompt met à jour les instructions de la base de connaissances de l'assistant
  • les champs omis conservent la valeur actuelle, s'ils sont présents
  • sur les assistants voice_to_voice le backend met à jour knowledgeBases dans la racine JSON voice-llm

Paramètres de chemin

  • assistantId
    Type: string
    longueur min.:  
    1
    longueur max.:  
    128
    obligatoire

    Identifiant public de l'assistant. L'actuel assistantId numérique est canonique ; la valeur historique assistantApiKey reste acceptée pendant la période de compatibilité v1.

Corps·

obligatoire
application/json

Fusion PATCH de la configuration RAG de l'assistant, alignée sur le comportement du portail.

Règles de fonctionnement :

  • au moins un des enabled, name, returnedChunks, kbPrompt doit être présent
  • utilisez GET /api/v1/catalog/rag/collections pour récupérer le name
  • enabled: true nécessite une collection valide et active
  • en envoyant name avec une collection valide, le RAG est activé s'il n'est pas explicitement désactivé
  • enabled: false supprime la base de connaissances RAG de l'assistant et nettoie returnedChunks et kbPrompt
  • returnedChunks suit le paramètre du portail et doit être compris entre 1 et 10
  • kbPrompt: null supprime les instructions de la base de connaissances de l'assistant
  • les champs omis conservent la valeur actuelle, s'ils sont déjà présents
  • enabled
    Type: boolean

    Activez ou désactivez RAG pour l'assistant. Si false, la base de connaissances RAG est supprimée.

  • kbPrompt
    Type: string | null

    Instructions de la base de connaissances de l'assistant. Si null, le champ est supprimé du runtime LLM.

  • name
    Type: string | null

    Nom de la collection RAG à associer. Il doit être récupéré à partir de GET /api/v1/catalog/rag/collections. Si null, la sélection est réinitialisée.

  • returnedChunks
    Type: integer
    min.:  
    1
    max.:  
    10

    Nombre de fragments pertinents à renvoyer depuis la base de connaissances.

Réponses

  • 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
    }
  }
}

Configuration d'exécution RAG mise à jour

Account Analytics

​

Historique des appels, recharges, RAG, SMS et réponses outils du client authentifié

Account Analytics Opérations

Récupère l'historique des appels entrants du client authentifié

​

Renvoie les appels entrants du client avec les détails des coûts et des jetons pour chaque session.

Filtres disponibles :

  • startDate et endDate filtrer par date de création (createdAt)
  • les deux sont facultatifs ; en cas d'omission, le backend renvoie tout l'historique disponible

Comment lire les coûts :

  • tous les coûts sont en EUR
  • totalCost = llmInputCost + llmOutputCost + ttsCost + asrCost + ragCost + trafficCost + trafficCostOutbound

Paramètres de requête

  • startDate
    Type: stringFormat: date

    Date de début du filtre (AAAA-MM-JJ, inclus)

  • endDate
    Type: stringFormat: date

    Date de fin du filtre (AAAA-MM-JJ, inclus)

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximum d'enregistrements. En cas d'omission avec cursor, conserve le comportement non paginé hérité.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor pour lire la page suivante.

Réponses

  • 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
  }
}

Historique des appels entrants

Récupère l'historique des appels sortants du client authentifié

​

Renvoie les appels sortants du client avec le détail des coûts de trafic pour chaque session.

Filtres disponibles :

  • Filtre startDate et endDate par date de création (createdAt)
  • internalId filtre un seul appel sortant en utilisant l'identifiant interne généré par AI4Call
  • le filtre client authentifié est toujours appliqué, même lorsque internalId est présent
  • si internalId est omis, le backend renvoie l'historique disponible du client authentifié

Paramètres de requête

  • internalId
    Type: Format: uuid

    Filtre par l'UUID outbound généré par AI4Call.

    UUID généré par AI4Call pour corréler la demande outbound, le callback et la recherche de l'état final d'appel.

  • internal_id
    Type: Format: uuid
    obsolète

    Alias ​​hérité de internalId.

    UUID généré par AI4Call pour corréler la demande outbound, le callback et la recherche de l'état final d'appel.

  • startDate
    Type: stringFormat: date

    Date de début du filtre (AAAA-MM-JJ, inclus)

  • endDate
    Type: stringFormat: date

    Date de fin du filtre (AAAA-MM-JJ, inclus)

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximum d'enregistrements. En cas d'omission avec cursor, conserve le comportement non paginé hérité.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor pour lire la page suivante.

Réponses

  • 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
  }
}

Historique des appels sortants

Récupère l'historique des appels MCP Pre-Call du client authentifié

​

Renvoie les appels MCP Pre-Call du client avec les détails du jeton et les coûts LLM pour chaque demande.

Le Pre-Call MCP effectue des validations numériques et des configurations MCP avant que l'appel ne soit acheminé vers l'assistant.

Filtres disponibles :

  • startDate et endDate filtrer par date de création (createdAt)
  • les deux sont facultatifs ; en cas d'omission, le backend renvoie tout l'historique disponible

Paramètres de requête

  • startDate
    Type: stringFormat: date

    Date de début du filtre (AAAA-MM-JJ, inclus)

  • endDate
    Type: stringFormat: date

    Date de fin du filtre (AAAA-MM-JJ, inclus)

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximum d'enregistrements. En cas d'omission avec cursor, conserve le comportement non paginé hérité.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor pour lire la page suivante.

Réponses

  • 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
  }
}

Historique des appels pré-appel MCP

Récupère l'historique des appels MCP post-appel du client authentifié

​

Renvoie les appels MCP post-appel du client avec les détails du jeton et les coûts LLM pour chaque demande.

Le MCP post-appel exécute des outils et des automatisations après la clôture de l'appel, en utilisant le contexte de la conversation conclue.

Filtres disponibles :

  • Filtre startDate et endDate par date de création (createdAt)
  • les deux sont facultatifs ; en cas d'omission, le backend renvoie tout l'historique disponible

Paramètres de requête

  • startDate
    Type: stringFormat: date

    Date de début du filtre (AAAA-MM-JJ, inclus)

  • endDate
    Type: stringFormat: date

    Date de fin du filtre (AAAA-MM-JJ, inclus)

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximum d'enregistrements. En cas d'omission avec cursor, conserve le comportement non paginé hérité.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor pour lire la page suivante.

Réponses

  • 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
  }
}

Historique des appels MCP post-appel

Récupérer l'historique des recharges du client authentifié

​

Renvoie les mouvements de recharge de crédit du client.

Filtres disponibles :

  • startDate et endDate filtrer par date de création (createdAt)
  • les deux sont facultatifs ; en cas d'omission, le backend renvoie tout l'historique disponible

Valeurs status :

  • completed — recharge terminée et crédit crédité
  • pending — transaction en attente de confirmation de la passerelle
  • failed — la transaction a échoué
  • cancelled — transaction annulée

Paramètres de requête

  • startDate
    Type: stringFormat: date

    Date de début du filtre (AAAA-MM-JJ, inclus)

  • endDate
    Type: stringFormat: date

    Date de fin du filtre (AAAA-MM-JJ, inclus)

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximum d'enregistrements. En cas d'omission avec cursor, conserve le comportement non paginé hérité.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor pour lire la page suivante.

Réponses

  • 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
  }
}

Historique des recharges

Récupère l’historique de consommation RAG du client authentifié

​

Renvoie le détail de la consommation d'intégration RAG du client, agrégée par collection.

Filtres disponibles :

  • startDate et endDate filtrer par date de création du relevé de consommation (createdAt)
  • les deux sont facultatifs ; en cas d'omission, le backend renvoie tout l'historique disponible

Comment lire les données :

  • totalToken — nombre total de jetons d'intégration traités pour cette collection au cours de la période
  • totalCost — coût total d'intégration en EUR pour cette collection dans la période
  • fileCount — nombre de dossiers indexés dans la collection au moment de l'enregistrement

Paramètres de requête

  • startDate
    Type: stringFormat: date

    Date de début du filtre (AAAA-MM-JJ, inclus)

  • endDate
    Type: stringFormat: date

    Date de fin du filtre (AAAA-MM-JJ, inclus)

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximum d'enregistrements. En cas d'omission avec cursor, conserve le comportement non paginé hérité.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor pour lire la page suivante.

Réponses

  • 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
  }
}

Historique de consommation du RAG

Recupere les recherches RAG facturees du client authentifie

​

Renvoie le detail des recherches RAG facturees au client, un enregistrement par recherche.

Different de /api/v1/account/analytics/rag, qui concerne le cout du chargement des documents dans les collections : cet endpoint concerne le cout de leur interrogation.

Filtres disponibles :

  • startDate et endDate filtrent par date de la recherche (createdAt)
  • les deux sont optionnels ; s'ils sont omis, le backend renvoie tout l'historique disponible

Comment lire les donnees :

  • queryTokens - tokens de la requete, la quantite sur laquelle la recherche est facturee
  • pricePerTokenNoVat - prix unitaire applique depuis la grille tarifaire du client
  • totalCost - montant facture, TVA incluse ; totalCostNoVat est le meme montant hors taxes
  • resultCount - chunks renvoyes, au maximum 10 par recherche

Si le client n'a jamais lance de recherche facturee, la liste est vide.

Paramètres de requête

  • startDate
    Type: stringFormat: date

    Date de début du filtre (AAAA-MM-JJ, inclus)

  • endDate
    Type: stringFormat: date

    Date de fin du filtre (AAAA-MM-JJ, inclus)

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximum d'enregistrements. En cas d'omission avec cursor, conserve le comportement non paginé hérité.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor pour lire la page suivante.

Réponses

  • 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
  }
}

Historique des recherches RAG facturees

Récupérer l'historique SMS du client authentifié

​

Renvoie les messages SMS envoyés par le client via les assistants.

Filtres disponibles :

  • startDate et endDate filtrer par date d'envoi (createdAt)
  • les deux sont facultatifs ; en cas d'omission, le backend renvoie tout l'historique disponible

Comment lire les données :

  • usageSms — nombre de SMS déduit du crédit SMS pour ce message (dépend de la longueur du texte)
  • alias — nom ou étiquette de l'assistant configuré pour le canal SMS

Paramètres de requête

  • startDate
    Type: stringFormat: date

    Date de début du filtre (AAAA-MM-JJ, inclus)

  • endDate
    Type: stringFormat: date

    Date de fin du filtre (AAAA-MM-JJ, inclus)

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximum d'enregistrements. En cas d'omission avec cursor, conserve le comportement non paginé hérité.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor pour lire la page suivante.

Réponses

  • 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
  }
}

Historique des SMS envoyés

Récupère l'historique des réponses de l'outil du client authentifié

​

Renvoie les réponses des outils invoqués par les assistants lors des appels.

Filtres disponibles :

  • startDate et endDate filtrer par date de création (createdAt)
  • les deux sont facultatifs ; en cas d'omission, le backend renvoie tout l'historique disponible

Comment lire les données :

  • toolName — nom de l'outil invoqué (correspond au name de l'outil configuré sur l'assistant)
  • toolCallId — identifiant unique de l'invocation généré par le LLM
  • callUuid — UUID de l'appel téléphonique à l'origine de l'invocation
  • toolResponse — charge utile de réponse renvoyée par l'outil ; la structure varie pour chaque outil

Paramètres de requête

  • startDate
    Type: stringFormat: date

    Date de début du filtre (AAAA-MM-JJ, inclus)

  • endDate
    Type: stringFormat: date

    Date de fin du filtre (AAAA-MM-JJ, inclus)

  • limit
    Type: integer
    min.:  
    1
    max.:  
    100

    Nombre maximum d'enregistrements. En cas d'omission avec cursor, conserve le comportement non paginé hérité.

  • cursor
    Type: string

    Curseur opaque renvoyé dans meta.nextCursor pour lire la page suivante.

Réponses

  • 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
  }
}

Outil d'historique des réponses

Public RAG

​

Recherche RAG publique via l'API de clé client

Public RAG Opérations

Rechercher des morceaux dans une collection RAG publique

​

Effectue une recherche vectorielle sur une collection RAG à l’aide de l’ID API public de la collection.

Le point de terminaison utilise le domaine dédié https://rag.ai4call.com et nécessite une clé API client généré par le portail AI4Call dans la section Sécurité -> Clé API.

Le champ rag_id est l'ID d'API public affiché dans l'interface utilisateur de gestion RAG, et non l'ID numérique. base de données interne. La recherche renvoie un maximum de 4 morceaux.

Corps·

obligatoire
application/json

Requête de recherche Public RAG acceptée par le service RAG dédié.

  • query
    Type: string
    obligatoire

    Texte à rechercher sémantiquement dans la collection RAG

  • rag_id
    Type: string
    obligatoire

    ID d'API public de la collection RAG affiché dans l'interface utilisateur du portail

Réponses

  • 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"
        }
      }
    ]
  }
}

Résultats de recherche RAG

Outbound

​

Webhook pour lancer des appels sortants avec le PBX client ou la ligne réseau AI4Call

Outbound Opérations

Appel sortant utilisant la configuration téléphonique du client

​

Lancez un appel sortant en utilisant la configuration téléphonique du client.

Deux modes sont disponibles :

  • Mode PBX IP (par défaut) : omettez method_uac ou définissez-le sur false, et fournissez ip_pbx et sip_port. ip_pbx doit être l'une des adresses IP publiques autorisées disponibles dans GESTIONE -> Abilita IP.
  • Mode UAC enregistré : définissez method_uac sur true et omettez ip_pbx et sip_port.

La clé API dans l'en-tête doit être générée par le portail dans la section SICUREZZA -> API key.

Corps·

obligatoire
application/json

Réponses

  • 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"
  }
}

Demande d'appel acceptée

Appel sortant avec la ligne réseau AI4Call

​

Lancez un appel sortant à l’aide des lignes réseau VoIP AI4Call. Ne nécessite pas de configuration PBX client.

callerId doit être une démo ou un numéro AI4Call acheté présent dans le compte. Vous pouvez voir les numéros de démonstration et achetés dans NUMERI AI4Call -> Routing.

La clé API dans l'en-tête doit être générée par le portail dans la section SICUREZZA -> API key.

Corps·

obligatoire
application/json

Réponses

  • 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"
  }
}

Demande d'appel acceptée

Récupérer l'état enregistré d'un appel outbound

​

Récupère le CDR outbound final à l'aide de l'internal_id reçu dans le callback de résultat.

Le callback peut arriver alors que duration vaut 0 ; les clients peuvent répéter cette requête jusqu'à ce que le CDR soit enregistré. La clé API doit appartenir au client qui a lancé l'appel outbound.

Paramètres de chemin

  • uuid
    Type: Format: uuid
    obligatoire

    Identifiant interne outbound reçu dans le callback.

    UUID généré par AI4Call pour corréler la demande outbound, le callback et la recherche de l'état final d'appel.

Réponses

  • 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"
}

État enregistré de l'appel outbound

Modèles

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