v1.2.0
OpenAPI 3.0.3

API de cliente AI4Call

AI4Call technical support
Proprietary
Términos del servicio

Contrato OpenAPI público para las API de AI4Call orientadas al cliente.

El servicio principal en https://client-api.ai4call.com cubre la gestión autenticada de la cuenta, los asistentes y su configuración de runtime, el monedero de proveedores, los recursos de catálogo, knowledge, la gestión de documentos RAG, las herramientas y las analíticas de la cuenta.

Flujo de autenticación actual de la Client API:

  1. POST /api/v1/auth/portal/login valida email y portalApiKey. No emite un token de acceso ni crea una sesión del servidor.
  2. Las llamadas de negocio aceptan Authorization: Bearer <portalApiKey> o el par legacy x-client-email y x-portal-api-key.
  3. Las operaciones sobre un asistente usan assistantId; los valores de ruta legacy assistantApiKey siguen aceptándose durante el periodo de compatibilidad v1.

Este documento también contiene operaciones alojadas en servicios dedicados. Las operaciones Public RAG usan su propia autenticación Bearer y las operaciones outbound su propio encabezado de API key; cada operación declara su servidor y esquema de seguridad dedicados.

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

Producción de clientes API

No se ha seleccionado ninguna autenticación
Bibliotecas cliente
Shell Curl

Health

​

Consultar disponibilidad del servicio API

Health Operaciones

Chequeo de salud del servicio.

​

Chequeo de salud del servicio.

Respuestas

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

Servicio activo

Auth

​

Autenticación del cliente del portal a través de correo electrónico y portalApiKey

Auth Operaciones

Autenticar a un cliente del portal con correo electrónico y portalApiKey

​

Valida las credenciales estáticas del portal y devuelve los datos del cliente. No emite tokens ni crea sesiones en el servidor.

Cuerpo·

obligatorio
application/json

Credenciales usadas para verificar un cliente del portal. La solicitud no crea una sesión ni emite un token de acceso.

  • email
    Tipo: stringFormato: email
    obligatorio

    Correo electrónico del cliente del portal.

  • portalApiKey
    Tipo: string
    longitud mín.:  
    10
    obligatorio

    Clave API estática del portal asociada a la cuenta del cliente.

Respuestas

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

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

Cliente autenticado

Account

​

Gestión de cuentas de clientes autenticados

Account Operaciones

Recuperar las IP permitidas de la cuenta autenticada

​

Recuperar las IP permitidas de la cuenta autenticada

Respuestas

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

Lista blanca de IP de la cuenta

Actualice las IP permitidas de la cuenta autenticada

​

Actualiza la lista blanca de IP de la cuenta con la semántica PATCH merge.

Parámetros editables:

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

Cómo recuperar datos actuales:

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

Reglas operativas:

  • allowedIps reemplaza la lista completa
  • addIps agrega nuevas IP o actualiza la descripción de las IP ya presentes
  • deleteIps elimina las IP indicadas
  • no combine allowedIps con addIps o deleteIps
  • allowedIps: [] borra completamente la lista
  • Después de la actualización de la base de datos, el backend también sincroniza inmediatamente el firewall

Cuerpo·

obligatorio
application/json

PATCH fusiona la configuración de IP permitida de la cuenta.

Reglas operativas:

  • allowedIps reemplaza completamente la lista actual
  • addIps agrega nuevas IP o actualiza la description de una IP ya existente
  • deleteIps elimina las IP indicadas
  • allowedIps no se puede combinar con addIps o deleteIps
  • allowedIps: [] elimina todas las IP
  • description: null o una cadena vacía elimina la descripción de IP
  • addIps
    Tipo:

    Valor que se debe enviar para addIps en la solicitud AccountAllowedIpsUpdateRequest.

    Propiedades: 2
  • allowedIps
    Tipo:

    Valor que se debe enviar para allowedIps en la solicitud AccountAllowedIpsUpdateRequest.

    Propiedades: 2
  • deleteIps
    Tipo: array of stringFormato: ipv4

    Valor que se debe enviar para deleteIps en la solicitud AccountAllowedIpsUpdateRequest.

Respuestas

  • 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": "Oficina central"
    },
    {
      "ip": "192.168.1.20",
      "description": "Casa"
    }
  ]
}'

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

Lista blanca de IP actualizada

Recupera los límites de llamadas de la cuenta autenticada.

​

Devuelve los límites de llamadas simultáneas a nivel de cuenta para todos los asistentes al cliente.

Cómo utilizar la respuesta:

  • utilizar assistants[].assistantApiKey en PATCH
  • configuredLimit y el valor guardado en el lado del inquilino
  • maxConcurrentCalls y el valor real mostrado en el portal
  • si configuredLimit y null, el backend usa defaultLimit

Respuestas

  • 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": "Atención al cliente",
          "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"
}

Límites de llamadas de la cuenta

Actualizar los límites de llamadas de la cuenta autenticada

​

Actualice los límites de llamadas simultáneas a nivel de cuenta con la semántica PATCH merge.

Parámetros editables:

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

Cómo recuperar datos:

  • utilizar GET /api/v1/account/call-limits
  • reutilizar assistants[].assistantApiKey

Reglas operativas:

  • cada elemento modifica solo el asistente indicado
  • maxConcurrentCalls: null elimina el límite configurado y el asistente vuelve a defaultLimit
  • si un asistente no está presente en la carga útil, su límite no cambia

Cuerpo·

obligatorio
application/json

PATCH fusiona los límites de llamadas simultáneas de la cuenta.

Reglas operativas:

  • assistants es obligatorio
  • cada elemento actualiza solo el asistente indicado
  • maxConcurrentCalls: null elimina el límite configurado para ese asistente
  • si no se envía un asistente, su límite actual no cambia
  • maxConcurrentCalls debe ser un número entero mayor o igual a 0
  • assistants
    Tipo:
    obligatorio

    Valor que se debe enviar para assistants en la solicitud AccountCallLimitsUpdateRequest.

    Propiedades: 2

Respuestas

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

Límites de llamadas actualizados

Recuperar los números de ruta de la cuenta autenticada

​

Devuelve los números de ruta a nivel de cuenta del portal:

  • assistants
  • demoNumbers
  • purchasedNumbers
  • userNumbers

Cómo utilizar la respuesta:

  • use assistants[].assistantApiKey en cargas útiles PATCH
  • use phoneNumber de las listas respectivas en las cargas útiles PATCH
  • assistantApiKey y assistantName dentro de cada número indican el asistente actualmente conectado

Respuestas

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

Números de cuenta de ruta

Actualice los números de ruta de la cuenta autenticada

​

Actualice el enrutamiento de números a nivel de cuenta con la semántica PATCH merge.

Parámetros editables:

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

Cómo recuperar datos:

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

Reglas operativas:

  • cada artículo modifica sólo el número indicado
  • assistantApiKey: null libera el número
  • si el número ya estaba asociado a otro asistente, se mueve al nuevo
  • para números de demostración, al asignar un asistente a un número de demostración, se libera cualquier otra demostración que ya esté conectada a ese asistente
  • los campos omitidos no se modifican

Cuerpo·

obligatorio
application/json

Combinación de PATCH de enrutamiento de números de cuenta.

Reglas operativas:

  • al menos uno de demoNumbers, purchasedNumbers, userNumbers debe estar presente
  • cada artículo actualiza solo el número indicado
  • assistantApiKey: null libera el número
  • assistantApiKey: "..." conecta o mueve el número a ese asistente
  • si un número estaba conectado a otro asistente, se descarta y se vuelve a conectar al nuevo
  • para los números de demostración, si el asistente de destino ya tenía otro número de demostración, se libera el anterior
  • los campos omitidos no se modifican
  • demoNumbers
    Tipo:

    Valor que se debe enviar para demoNumbers en la solicitud AccountNumberRoutingUpdateRequest.

    Propiedades: 2
  • purchasedNumbers
    Tipo:

    Valor que se debe enviar para purchasedNumbers en la solicitud AccountNumberRoutingUpdateRequest.

    Propiedades: 2
  • userNumbers
    Tipo:

    Valor que se debe enviar para userNumbers en la solicitud AccountNumberRoutingUpdateRequest.

    Propiedades: 2

Respuestas

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

Ruta numérica actualizada

Recupera todos los complementos adquiribles de la cuenta autenticada

​

Devuelve los complementos que se pueden comprar para el cliente autenticado según su lista de precios.

Cómo utilizar los datos:

  • reutilizar directamente pluginName en el PATCH PATCH /api/v1/account/plugins/purchase
  • no se necesitan ID de complemento

Respuestas

  • 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": "Integración con Hojas de cálculo de Google",
          "category": "data_integrations",
          "pluginType": "paid",
          "purchasePrice": 9.9,
          "monthlyPrice": 4.9,
          "priceListName": "Standard",
          "activeInstanceCount": 1
        }
      ]
    }
  },
  "meta": {
    "count": 1
  }
}

Lista de complementos adquiribles

Recupera todas las instancias de complementos activos comprados por la cuenta autenticada

​

Devuelve las instancias de plugin activas del cliente autenticado.

Uso canónico:

  • usa el instanceId estable con PATCH /api/v1/account/plugins/instances/{instanceId}
  • usa el mismo instanceId con DELETE /api/v1/account/plugins/instances/{instanceId}

El PATCH legacy basado en nombres sigue disponible por compatibilidad.

Parámetros de consulta

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de elementos devueltos en una página con paginación por cursor. Omite limit y cursor para conservar la respuesta legacy sin paginar.

  • cursor
    Tipo: string

    Cursor opaco devuelto en meta.nextCursor por la página anterior.

Respuestas

  • 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": "Integración con Hojas de cálculo de Google",
          "category": "data_integrations",
          "instanceName": "Sheets Produzione",
          "instanceIndex": 1,
          "status": "active",
          "activationDate": "2026-04-24T10:30:00.000Z",
          "nextBillingDate": "2026-05-24T10:30:00.000Z",
          "purchasePrice": 9.9,
          "monthlyPrice": 4.9,
          "instanceId": "1"
        }
      ]
    }
  },
  "meta": {
    "count": 1
  }
}

Lista de instancias de complementos activos comprados

Crear una instancia de plugin comprada

​

Compra un plugin y crea una nueva instancia de plugin de la cuenta. La respuesta expone el instanceId estable usado por las rutas canónicas de la instancia.

Cuerpo·

obligatorio
application/json

Compre un complemento utilizando el nombre del complemento devuelto por GET /api/v1/account/plugins/available.

Reglas operativas:

  • pluginName debe coincidir con el valor devuelto por el catálogo
  • instanceName y opcional
  • si instanceName no está presente, el backend genera automáticamente Istanza N
  • Los alias heredados de Snake_case siguen siendo aceptados pero están obsoletos.

Respuestas

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

Instancia de plugin creada correctamente

Renombrar una instancia de plugin comprada

​

Renombra una instancia de plugin activa mediante su instanceId estable.

Parámetros de ruta

  • instanceId
    Tipo: string
    obligatorio

    Identificador estable de la suscripción de plugin devuelto por la lista de instancias o la operación de creación.

Cuerpo·

obligatorio
application/json

Renombra una instancia de plugin comprada identificada por su instanceId estable.

Respuestas

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

Instancia de complemento actualizada

Cancelar una instancia de plugin comprada

​

Cancela una instancia de plugin activa mediante su instanceId estable.

Parámetros de ruta

  • instanceId
    Tipo: string
    obligatorio

    Identificador estable de la suscripción de plugin devuelto por la lista de instancias o la operación de creación.

Respuestas

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

Instancia de plugin cancelada

Recuperar la configuración de una instancia de plugin adquirida

​

Recupera la configuración de una instancia de plugin adquirida. Usa el instanceId estable devuelto por GET /api/v1/account/plugins/instances. La ruta legacy basada en el nombre sigue siendo compatible.

Parámetros de ruta

  • instanceId
    Tipo: string
    obligatorio

    Identificador estable de la instancia de plugin adquirida.

Respuestas

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

Configuración del plugin

Actualizar la configuración de una instancia de plugin adquirida

​

Actualiza la configuración mediante el instanceId estable. Los nombres del plugin y de la instancia se resuelven en el servidor, por lo que los clientes solo envían los campos de configuración que se fusionarán.

Parámetros de ruta

  • instanceId
    Tipo: string
    obligatorio

    Identificador estable de la instancia de plugin adquirida.

Cuerpo·

obligatorio
application/json

Cuerpo PATCH de configuración dirigido mediante un instanceId estable del plugin.

  • configuration
    Tipo: object
    obligatorio

    Campos específicos del plugin que se fusionarán con la configuración guardada.

    Propiedades: 1

Respuestas

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

Configuración del complemento actualizada

Assistants

​

Gestión de asistentes de cliente autenticados

Assistants Operaciones

Enumera los asistentes del cliente autenticado.

​

Enumera los asistentes del cliente autenticado.

Parámetros de consulta

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de elementos devueltos en una página con paginación por cursor. Omite limit y cursor para conservar la respuesta legacy sin paginar.

  • cursor
    Tipo: string

    Cursor opaco devuelto en meta.nextCursor por la página anterior.

Respuestas

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

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

Lista de asistentes

Cree un nuevo asistente preinicializado para el cliente autenticado

​

Crea el asistente replicando la misma lógica usada por el portal AI4Call.

Para un asistente clásico solo se requieren name y description. Para un asistente audio-a-audio envía mode: audio_to_audio y, si quieres sobrescribir los valores predeterminados, el bloque canónico audioToAudio. El modo legacy voice_to_voice y el campo voiceToVoice siguen aceptándose por compatibilidad.

El backend realiza automáticamente:

  • generación de assistantApiKey en formato ai4call_sk_*
  • asignación progresiva de jsonFilename en formato FLLM*.json
  • generación del virtualNumber demo en formato 0000********
  • inicialización del JSON de runtime con los valores predeterminados del portal
  • trigger de provisioning backend
  • intento best-effort de registrar el asistente en el tenant MCP

Valores iniciales:

  • TTS tts_live_azure_multi con voz it-IT-ElsaNeural
  • ASR asr_azure_multi
  • LLM openai con modelo gpt-4o
  • primer mensaje no configurado (firstMessage.text vacío)
  • prompt inicial preconfigurado
  • estado inicial draft

Si mode es audio_to_audio, el backend inicializa un JSON configType: voice-llm con raíz audio-a-audio compatible con el portal.

Cuerpo·

obligatorio
application/json

Carga útil mínima de creación. El backend replica la lógica del portal: genera assistantApiKey, virtualNumber y jsonFilename, inicializa el JSON en tiempo de ejecución con los valores predeterminados de AI4Call y comienza a aprovisionar el asistente. El nombre del asistente se normaliza reemplazando los espacios con _.

  • description
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    500
    obligatorio

    Descripción funcional del asistente.

  • name
    Tipo: string
    longitud mín.:  
    3
    longitud máx.:  
    100
    obligatorio

    Nombre del asistente. Si contiene espacios, el backend los convierte automáticamente a _.

  • audioToAudio
    Tipo:
    obsoleto

    Configuración audio-a-audio inicial, usada cuando corresponde al modo seleccionado.

    Propiedades: 6
  • mode
    Tipo: enum

    Modo de runtime que se usará al crear el asistente.

    valores
    textaudio_to_audiovoice_to_voice
  • voiceToVoice
    Tipo:
    obsoleto

    Alias legacy de audioToAudio.

    Propiedades: 6

Respuestas

  • 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": "Asistente demo para campañas comerciales inbound.",
  "mode": "text"
}'

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

Asistente creado

Recupera un asistente autenticado específico del cliente

​

Recupera un asistente autenticado específico del cliente

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

Asistente encontrado

Actualizar metadatos, estado y configuración básica del asistente.

​

Actualiza los campos generales del asistente.

Para asistentes text, el bloque firstMessage actualiza el primer mensaje estático con semántica PATCH merge. Envía firstMessage.text: null o firstMessage.text: "" para eliminarlo.

Para asistentes audio-a-audio, el bloque canónico audioToAudio actualiza el JSON voice-llm con semántica PATCH merge. El campo legacy voiceToVoice sigue aceptándose por compatibilidad.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

Payload PATCH usado para actualizar los campos editables del asistente.

  • audioToAudio
    Tipo:
    obsoleto

    Actualización parcial de la configuración audio-a-audio.

    Propiedades: 6
  • description
    Tipo: string | null
    longitud máx.:  
    500

    Nueva descripción funcional; null elimina la descripción actual.

  • firstMessage
    Tipo:

    Actualización parcial de la configuración del primer mensaje del asistente.

    Propiedades: 3
  • metadata
    Tipo: object

    Metadatos libres que se almacenarán con el asistente.

    Propiedades: 1
  • name
    Tipo: string
    longitud mín.:  
    3
    longitud máx.:  
    100

    Si contiene espacios, el backend los convierte automáticamente a _.

  • network
    Tipo: object

    Configuración de red que se actualizará en el asistente.

    Propiedades: 1
  • numbers
    Tipo: object

    Valores de sustitución para las listas de números del asistente cuando se envían.

    Propiedades: 2
  • settings
    Tipo: object

    Configuración principal del asistente que se actualizará.

    Propiedades: 5
  • status
    Tipo: "draft" or "active" or "disabled"enum

    Nuevo estado del ciclo de vida del asistente.

  • voiceToVoice
    Tipo:
    obsoleto

    Alias legacy de audioToAudio.

    Propiedades: 6

Respuestas

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

Asistente actualizado

Eliminar un asistente

​

Elimina el asistente, libera sus números de teléfono asignados, elimina su JSON de runtime y actualiza el mapa de enrutamiento. La eliminación se rechaza mientras otro asistente de la misma cuenta use este asistente como destino de transferencia.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

Asistente eliminado

Actualiza los numeros enrutados al asistente

​

Actualiza el enrutamiento de los numeros del cliente a este asistente, con semantica PATCH merge entre las tres listas.

Parametros modificables:

  • demoNumbers
  • purchasedNumbers
  • userNumbers

Como recuperar los datos actuales:

  • usar GET /api/v1/catalog/assistants/{assistantApiKey}/number-routing para los numeros ya asignados y los que siguen libres en la cuenta

Reglas operativas:

  • al menos una de las tres listas debe estar presente
  • una lista omitida conserva el valor actual
  • una lista presente sustituye por completo la anterior: enviar [] para liberar todos los numeros de ese tipo
  • asignar un numero ya enrutado a otro asistente lo mueve a este

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

PATCH merge de los numeros enrutados al asistente.

Reglas operativas:

  • al menos uno entre demoNumbers, purchasedNumbers y userNumbers debe estar presente
  • las listas omitidas conservan el valor actual
  • cada lista sustituye por completo la anterior: para quitar todos los numeros de un tipo, enviar []
  • solo se pueden asignar numeros ya disponibles en la cuenta del cliente
  • un numero asignado a otro asistente se mueve a este
  • demoNumbers
    Tipo: array of string

    Numeros demo a enrutar a este asistente

  • purchasedNumbers
    Tipo: array of string

    Numeros comprados a enrutar a este asistente

  • userNumbers
    Tipo: array of string

    Numeros propios del cliente (centralita propia) a enrutar a este asistente

Respuestas

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

Enrutamiento actualizado

Lista los numeros del cliente con su estado de enrutamiento

​

Devuelve todos los numeros del cliente, divididos en demo, comprados y propios, cada uno con el asistente al que esta enrutado actualmente.

Usar antes de PATCH /api/v1/assistants/{assistantApiKey}/runtime/number-routing para saber que numeros estan libres y cuales ya estan asignados en otro sitio.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

  • 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 con su estado de enrutamiento

Assistant Prompt

​

Mensaje de asistente editable, primer mensaje y opciones relacionadas

Assistant Prompt Operaciones

Recuperar mensaje editable y configuración del primer mensaje del asistente

​

Devuelve la configuración rápida del asistente en el mismo modelo conceptual utilizado por el portal.

Lo que vuelve

  • prompt.text: solo la parte editable del mensaje
  • firstMessage.text: el primer mensaje estático, si está presente
  • firstMessage.callerSpeaksFirst: opción que indica si quien llama habla primero
  • firstMessage.uninterruptible: opción que indica si el primer mensaje no se puede interrumpir

Nota importante

Cualquier sección automática que ya esté presente en el JSON, como bloques del sistema o conocimiento, no se devuelve en prompt.text. En servidores voice_to_voice, prompt.text corresponde al campo raíz prompt del JSON voice-llm; el primer mensaje no se utiliza.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

Configuración rápida recuperada

Actualizar el mensaje editable y la configuración del primer mensaje del asistente

​

Actualice la configuración del mensaje del asistente con la semántica PATCH merge.

Parámetros editables:

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

Si actualiza el mensaje

  • Enviar prompt.text
  • El backend actualiza solo la parte editable
  • Todas las secciones automáticas ya presentes en el JSON, como sistema y conocimiento, permanecen conservadas.

Si actualizas el primer mensaje

  • Envía firstMessage.text para configurarlo o reemplazarlo.
  • Envía firstMessage.text: null o "" para eliminarlo.
  • Envíe firstMessage.callerSpeaksFirst: true si desea que la persona que llama hable primero
  • Si callerSpeaksFirst=true, el backend elimina el primer mensaje estático y fuerza uninterruptible=false.

Nota sobre la fusión

  • Los campos omitidos conservan su valor actual.
  • Puedes actualizar solo el aviso, solo el primer mensaje o ambos en la misma llamada
  • en los asistentes voice_to_voice, solo prompt.text se actualiza en la raíz JSON voice-llm; Los campos firstMessage son ignorados por el tiempo de ejecución de audio a audio.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

Carga útil de actualización del mensaje y del primer mensaje.

Utilice uno de los ejemplos siguientes dependiendo de lo que desee cambiar:

  • solo indicaciones
  • solo el primer mensaje
  • cambiar a callerSpeaksFirst

PATCH fusiona la configuración del mensaje del asistente.

Reglas operativas:

  • los campos omitidos conservan su valor actual
  • prompt.text actualiza solo la parte editable del mensaje
  • Se conservan todas las secciones automáticas ya presentes en el JSON, como sistema y conocimiento.
  • para eliminar el primer mensaje estático, envíe firstMessage.text: null o firstMessage.text: ""
  • si después de la fusión firstMessage.callerSpeaksFirst=true, el backend:
    • eliminar el primer mensaje estático
    • ir firstMessage.uninterruptible=false
  • firstMessage
    Tipo: object

    Valor que se debe enviar para firstMessage en la solicitud AssistantPromptUpdateRequest.

    Propiedades: 3
  • prompt
    Tipo: object

    Valor que se debe enviar para prompt en la solicitud AssistantPromptUpdateRequest.

    Propiedades: 1

Respuestas

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

Configuración de aviso actualizada

Provider Wallet

​

Credenciales de proveedor del cliente, reutilizables entre asistentes sin enviar claves en claro

Provider Wallet Operaciones

Lista los proveedores que aceptan credenciales propias

​

Devuelve el catalogo de proveedores que admite la cartera, cada uno con los campos exactos necesarios para guardar una credencial.

Leer antes de POST /api/v1/account/provider-wallet: serviceType, provider y engine del payload de creacion deben coincidir con una de estas entradas, y config solo acepta las claves listadas en sus fields.

ai4call: true indica un proveedor usable tambien a traves de la tarifa AI4CALL, sin credenciales propias; byok: true indica que acepta tus credenciales.

El catalogo es estatico y no depende del cliente autenticado.

Respuestas

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

Catalogo de los proveedores admitidos

Lista las credenciales guardadas en la cartera

​

Devuelve las credenciales del cliente, ordenadas por servicio y proveedor.

La configuracion nunca vuelve en claro: preview contiene los valores no secretos mas los secretos truncados a sus primeros caracteres, lo justo para distinguir dos credenciales.

El id de cada credencial es el valor a enviar como providerWalletId en los endpoints runtime del asistente, en lugar de poner una API key en el payload.

Parámetros de consulta

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de elementos devueltos en una página con paginación por cursor. Omite limit y cursor para conservar la respuesta legacy sin paginar.

  • cursor
    Tipo: string

    Cursor opaco devuelto en meta.nextCursor por la página anterior.

Respuestas

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

Credenciales guardadas

Guarda una nueva credencial en la cartera

​

Guarda una credencial de proveedor. El valor se cifra en reposo y nunca vuelve en claro.

Como construir el payload:

  • leer GET /api/v1/account/provider-wallet/catalog
  • copiar serviceType, provider y engine de la entrada elegida
  • rellenar config con las claves listadas en los fields de esa entrada

Reglas operativas:

  • config solo acepta las claves declaradas: cualquier otra clave devuelve 400
  • cada campo marcado required debe estar presente y no vacio
  • los campos con options solo aceptan los valores listados
  • name es texto libre, sirve para reconocer la credencial despues

El id de la respuesta es el valor a usar como providerWalletId en los runtimes del asistente.

Cuerpo·

obligatorio
application/json

Creacion de una credencial en la cartera.

Reglas operativas:

  • serviceType, provider y engine deben coincidir con una entrada devuelta por GET /api/v1/account/provider-wallet/catalog
  • config solo acepta las claves declaradas en los fields de esa entrada; cualquier otra clave se rechaza
  • cada campo marcado required debe estar presente y no vacio
  • config
    Tipo: object
    obligatorio

    Valores de los campos declarados por la entrada del catalogo

    Propiedades: 1
  • engine
    Tipo: string
    obligatorio

    Código de motor seleccionado del catálogo del monedero de proveedores.

  • name
    Tipo: string
    longitud máx.:  
    120
    obligatorio

    Nombre definido por el cliente para la credencial guardada.

  • provider
    Tipo: string
    obligatorio

    Código de proveedor seleccionado del catálogo del monedero de proveedores.

  • serviceType
    Tipo: enum
    obligatorio

    Categoría de servicio seleccionada del catálogo del monedero de proveedores.

    valores
    llmttsasrvoice_llm

Respuestas

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

Credencial guardada

Lista las credenciales de la cartera asociadas a un asistente

​

Devuelve que credencial usa cada runtime del asistente, una entrada por scopeKey (por ejemplo el llm, el tts, el asr).

Los endpoints runtime solo informan hasProviderWallet, un booleano: aqui se descubre cual credencial esta aplicada.

Las asociaciones no se escriben aqui: se crean enviando providerWalletId en el endpoint runtime correspondiente, y se quitan enviando providerWalletId: null.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

Asociaciones del asistente

Recupera una credencial de la cartera

​

Devuelve una sola credencial. Como en el listado, la configuracion vuelve solo como preview, con los secretos enmascarados.

Parámetros de ruta

  • providerWalletId
    Tipo: integer
    mín.:  
    1
    obligatorio

    Id de la credencial, devuelto al crearla o por el endpoint de listado

Respuestas

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

Credencial encontrada

Actualiza una credencial de la cartera

​

Actualiza una credencial con semantica PATCH merge.

Parametros modificables:

  • name
  • isActive
  • config

Reglas operativas:

  • al menos uno de los tres debe estar presente
  • serviceType, provider y engine no se cambian: para cambiar de proveedor se crea una credencial nueva
  • dentro de config, un campo omitido o vacio conserva el valor ya guardado. Esto es lo que permite renombrar una credencial sin reenviar una API key que el cliente nunca puede releer
  • desactivar con isActive: false conserva la credencial pero deja de aplicarla a los runtimes

Parámetros de ruta

  • providerWalletId
    Tipo: integer
    mín.:  
    1
    obligatorio

    Id de la credencial, devuelto al crearla o por el endpoint de listado

Cuerpo·

obligatorio
application/json

PATCH merge de una credencial.

Reglas operativas:

  • al menos uno entre name, isActive y config debe estar presente
  • serviceType, provider y engine no se cambian: para cambiar de proveedor se crea una credencial nueva
  • dentro de config, un campo omitido o vacio conserva el valor ya guardado - util para los secretos, que el cliente nunca puede releer
  • config
    Tipo: object

    Campos de credenciales que se combinarán con la configuración guardada.

    Propiedades: 1
  • isActive
    Tipo: boolean

    Indica si la credencial guardada puede ser usada por los runtimes de asistentes.

  • name
    Tipo: string
    longitud máx.:  
    120

    Nuevo nombre de credencial definido por el cliente.

Respuestas

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

Credencial actualizada

Elimina una credencial de la cartera

​

Elimina definitivamente la credencial y toda asociacion con los asistentes del cliente.

Los asistentes afectados vuelven a usar los valores escritos directamente en su propia configuracion; no se detienen. Si necesitas saber cuales son, comprueba antes las asociaciones con GET /api/v1/account/provider-wallet/assistants/{assistantApiKey}.

Parámetros de ruta

  • providerWalletId
    Tipo: integer
    mín.:  
    1
    obligatorio

    Id de la credencial, devuelto al crearla o por el endpoint de listado

Respuestas

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

Credencial eliminada

Catalog TTS

​

Actualización del tiempo de ejecución de TTS del proveedor, voces y asistente de TTS

Catalog TTS Operaciones

Actualizar la configuración del tiempo de ejecución TTS del asistente

​

Actualice la configuración del tiempo de ejecución TTS del asistente con la semántica PATCH merge.

Parámetros editables:

  • sourceMode
  • engineCode
  • voiceCode
  • API key
  • region

Si usas ai4call

  • Enviar sourceMode: ai4call
  • Enviar voiceCode
  • engineCode y opcional
  • No enviar API key
  • No enviar region

Si usas customer

  • Enviar sourceMode: customer
  • Enviar engineCode
  • Enviar voiceCode
  • Enviar API key
  • Si usas Azure, envía también region

Nota sobre la fusión

  • Los campos omitidos conservan el valor actual, si ya están presentes.
  • La respuesta devuelve la configuración final resultante.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

Elija uno de los ejemplos siguientes según el modo que desee configurar.

  • ai4call: selección de un artículo del catálogo AI4Call
  • customer: configuración directa con parámetros del proveedor del cliente

Combinación de PATCH de la configuración TTS del asistente.

Reglas operativas:

  • sourceMode y siempre obligatorio
  • los campos omitidos conservan el valor actual ya guardado, si está presente
  • en ai4call el backend resuelve la configuración a partir de voiceCode
  • en customer la configuración utiliza parámetros directos del cliente

Restricciones de la aplicación:

  • customer: engineCode, voiceCode y API key deben completarse después de la fusión
  • customer con Azure: region debe completarse después de la fusión
  • ai4call: utilice voiceCode; engineCode es opcional y sirve solo como verificación de coherencia
  • sourceMode
    Tipo: "ai4call" or "customer"enum
    obligatorio

    Modo de abastecimiento en tiempo de ejecución.

    • ai4call: utiliza un proveedor/modelo presente en las listas de precios AI4Call del cliente
    • customer: Utilice configuración y credenciales directas del cliente
  • apiKey
    Tipo: string | null
    solo escritura

    Clave API del proveedor TTS del cliente. Sólo debe enviarse en customer. En ai4call se debe omitir.

  • engineCode
    Tipo: string | null

    Código de proveedor/motor TTS. En customer se identifica el motor a utilizar. En ai4call es opcional y, si se envía, solo se usa para verificar que el voiceCode pertenece a ese motor.

  • providerWalletId
    Tipo: integer | null

    Id de una credencial guardada en la cartera de proveedores del cliente, para usar en lugar del envio de apiKey en claro.

    Cuando esta presente, las credenciales se leen de la cartera, se aplican al runtime y la asociacion se guarda en el asistente. null elimina la asociacion y vuelve a los valores enviados explicitamente.

    Las credenciales de la cartera se crean y se gestionan desde el portal AI4CALL.

  • region
    Tipo: string | null

    Región/área de proveedor solicitada por algunos clientes del motor, en particular Azure. Requerido para Azure en customer. En ai4call se debe omitir.

  • voiceCode
    Tipo: string | null

    Código de voz TTS. En ai4call está el parámetro principal para seleccionar la entrada del catálogo AI4Call. En customer debe identificar la entrada válida para el proveedor/motor elegido.

Respuestas

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

Configuración de tiempo de ejecución TTS actualizada

Enumera los proveedores de TTS disponibles para el cliente.

​

Enumera los proveedores de TTS disponibles para el cliente.

Respuestas

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

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

Lista de proveedores TTS

Enumera las entradas TTS resueltas por la configuración del tiempo de ejecución del asistente.

​

Enumera las entradas TTS resueltas por la configuración del tiempo de ejecución del asistente.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

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

Lista de voces TTS del asistente

Catalog ASR

​

Proveedor de ASR, plantillas y asistente de actualización del tiempo de ejecución de ASR

Catalog ASR Operaciones

Actualizar la configuración del tiempo de ejecución ASR del asistente

​

Actualice la configuración del tiempo de ejecución ASR del asistente con la semántica PATCH merge.

Parámetros editables:

  • sourceMode
  • engineCode
  • API key

Si usas ai4call

  • Enviar sourceMode: ai4call
  • Enviar engineCode
  • No enviar API key

Si usas customer

  • Enviar sourceMode: customer
  • Enviar engineCode
  • Enviar API key

Nota sobre la fusión

  • Los campos omitidos conservan el valor actual, si ya están presentes.
  • La respuesta devuelve la configuración final resultante.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

Elija uno de los ejemplos siguientes según el modo que desee configurar.

  • ai4call: selección de un motor ASR del catálogo AI4Call
  • customer: configuración directa con el motor y clave API del cliente

PATCH fusiona la configuración ASR del asistente.

Reglas operativas:

  • sourceMode y siempre obligatorio
  • los campos omitidos conservan el valor actual ya guardado, si está presente
  • en ai4call el backend selecciona un motor disponible de las listas de precios AI4Call del cliente
  • en customer la configuración utiliza parámetros directos del cliente

Restricciones de la aplicación:

  • customer: engineCode y API key deben completarse después de la fusión
  • ai4call: engineCode debe identificar un motor disponible en el catálogo AI4Call del cliente
  • sourceMode
    Tipo: "ai4call" or "customer"enum
    obligatorio

    Modo de abastecimiento en tiempo de ejecución.

    • ai4call: utiliza un motor ASR presente en las listas de precios AI4Call del cliente
    • customer: Utilice configuración y credenciales directas del cliente
  • apiKey
    Tipo: string | null
    solo escritura

    Clave API del proveedor de ASR del cliente. Sólo debe enviarse en customer. En ai4call se debe omitir.

  • engineCode
    Tipo: string | null

    Código de motor/proveedor ASR. En ai4call se identifica el motor AI4Call a asociar. En customer identifica el motor del proveedor del cliente.

  • providerWalletId
    Tipo: integer | null

    Id de una credencial guardada en la cartera de proveedores del cliente, para usar en lugar del envio de apiKey en claro.

    Cuando esta presente, las credenciales se leen de la cartera, se aplican al runtime y la asociacion se guarda en el asistente. null elimina la asociacion y vuelve a los valores enviados explicitamente.

    Las credenciales de la cartera se crean y se gestionan desde el portal AI4CALL.

Respuestas

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

Configuración de tiempo de ejecución de ASR actualizada

Enumera los proveedores de ASR disponibles para el cliente.

​

Enumera los proveedores de ASR disponibles para el cliente.

Respuestas

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

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

Lista de proveedores de ASR

Enumera los patrones ASR resueltos por la configuración del tiempo de ejecución del asistente.

​

Enumera los patrones ASR resueltos por la configuración del tiempo de ejecución del asistente.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

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

Lista de modelos de asistente ASR

Catalog LLM

​

Actualización del tiempo de ejecución de LLM de proveedor, plantillas y asistente de LLM

Catalog LLM Operaciones

Actualice la configuración del tiempo de ejecución de LLM del asistente

​

Actualice la configuración del tiempo de ejecución de LLM del asistente con la semántica PATCH merge.

Parámetros editables:

  • sourceMode
  • engineCode
  • modelCode
  • API key
  • baseUrl

Si usas ai4call

  • Enviar sourceMode: ai4call
  • Enviar modelCode
  • engineCode y opcional
  • No enviar API key
  • No enviar baseUrl

Si usas customer

  • Enviar sourceMode: customer
  • Enviar engineCode
  • Enviar modelCode
  • Si engineCode = ollama, envíe baseUrl
  • Para todos los demás motores, envíe API key

Nota sobre la fusión

  • Los campos omitidos conservan el valor actual, si ya están presentes.
  • La respuesta devuelve la configuración final resultante.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

Elija uno de los ejemplos siguientes según el modo que desee configurar.

  • ai4call: selección de un modelo del catálogo AI4Call
  • customer: configuración directa con el proveedor del cliente

PATCH fusiona la configuración LLM del asistente.

Reglas operativas:

  • sourceMode y siempre obligatorio
  • los campos omitidos conservan el valor actual ya guardado, si está presente
  • en ai4call el backend resuelve la configuración a partir de modelCode
  • en customer la configuración utiliza parámetros directos del cliente

Restricciones de la aplicación:

  • customer: engineCode y modelCode deben completarse después de la fusión
  • customer con ollama: baseUrl debe completarse después de la fusión
  • customer con motores distintos a ollama: API key debe completarse después de la fusión
  • ai4call: utilice modelCode; engineCode es opcional y sirve solo como verificación de coherencia
  • sourceMode
    Tipo: "ai4call" or "customer"enum
    obligatorio

    Modo de abastecimiento en tiempo de ejecución.

    • ai4call: utiliza un modelo presente en las listas de precios AI4Call del cliente
    • customer: Utilice configuración y credenciales directas del cliente
  • apiKey
    Tipo: string | null
    solo escritura

    Clave API del proveedor de LLM del cliente. Debe enviarse en customer para proveedores que lo soliciten. Para ollama normalmente no es necesario. En ai4call se debe omitir.

  • baseUrl
    Tipo: string | null

    URL personalizada base del proveedor de LLM. Normalmente se utiliza para ollama o puntos finales compatibles con OpenAI autohospedados. En customer con ollama y obligatorio. En ai4call se debe omitir.

  • engineCode
    Tipo: string | null

    Código de motor/proveedor de LLM. En customer se identifica el proveedor a utilizar. En ai4call es opcional y, si se envía, solo se usa para verificar que el modelCode pertenece a ese motor.

  • modelCode
    Tipo: string | null

    Código de modelo LLM. En ai4call está el parámetro principal para seleccionar el modelo del catálogo AI4Call. En customer debe identificar el modelo válido para el proveedor elegido.

  • providerWalletId
    Tipo: integer | null

    Id de una credencial guardada en la cartera de proveedores del cliente, para usar en lugar del envio de apiKey en claro.

    Cuando esta presente, las credenciales se leen de la cartera, se aplican al runtime y la asociacion se guarda en el asistente. null elimina la asociacion y vuelve a los valores enviados explicitamente.

    Las credenciales de la cartera se crean y se gestionan desde el portal AI4CALL.

Respuestas

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

Configuración de tiempo de ejecución de LLM actualizada

Enumera los proveedores de LLM disponibles para el cliente.

​

Enumera los proveedores de LLM disponibles para el cliente.

Respuestas

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

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

Lista de proveedores de LLM

Enumera los modelos LLM resueltos por la configuración del tiempo de ejecución del asistente.

​

Enumera los modelos LLM resueltos por la configuración del tiempo de ejecución del asistente.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

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

Lista de plantillas de asistente LLM

Catalog Audio-to-Audio

​

Proveedores, modelos, voces y runtimes canónicos para asistentes audio-a-audio

Catalog Audio-to-Audio Operaciones

Actualiza la configuracion runtime audio-to-audio del asistente

​

Ruta canonica para los asistentes realtime audio-to-audio.

PATCH /api/v1/assistants/{assistantApiKey}/runtime/voice-to-voice se mantiene como alias historico: mismo handler, mismo payload, misma respuesta.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

PATCH merge de la configuración de runtime audio-a-audio.

Actualiza el JSON del servidor configType: voice-llm. Debe estar presente al menos un campo entre engineCode, modelCode, voiceCode, providerWalletId, apiKey, baseUrl o prompt.

  • apiKey
    Tipo: string | null
    solo escritura

    API del proveedor de claves de cliente. Envíe null para eliminarlo del JSON.

  • baseUrl
    Tipo: string | null

    URL personalizada base. Envíe null para eliminarlo del JSON.

  • engineCode
    Tipo: string

    LLM de voz de proveedor/motor.

  • modelCode
    Tipo: string

    Código de modelo de voz LLM.

  • prompt
    Tipo: string

    Prompt principal del runtime audio-to-audio.

  • providerWalletId
    Tipo: integer | null

    Id de una credencial guardada en la cartera de proveedores del cliente, para usar en lugar del envio de apiKey en claro.

    Cuando esta presente, las credenciales se leen de la cartera, se aplican al runtime y la asociacion se guarda en el asistente. null elimina la asociacion y vuelve a los valores enviados explicitamente.

    Las credenciales de la cartera se crean y se gestionan desde el portal AI4CALL.

  • voiceCode
    Tipo: string

    Código de artículo del modelo.

Respuestas

  • 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-a-audio actualizado

Enumera los proveedores de voz LLM disponibles para el cliente

​

Enumera los proveedores de voz LLM disponibles para el cliente

Respuestas

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

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

Lista de proveedores de voz LLM

Enumera los modelos de LLM por voz

​

Enumera los modelos de LLM por voz

Parámetros de consulta

  • provider
    Tipo: string
    obligatorio
  • sourceMode
    Tipo: "ai4call" or "customer"enum

Respuestas

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

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

Lista de modelos de voz de LLM

Enumera las voces disponibles para un modelo de voz LLM

​

Enumera las voces disponibles para un modelo de voz LLM

Parámetros de consulta

  • modelCode
    Tipo: string
    obligatorio

Respuestas

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

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

Lista de entradas de voz LLM

Enumera los modelos de LLM de voz compatibles con el asistente.

​

Enumera los modelos de LLM de voz compatibles con el asistente.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

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

Lista de plantillas de LLM de asistente de voz

Enumera las entradas de voz de LLM disponibles para un asistente

​

Enumera las entradas de voz de LLM disponibles para un asistente

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Parámetros de consulta

  • modelCode
    Tipo: string
    obligatorio

Respuestas

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

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

Lista de entradas de asistente de voz LLM

Catalog DTMF

​

Configuración del asistente DTMF y actualización del tiempo de ejecución DTMF

Catalog DTMF Operaciones

Actualizar la configuración de tiempo de ejecución DTMF del asistente

​

Actualice la configuración DTMF del asistente con la semántica PATCH merge.

Parámetros editables:

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

Cómo recuperar datos actuales:

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

Reglas operativas:

  • si desea modificar solo un campo, envíe solo ese campo
  • enabled: false restablece todas las configuraciones DTMF
  • playEnabled permanece independiente del cambio DTMF recibido
  • en los asistentes voice_to_voice el backend actualiza dtmf y pbxTools.dtmf/playDtmf en JSON voice-llm

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

Fusión de PATCH de la configuración DTMF del asistente.

Reglas operativas:

  • debe estar presente al menos uno de enabled, playEnabled, acceptTimeout, minLength, maxLength, terminationChars
  • los campos omitidos conservan el valor actual
  • al enviar una de las configuraciones DTMF con enabled omitido, DTMF se considera habilitado
  • enabled: false restablece acceptTimeout, minLength, maxLength y terminationChars
  • playEnabled controla el envío de DTMF durante la llamada
  • acceptTimeout
    Tipo: integer | null
    mín.:  
    0

    Valor que se debe enviar para acceptTimeout en la solicitud AssistantDtmfRuntimeUpdateRequest.

  • enabled
    Tipo: boolean

    Activa o desactiva la recepción DTMF.

  • maxLength
    Tipo: integer | null
    mín.:  
    0

    Valor que se debe enviar para maxLength en la solicitud AssistantDtmfRuntimeUpdateRequest.

  • minLength
    Tipo: integer | null
    mín.:  
    0

    Valor que se debe enviar para minLength en la solicitud AssistantDtmfRuntimeUpdateRequest.

  • playEnabled
    Tipo: boolean

    Activa o desactiva el envío DTMF durante la llamada.

  • terminationChars
    Tipo: string | null

    Valor que se debe enviar para terminationChars en la solicitud AssistantDtmfRuntimeUpdateRequest.

Respuestas

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

Configuración de tiempo de ejecución DTMF actualizada

Recuperar la configuración DTMF del asistente

​

Recuperar la configuración DTMF del asistente

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

Asistente de configuración DTMF

Catalog Settings

​

Configuración del asistente y configuración avanzada

Catalog Settings Operaciones

Actualizar la configuración del asistente

​

Actualice la configuración del asistente con la semántica PATCH merge.

Parámetros editables:

  • 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

Cómo recuperar datos actuales:

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

Reglas operativas:

  • si desea modificar solo un campo, envíe solo ese campo
  • filler, reprompt y callPermissions fusionan solo los campos presentes
  • country, prefixMobile y prefixFixed se pueden configurar en null
  • en los asistentes voice_to_voice, la configuración conversacional se escribe en la raíz JSON voice-llm; los permisos de llamada permanecen en la base de datos como en el portal

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

PATCH fusión de la configuración del servidor.

Cómo recuperar datos actuales:

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

Reglas operativas:

  • enviar sólo los campos a modificar
  • filler, reprompt y callPermissions utilizan combinación parcial en campos enviados
  • callPermissions utiliza combinación parcial en campos enviados
  • country, prefixMobile y prefixFixed se pueden enviar a null para eliminar el valor guardado.
  • asrInitialDelayMs
    Tipo: integer
    mín.:  
    0
    máx.:  
    10000

    Valor que se debe enviar para asrInitialDelayMs en la solicitud AssistantSettingsRuntimeUpdateRequest.

  • asrSilenceMs
    Tipo: integer
    mín.:  
    500
    máx.:  
    5000

    Valor que se debe enviar para asrSilenceMs en la solicitud AssistantSettingsRuntimeUpdateRequest.

  • callPermissions
    Tipo: object

    Valor que se debe enviar para callPermissions en la solicitud AssistantSettingsRuntimeUpdateRequest.

    Propiedades: 8
  • dynamicTimeoutMs
    Tipo: integer
    mín.:  
    5000
    máx.:  
    300000

    Valor que se debe enviar para dynamicTimeoutMs en la solicitud AssistantSettingsRuntimeUpdateRequest.

  • filler
    Tipo: object

    Valor que se debe enviar para filler en la solicitud AssistantSettingsRuntimeUpdateRequest.

    Propiedades: 6
  • maxResponseLength
    Tipo: integer
    mín.:  
    1000
    máx.:  
    10000000

    Valor que se debe enviar para maxResponseLength en la solicitud AssistantSettingsRuntimeUpdateRequest.

  • reprompt
    Tipo: object

    Valor que se debe enviar para reprompt en la solicitud AssistantSettingsRuntimeUpdateRequest.

    Propiedades: 5
  • truncateInitialAudio
    Tipo: boolean

    Valor que se debe enviar para truncateInitialAudio en la solicitud AssistantSettingsRuntimeUpdateRequest.

  • ttsInterruptionInConversation
    Tipo: boolean

    Valor que se debe enviar para ttsInterruptionInConversation en la solicitud AssistantSettingsRuntimeUpdateRequest.

  • vad
    Tipo: boolean

    Valor que se debe enviar para vad en la solicitud AssistantSettingsRuntimeUpdateRequest.

  • vadMinVoiceMs
    Tipo: integer
    mín.:  
    0

    Valor que se debe enviar para vadMinVoiceMs en la solicitud AssistantSettingsRuntimeUpdateRequest.

  • vadThreshold
    Tipo: numberFormato: float
    mín.:  
    0
    máx.:  
    1

    Valor que se debe enviar para vadThreshold en la solicitud AssistantSettingsRuntimeUpdateRequest.

Respuestas

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

Configuraciones actualizadas

Actualizar la configuración avanzada del asistente

​

Actualice la configuración avanzada del asistente con la semántica PATCH merge.

Parámetros editables:

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

Cómo recuperar datos actuales:

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

Reglas operativas:

  • si desea modificar solo un campo, envíe solo ese campo
  • los campos numéricos se pueden enviar a null para su eliminación
  • stopSequences: null o stopSequences: [] restablece la lista
  • en los asistentes voice_to_voice estos valores se escriben en la raíz JSON voice-llm

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

Combinación de PATCH de la configuración avanzada del asistente.

Cómo recuperar datos actuales:

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

Reglas operativas:

  • enviar sólo los campos a modificar
  • los campos numéricos se pueden enviar a null para su eliminación
  • stopSequences: null o stopSequences: [] restablece la lista
  • freqPenalty
    Tipo: number | null
    mín.:  
    -2
    máx.:  
    2

    Valor que se debe enviar para freqPenalty en la solicitud AssistantAdvancedSettingsRuntimeUpdateRequest.

  • maxTokens
    Tipo: integer | null
    mín.:  
    1
    máx.:  
    100000

    Valor que se debe enviar para maxTokens en la solicitud AssistantAdvancedSettingsRuntimeUpdateRequest.

  • presencePenalty
    Tipo: number | null
    mín.:  
    -2
    máx.:  
    2

    Valor que se debe enviar para presencePenalty en la solicitud AssistantAdvancedSettingsRuntimeUpdateRequest.

  • stopSequences
    Tipo: array of string | null

    Valor que se debe enviar para stopSequences en la solicitud AssistantAdvancedSettingsRuntimeUpdateRequest.

  • temperature
    Tipo: number | null
    mín.:  
    0
    máx.:  
    2

    Valor que se debe enviar para temperature en la solicitud AssistantAdvancedSettingsRuntimeUpdateRequest.

  • topK
    Tipo: integer | null
    mín.:  
    1
    máx.:  
    100

    Valor que se debe enviar para topK en la solicitud AssistantAdvancedSettingsRuntimeUpdateRequest.

  • topP
    Tipo: number | null
    mín.:  
    0
    máx.:  
    1

    Valor que se debe enviar para topP en la solicitud AssistantAdvancedSettingsRuntimeUpdateRequest.

Respuestas

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

Configuración avanzada actualizada

Recuperar la configuración del asistente

​

Recuperar la configuración del asistente

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

Configuración del asistente

Recuperar la configuración avanzada del asistente

​

Recuperar la configuración avanzada del asistente

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

Configuración avanzada del asistente

Catalog Hangup

​

Configuración de colgar, redirección y transferencia de asistente

Catalog Hangup Operaciones

Actualizar la configuración del tiempo de ejecución de colgar del asistente

​

Actualice la configuración de colgar, redireccionar y transferir con la semántica PATCH merge.

Parámetros editables:

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

Cómo recuperar datos actuales:

  • utilizar GET /api/v1/catalog/assistants/{assistantApiKey}/hangup
  • use GET /api/v1/assistants para recuperar los assistantApiKey seleccionables para transferencia

Reglas operativas:

  • si desea modificar solo un parámetro, envíe solo ese parámetro
  • enableTransferAgent: false restablece notificaciones y asistentes conectados
  • si enableTransferAgent está activo, se necesita al menos un asistente con una descripción que no esté vacía
  • en los asistentes voice_to_voice, el backend actualiza pbxTools.hangup, pbxTools.redirect y pbxTools.transferAgent.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

Combinación de PATCH de la configuración de colgar/redireccionar/transferir el asistente.

Reglas operativas:

  • al menos uno de enableHangup, enableRedirect, enableTransferAgent, transferAgentNotificationText, availableAgents debe estar presente
  • los campos omitidos conservan el valor actual
  • use GET /api/v1/catalog/assistants/{assistantApiKey}/hangup para leer el estado actual
  • use GET /api/v1/assistants para recuperar el assistantApiKey seleccionable para transferencia
  • si enableTransferAgent y true, necesita al menos un availableAgents con una descripción que no esté vacía
  • si envía availableAgents con enableTransferAgent omitido, la transferencia se considera activa
  • enableTransferAgent: false restablece transferAgentNotificationText y availableAgents
  • availableAgents
    Tipo:

    Valor que se debe enviar para availableAgents en la solicitud AssistantHangupRuntimeUpdateRequest.

    Propiedades: 2
  • enableHangup
    Tipo: boolean

    Valor que se debe enviar para enableHangup en la solicitud AssistantHangupRuntimeUpdateRequest.

  • enableRedirect
    Tipo: boolean

    Valor que se debe enviar para enableRedirect en la solicitud AssistantHangupRuntimeUpdateRequest.

  • enableTransferAgent
    Tipo: boolean

    Valor que se debe enviar para enableTransferAgent en la solicitud AssistantHangupRuntimeUpdateRequest.

  • transferAgentNotificationText
    Tipo: string | null

    Valor que se debe enviar para transferAgentNotificationText en la solicitud AssistantHangupRuntimeUpdateRequest.

Respuestas

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

Configuración actualizada del tiempo de ejecución de colgar

Recuperar la configuración para guardar la conversación del asistente

​

Devuelve el estado de guardado de la conversación actual:

  • enabled: si está activo el envío del resumen vía email
  • emails: destinatarios configurados (cadena separada por comas)
  • smtpInstanceName: nombre de la instancia del complemento SMTP conectado

Requisito previo: el cliente debe tener al menos una suscripción activa a un complemento SMTP.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

Configuración de guardado de conversación recuperada

Actualizar la configuración de guardado de conversaciones del asistente

​

Actualice la configuración para guardar la conversación con la semántica PATCH merge.

Parámetros editables:

  • enabled -emails -smtpInstanceName

Cómo recuperar datos actuales:

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

Reglas operativas:

  • debe estar presente al menos uno de enabled, emails y smtpInstanceName
  • los campos omitidos conservan el valor actual
  • smtpInstanceName debe coincidir con el instanceName de la suscripción SMTP activa de un cliente.
  • para obtener la lista de instancias SMTP disponibles, verifique las suscripciones a complementos del cliente
  • emails acepta una cadena con uno o más correos electrónicos separados por comas
  • configurar smtpInstanceName: null elimina la conexión a la instancia SMTP

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

Combinación de PATCH de la configuración para guardar la conversación del asistente.

Reglas operativas:

  • debe estar presente al menos uno de enabled, emails y smtpInstanceName
  • los campos omitidos conservan el valor actual
  • smtpInstanceName coincide con el instanceName de la suscripción SMTP activa del cliente.
  • si enabled: true, se debe configurar un complemento SMTP activo
  • emails acepta una cadena con uno o más correos electrónicos separados por comas
  • emails
    Tipo: string | null

    Uno o más correos electrónicos de destinatarios separados por comas (por ejemplo, correo electrónico1@ejemplo.com, correo electrónico2@ejemplo.com)

  • enabled
    Tipo: boolean

    Activar o desactivar el envío del resumen de la conversación por correo electrónico

  • smtp_instance_name
    Tipo: string | null
    obsoleto

    Alias ​​heredado de smtpInstanceName.

  • smtpInstanceName
    Tipo: string | null

    Nombre de la instancia del complemento SMTP que se utilizará para el envío

Respuestas

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

Configuración actualizada para guardar conversaciones

Recupera la configuracion del webhook de fin de conversacion del asistente

​

Devuelve la configuracion actual del webhook llamado al final de la llamada:

  • enabled: si el envio esta activo
  • url: endpoint de destino
  • authName: nombre de la autenticacion aplicada, null para una llamada sin autenticar
  • payloadFields: campos siempre presentes en el body enviado

Este canal es alternativo al envio por email (runtime/hangup/save-conversation) y ambos pueden estar activos a la vez.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

Configuracion webhook recuperada

Actualiza la configuracion del webhook de fin de conversacion del asistente

​

Actualiza la configuracion del webhook con semantica PATCH merge.

Parametros modificables:

  • enabled
  • url
  • authName

Como recuperar los datos actuales:

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

Reglas operativas:

  • al menos uno entre enabled, url y authName debe estar presente
  • los campos omitidos conservan el valor actual
  • habilitar sin una url http:// o https:// valida devuelve 400
  • authName debe coincidir con una autenticacion ya guardada por el cliente; las credenciales se resuelven en el servidor y no viajan en este payload
  • establecer authName: null envia el webhook sin autenticacion

Body recibido por el endpoint: caller, called, callid y conversation.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

PATCH merge de la configuracion del webhook de fin de conversacion del asistente.

Reglas operativas:

  • al menos uno entre enabled, url y authName debe estar presente
  • los campos omitidos conservan el valor actual
  • si enabled: true, url debe ser una direccion http:// o https:// valida
  • authName corresponde al nombre de una autenticacion ya guardada por el cliente; las credenciales se resuelven en el servidor y no viajan en este payload
  • establecer authName: null envia el webhook sin autenticacion
  • authName
    Tipo: string | null

    Nombre de la autenticacion guardada a aplicar a la peticion

  • enabled
    Tipo: boolean

    Habilita o deshabilita el envio de la conversacion al webhook

  • url
    Tipo: string | null

    Endpoint que recibe el POST al final de la llamada

Respuestas

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

Configuracion webhook actualizada

Recuperar la configuración del esquema de la herramienta para colgar

​

Devuelve la configuración actual del esquema enviado al webhook de colgar:

  • hangupUrl: URL del webhook llamado al final de la llamada
  • schema: conjunto de propiedades que definen el cuerpo JSON enviado a la URL de colgar

Cada propiedad puede ser del tipo string, number, boolean, enum o object. Las propiedades de tipo object admiten campos anidados a través de children. En los asistentes voice_to_voice, el patrón se lee desde pbxTools.hangupEndpoint.input_schema.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

{
  "success": true,
  "message": "Assistant hangup schema configuration retrieved successfully.",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "configuration": {
      "hangupUrl": "https://webhook.example.com/hangup",
      "schema": [
        {
          "name": "motivo",
          "type": "string",
          "description": "Motivo del cuelgue",
          "required": true
        },
        {
          "name": "esito",
          "type": "enum",
          "description": "Resultado de la llamada",
          "required": true,
          "enumValues": [
            "positivo",
            "negativo",
            "richiamata"
          ]
        },
        {
          "name": "dati_cliente",
          "type": "object",
          "description": "Datos recopilados sobre el cliente.",
          "children": [
            {
              "name": "nome",
              "type": "string",
              "description": "Nombre del cliente"
            },
            {
              "name": "email",
              "type": "string",
              "description": "Correo electrónico del cliente"
            }
          ]
        }
      ]
    }
  }
}

Patrón de colgar recuperado exitosamente

Actualizar la configuración del esquema de la herramienta para colgar

​

Actualice la configuración del esquema de colgar con la semántica PATCH merge.

Parámetros editables:

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

Cómo recuperar datos actuales:

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

Reglas operativas

  • Al menos uno entre hangupUrl y schema debe estar presente en el body.
  • Los campos omitidos conservan el valor actual.
  • Enviar schema reemplaza completamente el esquema actual (no es una combinación)
  • Al enviar hangupUrl: null se elimina el webhook de URL, se desactiva la herramienta de colgar y también se borra automáticamente el esquema
  • Al enviar schema: [] se borra el esquema manteniendo la URL actual
  • En los asistentes voice_to_voice, el backend actualiza pbxTools.hangupEndpoint.endpoint y pbxTools.hangupEndpoint.input_schema.

Cómo construir el cuerpo del esquema

schema es una matriz de propiedades que definen los campos del cuerpo JSON enviado. a hangupUrl al final de la llamada. Cada propiedad tiene la siguiente estructura:

Campo Tipo Requerido Descripción
name string si Nombre del campo en el cuerpo JSON
type string si Tipo de campo: string, number, boolean, enum, object
description string no Descripción del campo (ayuda a la plantilla LLM a comprender qué ingresar)
required boolean no Si true, el campo es obligatorio en el colgador del cuerpo
enumValues string[] sólo para enum Lista de valores permitidos (solo si type: enum)
children Property[] sólo para object Campos anidados (solo si type: object)

Tipos admitidos y cómo utilizarlos

string — campo de texto libre:

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

number — campo numérico:

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

boolean — campo booleano:

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

enum — campo de opción múltiple, requiere enumValues:

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

object — grupo de campos anidados, requiere 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" }
  ]
}

Ejemplo de cuerpo JSON resultante

Con el esquema anterior, el webhook recibirá un cuerpo similar a:

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

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json
  • hangupUrl
    Tipo: string | null

    URL del webhook para colgar (nulo para eliminar)

  • schema
    Tipo:

    Definición de campos del cuerpo (anula el esquema actual)

    Propiedades: 6

Respuestas

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for patch/api/v1/assistants/{assistantId}/runtime/hangup/schema
curl https://client-api.ai4call.com/api/v1/assistants/205/runtime/hangup/schema \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-client-email: YOUR_SECRET_TOKEN' \
  --header 'x-portal-api-key: YOUR_SECRET_TOKEN' \
  --data '{
  "hangupUrl": "https://webhook.example.com/hangup",
  "schema": [
    {
      "name": "motivo",
      "type": "string",
      "description": "Motivo del cuelgue",
      "required": true
    },
    {
      "name": "esito",
      "type": "enum",
      "description": "Resultado de la llamada",
      "required": true,
      "enumValues": [
        "positivo",
        "negativo",
        "richiamata"
      ]
    },
    {
      "name": "dati_cliente",
      "type": "object",
      "description": "Datos recopilados sobre el cliente.",
      "children": [
        {
          "name": "nome",
          "type": "string",
          "description": "Nombre del cliente"
        },
        {
          "name": "email",
          "type": "string",
          "description": "Correo electrónico del cliente"
        }
      ]
    }
  ]
}'

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

Diagrama de colgar actualizado con éxito

Recuperar la configuración de colgar del asistente

​

Recuperar la configuración de colgar del asistente

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

  • 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": "Transferir cuando el cliente solicite soporte administrativo."
        }
      ]
    }
  }
}

Configuración de colgar del asistente

Catalog Pre-Call

​

Configuración del asistente prellamada

Catalog Pre-Call Operaciones

Recuperar la configuración de verificación del número que llama

​

Devuelve la configuración actual del webhook utilizado para verificar el número. persona que llama antes de que la llamada se conecte al asistente.

Si aún no se ha creado ninguna configuración, data.configuration será null.

Cómo funciona la verificación de números

Cuando llega una llamada, el sistema realiza una solicitud HTTP al webhook configurado, pasando el número que llama al campo indicado (numberParamName), en la posición indicado (numberLocation). El webhook debería responder con: 

{ "enabled": true }
  • Si enabled es true (o está ausente): la llamada continúa normalmente
  • Si enabled es false: la llamada está bloqueada

El webhook también puede devolver un objeto callerInfo con datos adicionales que se pondrá a disposición del asistente durante la llamada.

Nota de seguridad

Los campos confidenciales (authToken, authPassword) nunca se devuelven en texto sin cifrar. En su lugar están las banderas hasAuthToken y hasAuthPassword.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

  • 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'
Configuración presente
{
  "success": true,
  "message": "Assistant precall validation configuration retrieved successfully.",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "configuration": {
      "name": "Verifica CRM",
      "method": "POST",
      "url": "https://api.example.com/validate-caller",
      "numberLocation": "body",
      "numberParamName": "caller_id",
      "headersJson": {
        "X-Api-Version": "2"
      },
      "authType": "bearer",
      "hasAuthToken": true,
      "hasAuthPassword": false,
      "authUsername": null,
      "timeoutMs": 5000,
      "isActive": true
    }
  }
}

Configuración de verificación de número recuperada

Crear o actualizar la configuración de verificación del número que llama

​

Cree la configuración si no existe; de lo contrario, actualice los campos proporcionados. con semántica PATCH merge (los campos omitidos conservan el valor actual).

Parámetros editables:

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

Cómo recuperar datos actuales:

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

Reglas operativas

  • Al menos un campo debe estar presente en el cuerpo.
  • Los campos omitidos conservan el valor actual (o el valor predeterminado si es la primera creación)
  • Enviar isActive: false elimina completamente la configuración — data.configuration será null
  • La configuración siempre está activa (isActive: true) cuando se crea o actualiza
  • Al enviar authToken: null se elimina el token configurado
  • Al enviar authPassword: null se elimina la contraseña configurada.
  • Al enviar headersJson: null se eliminan todos los encabezados personalizados.
  • authToken y authPassword nunca se devuelven — use hasAuthToken/hasAuthPassword

Cómo configurar numberLocation

Valor Dónde se envía el número Ejemplo
query Cadena de consulta de URL GET /validate?caller_id=0391234567
body Cuerpo JSON de la solicitud POST /validate con maillot { "caller_id": "0391234567" }
params Segmento de URL GET /validate/0391234567 (el número reemplaza a :numberParamName en la URL)

Autenticación compatible

authType Campos obligatorios Encabezado generado
none — ninguno
bearer authToken Authorization: Bearer <token>
api_key authToken X-Api-Key: <token>
basic authUsername + authPassword Authorization: Basic <base64>

Respuesta esperada del webhook

El webhook debe responder con HTTP 200 y un cuerpo JSON que contenga al menos:

{ "enabled": true }

Puede incluir datos adicionales:

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

Si enabled es false, la llamada se bloquea antes de llegar al asistente.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json
  • authPassword
    Tipo: string | null

    Contraseña de autenticación básica (nula para eliminarla)

  • authToken
    Tipo: string | null

    Token de portador o clave API (nulo para eliminarlo)

  • authType
    Tipo: enum
    valores
    nonebearerapi_keybasic
  • authUsername
    Tipo: string | null

    Valor que se debe enviar para authUsername en la solicitud AssistantPrecallValidationRuntimeUpdateRequest.

  • headersJson
    Tipo: object | null

    Valor que se debe enviar para headersJson en la solicitud AssistantPrecallValidationRuntimeUpdateRequest.

    Propiedades: 1
  • isActive
    Tipo: boolean

    Valor que se debe enviar para isActive en la solicitud AssistantPrecallValidationRuntimeUpdateRequest.

  • method
    Tipo: enum
    valores
    GETPOSTPUTPATCHDELETE
  • name
    Tipo: string
    longitud mín.:  
    1

    Valor que se debe enviar para name en la solicitud AssistantPrecallValidationRuntimeUpdateRequest.

  • numberLocation
    Tipo: enum

    Dónde insertar el número de llamada en la solicitud HTTP:

    • query: agregado como una cadena de consulta (por ejemplo, ?number=0391234567)
    • body — insertado en el cuerpo JSON (por ejemplo, { "number": "0391234567" })
    • params — reemplaza un segmento de la URL (por ejemplo, /validate/0391234567)
    valores
    bodyqueryparams
  • numberParamName
    Tipo: string
    longitud mín.:  
    1

    Valor que se debe enviar para numberParamName en la solicitud AssistantPrecallValidationRuntimeUpdateRequest.

  • timeoutMs
    Tipo: integer
    mín.:  
    500
    máx.:  
    30000

    Valor que se debe enviar para timeoutMs en la solicitud AssistantPrecallValidationRuntimeUpdateRequest.

  • url
    Tipo: stringFormato: uri

    Valor que se debe enviar para url en la solicitud AssistantPrecallValidationRuntimeUpdateRequest.

Respuestas

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

Configuración de verificación de número actualizada

Recuperar la configuración previa a la llamada del asistente

​

Devuelve la configuración actual de la fase previa a la llamada: configuración general (configuration) y herramientas asociadas (tools).

Cómo funciona la fase previa a la llamada

Antes de conectar la llamada al asistente, el sistema realiza secuencialmente las herramientas configuradas (en el orden definido por order). Las herramientas pueden ser:

  • herramientas personalizadas (definidas en el JSON del servidor, subscriptionName: null)
  • complemento MCP de herramienta o MCP personalizado (con subscriptionName mejorado)

Las herramientas pueden recuperar información de la persona que llama, realizar validación o enriquecer el contexto y finalizar la llamada antes de tiempo si earlyTerminationEnabled es true.

Si waitingAudioText está configurado, se reproduce para la persona que llama durante la ejecución. voiceConfig controla la voz utilizada para generar audio de espera/terminación, mientras que modelConfig controla el modelo utilizado para interpretar los resultados de las herramientas.

Cómo leer tools

Los campos toolName y subscriptionName devueltos coinciden con los campos toolName y subscriptionName para enviar el PATCH. Las herramientas de prellamada sólo se podrán elegir entre las ya asociadas al asistente: -GET /api/v1/catalog/assistants/{assistantApiKey}/tools

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

  • 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'
Herramientas personalizadas y complementos MCP asociados
{
  "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
      }
    ]
  }
}

Configuración previa a la llamada recuperada

Actualizar la configuración previa a la llamada del asistente

​

Actualice la configuración previa a la llamada con la semántica PATCH merge. Al menos un campo debe estar presente en el mono.

Parámetros editables:

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

Cómo recuperar la configuración actual:

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

Gestión de herramientas

El campo tools reemplaza completamente las herramientas de prellamada actuales:

Cuerpo publicado Efecto
tools omitido mantiene las herramientas actuales sin cambios
tools: [] elimina todas las herramientas previas a la llamada y restablece todas las configuraciones previas a la llamada
tools: [{...}] reemplaza con la lista enviada

Para clasificar:

  • si cada elemento incluye order, se utiliza order
  • si se omite order, se utiliza el orden de la matriz

Cómo construir la lista tools

Utilice los registros de GET /api/v1/catalog/assistants/{assistantApiKey}/tools para obtener toolName y instanceName. La prellamada sólo acepta herramientas ya asociadas al asistente:

Tipo de herramienta toolName subscriptionName
custom_tool (herramienta JSON personalizada) toolName null
plugin_tool (complemento MCP) toolName instanceName
custom_mcp_tool (MCP personalizado) toolName instanceName

Las herramientas personalizadas (subscriptionName: null) son las definidas en el JSON del asistente y no requieren suscripciones.

Configuración general

Campo Efecto
globalPrompt: null elimina el mensaje global
waitingAudioText: null elimina el audio en espera
earlyTerminationEnabled: true permitir la terminación anticipada
terminationMessage: null elimina mensaje de terminación
waitingAudioNonInterruptible: false hace que el audio en espera sea interrumpible
modelConfig establecer valor predeterminado/asistente/administrado/personalizado para la plantilla previa a la llamada
voiceConfig establecer valor predeterminado/asistente/personalizado para TTS previo a la llamada

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

Actualice la configuración previa a la llamada con la semántica PATCH merge. Al menos un campo debe estar presente.

Gestión de herramientas

El campo tools reemplaza completamente la lista de herramientas previas a la llamada.

  • tools: [] elimina todas las herramientas de prellamada y restablece globalPrompt, waitingAudioText, earlyTerminationEnabled, terminationMessage, waitingAudioNonInterruptible, modelConfig y voiceConfig.
  • tools omitido: mantener las herramientas actuales sin cambios
  • Si order está presente, la orden de ejecución sigue order
  • Si se omite order, el orden de ejecución sigue el orden del array enviado

Para construir la lista utilice los registros de GET /api/v1/catalog/assistants/{assistantApiKey}/tools. La prellamada sólo acepta herramientas ya asociadas al asistente.

  • earlyTerminationEnabled
    Tipo: boolean

    Activar/desactivar la terminación anticipada.

  • enabled
    Tipo: boolean

    Habilita o deshabilita toda la fase de pre-call sin perder su configuracion. Si se omite, conserva el valor actual.

  • globalPrompt
    Tipo: string | null

    Aviso global previo a la llamada. null para eliminarlo.

  • modelConfig
    Tipo:

    Configuración del modelo utilizado por la fase MCP. Las claves API no se devuelven en texto claro: hasApiKey está expuesto en las respuestas.

    Propiedades: 5
  • outputSchema
    Tipo: object

    Esquema JSON de la salida esperada del pre-call, como alternativa a outputVariables.

    Propiedades: 1
  • outputVariables
    Tipo:

    Variables a extraer del resultado del pre-call. Sustituye por completo la lista actual.

    Propiedades: 4
  • terminationMessage
    Tipo: string | null

    Mensaje de audio de terminación anticipada. null para eliminarlo.

  • tools
    Tipo:

    Lista completa de herramientas previas a la llamada para configurar (reemplaza las actuales).

  • voiceConfig
    Tipo:

    Configuración de voz/TTS utilizada para generar audio de terminación y retención previa a la llamada. Las claves API no se devuelven en texto claro: hasApiKey está expuesto en las respuestas.

    Propiedades: 8
  • waitingAudioNonInterruptible
    Tipo: boolean

    true reproduce todo el audio en espera, false permite al cliente hablar por encima del audio.

  • waitingAudioText
    Tipo: string | null

    Texto de audio en espera. null para eliminarlo.

Respuestas

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

Configuración previa a la llamada actualizada

Recuperar la configuración previa a la llamada del asistente

​

Recuperar la configuración previa a la llamada del asistente

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

Configuración previa a la llamada

Catalog Post-Call

​

Configuración del asistente MCP posterior a la llamada

Catalog Post-Call Operaciones

Recuperar la configuración posterior a la llamada MCP del asistente

​

Devuelve la configuración actual de la fase posterior a la llamada de MCP: configuración general (configuration) y herramientas asociadas (tools).

Los campos toolName y subscriptionName devueltos coinciden con los campos toolName y subscriptionName para enviar el PATCH. Las herramientas post-llamada sólo se podrán elegir entre las ya asociadas al asistente: -GET /api/v1/catalog/assistants/{assistantApiKey}/tools

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

  • 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'
Herramientas post-llamada asociadas
{
  "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
      }
    ]
  }
}

Configuración post-llamada recuperada

Actualizar la configuración posterior a la llamada MCP del asistente

​

Actualice la configuración posterior a la llamada con la semántica PATCH merge. Al menos un campo debe estar presente en el mono.

Parámetros editables:

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

Cómo recuperar la configuración actual: -GET /api/v1/assistants/{assistantApiKey}/runtime/postcall/mcp-config

El campo tools reemplaza completamente las herramientas posteriores a la llamada actuales:

Cuerpo publicado Efecto
tools omitido mantiene las herramientas actuales sin cambios
tools: [] elimina todas las herramientas posteriores a la llamada y restablece globalPrompt y modelConfig
tools: [{...}] reemplaza con la lista enviada

Utilice registros de GET /api/v1/catalog/assistants/{assistantApiKey}/tools para obtener toolName y instanceName.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

Actualice la configuración posterior a la llamada con la semántica PATCH merge. Al menos un campo debe estar presente.

El campo tools reemplaza completamente la lista de herramientas posteriores a la llamada.

  • tools: [] elimina todas las herramientas posteriores a la llamada y restablece globalPrompt y modelConfig.
  • tools omitido: mantiene las herramientas actuales sin cambios
  • enabled
    Tipo: boolean

    Habilita o deshabilita toda la fase de post-call sin perder su configuracion. Cuando es false el webhook de fin de llamada no se envia. Si se omite, conserva el valor actual.

  • globalPrompt
    Tipo: string | null

    Aviso global posterior a la llamada. null para eliminarlo.

  • modelConfig
    Tipo:

    Configuración del modelo utilizado por la fase MCP. Las claves API no se devuelven en texto claro: hasApiKey está expuesto en las respuestas.

    Propiedades: 5
  • tools
    Tipo:

    Lista completa de herramientas posteriores a la llamada para configurar.

Respuestas

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

Configuración posterior a la llamada actualizada

Catalog Runtime Bindings

​

Vinculación en tiempo de ejecución del asistente con precios y proveedores reales

Catalog Runtime Bindings Operaciones

Recupera los enlaces del tiempo de ejecución del asistente para TTS, ASR y LLM.

​

Recupera los enlaces del tiempo de ejecución del asistente para TTS, ASR y LLM.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

Enlace de tiempo de ejecución del asistente

Knowledge

​

Recursos knowledge canónicos del cliente y asociaciones con asistentes

Knowledge Operaciones

Lista las knowledge del cliente

​

Devuelve las knowledge del cliente mas las proporcionadas por AI4CALL, de la mas reciente. Las compartidas llevan isShared: true: se pueden asociar a tus asistentes pero no modificar.

Cada entrada vuelve completa con sus disparadores, ordenados por sortOrder.

Parámetros de consulta

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de elementos devueltos en una página con paginación por cursor. Omite limit y cursor para conservar la respuesta legacy sin paginar.

  • cursor
    Tipo: string

    Cursor opaco devuelto en meta.nextCursor por la página anterior.

Respuestas

  • 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": "Horarios y sedes",
        "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 para el cliente

Crea una knowledge

​

Crea una knowledge propiedad del cliente.

Una knowledge es un conjunto de peticiones reconocidas, los disparadores, con lo que el asistente debe responder. Se inserta en el prompt de cada asistente al que esta asociada, asi que crearla no basta: hay que asociarla con PUT /api/v1/catalog/assistants/{assistantApiKey}/knowledge.

Reglas operativas:

  • triggers puede omitirse o estar vacio: la knowledge responde entonces siempre con defaultResponse
  • un disparador sin specificResponse recae en el defaultResponse de la knowledge
  • un disparador sin postAction recae en el defaultPostAction de la knowledge
  • aiInstructions guia como el modelo usa la respuesta, sin reescribir la respuesta misma
  • sortOrder es opcional: si se omite vale el orden del array

Cuerpo·

obligatorio
application/json

Creacion de una knowledge.

triggers puede omitirse o estar vacio: la knowledge responde entonces siempre con defaultResponse.

  • defaultResponse
    Tipo: string
    longitud mín.:  
    1
    obligatorio

    Respuesta predeterminada usada cuando un disparador no tiene una respuesta específica.

  • title
    Tipo: string
    longitud máx.:  
    255
    obligatorio

    Título legible de la nueva knowledge.

  • defaultPostAction
    Tipo: string
    longitud máx.:  
    50

    Vale ask_if_needs_more si se omite

  • rules
    Tipo: string | null

    Restricciones opcionales aplicadas a toda la knowledge.

  • triggers
    Tipo:

    Lista inicial de disparadores de la knowledge.

    Propiedades: 5

Respuestas

  • 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": "Horarios y sedes",
  "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": "Horarios y sedes",
      "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 creada

Recupera una sola knowledge

​

Devuelve una sola knowledge completa con sus disparadores. Vale para las knowledge del cliente y para las compartidas.

Parámetros de ruta

  • knowledgeId
    Tipo: integer
    mín.:  
    1
    obligatorio

    Id de la knowledge

Respuestas

  • 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": "Horarios y sedes",
      "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 encontrada

Actualiza una knowledge

​

Actualiza una knowledge con semantica PATCH merge.

Reglas operativas:

  • al menos un campo debe estar presente, los campos omitidos conservan el valor actual
  • triggers, si esta presente, sustituye la lista entera: hay que enviarla completa, u omitirla para dejar los disparadores sin cambios. Enviar [] los quita todos
  • las knowledge proporcionadas por AI4CALL (isShared: true) no son modificables y responden 404

Los cambios tienen efecto en cada asistente al que la knowledge esta asociada, sin reasociarla.

Parámetros de ruta

  • knowledgeId
    Tipo: integer
    mín.:  
    1
    obligatorio

    Id de la knowledge

Cuerpo·

obligatorio
application/json

PATCH merge de una knowledge.

Reglas operativas:

  • al menos un campo debe estar presente
  • los campos omitidos conservan el valor actual
  • triggers, si esta presente, sustituye la lista entera: hay que enviarla completa, u omitirla para dejar los disparadores sin cambios. Enviar [] los quita todos
  • las knowledge con isShared: true no son modificables
  • defaultPostAction
    Tipo: string
    longitud máx.:  
    50

    Nueva acción posterior predeterminada para los disparadores que no definen una propia.

  • defaultResponse
    Tipo: string
    longitud mín.:  
    1

    Nueva respuesta predeterminada de la knowledge.

  • rules
    Tipo: string | null

    Nuevas restricciones opcionales de la knowledge.

  • title
    Tipo: string
    longitud máx.:  
    255

    Nuevo título de la knowledge.

  • triggers
    Tipo:

    Lista completa de sustitución de disparadores cuando se envía este campo.

    Propiedades: 5

Respuestas

  • 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": "Horarios y sedes",
      "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 actualizada

Elimina una knowledge

​

Elimina definitivamente la knowledge, sus disparadores y toda asociacion con los asistentes del cliente. Los asistentes afectados simplemente dejan de llevarla en el prompt.

Las knowledge proporcionadas por AI4CALL no son eliminables y responden 404.

Parámetros de ruta

  • knowledgeId
    Tipo: integer
    mín.:  
    1
    obligatorio

    Id de la knowledge

Respuestas

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

Lista las knowledge asociadas a un asistente

​

Devuelve las knowledge insertadas en el prompt de este asistente, en el orden en que se aplican, junto con su contenido completo, asi no hace falta una segunda llamada.

Una asociacion que apunta a una knowledge eliminada se descarta de la respuesta.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

  • 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": "Horarios y sedes",
        "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 asociadas

Establece las knowledge asociadas a un asistente

​

Sustituye por completo las asociaciones del asistente: lo que envias se convierte en la lista completa.

Dos formas aceptadas:

  • associations, cuando el orden importa y quieres declararlo
  • knowledgeIds, cuando basta el orden del array

Son excluyentes. Una lista vacia desvincula todas las knowledge.

Se pueden asociar tanto las knowledge propias como las compartidas; un id que no es ni tuyo ni compartido hace fallar toda la llamada con 400, sin cambios parciales.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

Sustituye por completo las asociaciones knowledge del asistente.

Enviar associations cuando el orden importa, knowledgeIds cuando basta el orden del array. Las dos formas son excluyentes; una lista vacia lo desvincula todo.

Se pueden asociar tanto las knowledge propias como las compartidas.

  • associations
    Tipo: array of object

    Valor que se debe enviar para associations en la solicitud AssistantKnowledgeAssociationsRequest.

    Propiedades: 2
  • knowledgeIds
    Tipo: array of integer

    Valor que se debe enviar para knowledgeIds en la solicitud AssistantKnowledgeAssociationsRequest.

Respuestas

  • 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": "Horarios y sedes",
        "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"
      }
    ]
  }
}

Asociaciones actualizadas

Filler Phrase Lists

​

Listas de frases de relleno reutilizables canónicas y asociaciones con asistentes

Filler Phrase Lists Operaciones

Listar las listas de relleno del cliente.

​

Listar las listas de relleno del cliente.

Parámetros de consulta

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de elementos devueltos en una página con paginación por cursor. Omite limit y cursor para conservar la respuesta legacy sin paginar.

  • cursor
    Tipo: string

    Cursor opaco devuelto en meta.nextCursor por la página anterior.

Respuestas

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

Listas de relleno disponibles

Crear una lista de relleno

​

Crear una lista de relleno

Cuerpo·

obligatorio
application/json
  • id
    Tipo: string
    longitud máx.:  
    100
    obligatorio

    Valor que se debe enviar para id en la solicitud FillerPhraseListCreateRequest.

  • name
    Tipo: string
    longitud máx.:  
    255
    obligatorio

    Valor que se debe enviar para name en la solicitud FillerPhraseListCreateRequest.

  • phrases
    Tipo: array of string

    Valor que se debe enviar para phrases en la solicitud FillerPhraseListCreateRequest.

Respuestas

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

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

Lista de relleno creada

Actualizar una lista de relleno

​

Actualizar una lista de relleno

Parámetros de ruta

  • listId
    Tipo: string
    obligatorio

Cuerpo·

obligatorio
application/json
  • name
    Tipo: string
    longitud máx.:  
    255
    obligatorio

    Valor que se debe enviar para name en la solicitud FillerPhraseListUpdateRequest.

  • phrases
    Tipo: array of string

    Valor que se debe enviar para phrases en la solicitud FillerPhraseListUpdateRequest.

Respuestas

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

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

Lista de relleno actualizada

Eliminar una lista de relleno

​

Eliminar una lista de relleno

Parámetros de ruta

  • listId
    Tipo: string
    obligatorio

Respuestas

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

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

Lista de relleno eliminada

Obtener una lista de relleno

​

Obtiene una lista de frases de relleno perteneciente al cliente autenticado.

Parámetros de ruta

  • listId
    Tipo: string
    obligatorio

Respuestas

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

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

Lista de relleno encontrada

Recupera las listas de relleno asociadas con el asistente.

​

Recupera las listas de relleno asociadas con el asistente.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

Asociaciones de lista de relleno

Guarde las listas de relleno asociadas con el asistente.

​

Guarde las listas de relleno asociadas con el asistente.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json
  • toolListIds
    Tipo: array of string
    obligatorio
  • waitingListIds
    Tipo: array of string
    obligatorio

Respuestas

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

Asociaciones de lista de relleno guardadas

RAG

​

Gestión canónica de las colecciones RAG del cliente y sus documentos

RAG Operaciones

Enumera todas las colecciones RAG de los clientes

​

Devuelve todas las colecciones de RAG disponibles para el cliente autenticado.

Utilice esta respuesta para completar name en el PATCH /api/v1/assistants/{assistantApiKey}/runtime/rag.

Parámetros de consulta

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de elementos devueltos en una página con paginación por cursor. Omite limit y cursor para conservar la respuesta legacy sin paginar.

  • cursor
    Tipo: string

    Cursor opaco devuelto en meta.nextCursor por la página anterior.

Respuestas

  • 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": "Colección de demostración de documentación del producto",
        "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": "Colección aún no adjunta a un asistente",
        "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"
      }
    ]
  }
}

Listado completo de las colecciones RAG del cliente, incluso aquellas no asociadas a ningún asistente

Crear una colección RAG

​

Crea una colección RAG del cliente y aprovisiona su colección en el almacén vectorial.

Cuerpo·

obligatorio
application/json

Crea una colección RAG del cliente y aprovisiona la colección correspondiente en el almacén vectorial.

  • name
    Tipo: string
    longitud mín.:  
    1
    obligatorio

    Valor que se debe enviar para name en la solicitud RagCollectionCreateRequest.

  • description
    Tipo: string | null

    Valor que se debe enviar para description en la solicitud RagCollectionCreateRequest.

  • maxChunkSize
    Tipo: integer
    mín.:  
    500
    máx.:  
    10000

    Valor que se debe enviar para maxChunkSize en la solicitud RagCollectionCreateRequest.

  • maxChunksPerFile
    Tipo: integer | null
    mín.:  
    1

    Valor que se debe enviar para maxChunksPerFile en la solicitud RagCollectionCreateRequest.

Respuestas

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

Colección RAG creada

Eliminar una colección RAG

​

Elimina una colección RAG del cliente no utilizada y los metadatos de documentos almacenados.

Parámetros de ruta

  • ragId
    Tipo: string
    obligatorio

    publicRagId estable de la colección RAG. Los valores heredados collectionName y name siguen siendo aceptados.

Respuestas

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

Colección RAG eliminada

Calcule el token y el costo de los archivos RAG antes de cargarlos

​

Calcule el token y el costo de los archivos a cargar, utilizando el mismo cálculo que se muestra desde el portal antes de confirmar la carga.

Envíe archivos como multipart/form-data en el campo repetible files.

Cuerpo

obligatorio
application/json

Respuestas

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

Subir estimación de token

Recuperar el estado de una carga de RAG

​

Utilice uploadId devuelto por la POST de carga para seguir el estado del vectorización, como en el portal.

Parámetros de ruta

  • uploadId
    Tipo: string
    obligatorio

Respuestas

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

Estado de carga actual

Enumera los archivos cargados en una colección RAG

​

Obtiene los archivos de la colección RAG del cliente autenticado.

ragId es el publicRagId estable devuelto por la lista de colecciones. Los valores heredados collectionName y name siguen siendo aceptados.

Parámetros de ruta

  • ragId
    Tipo: string
    obligatorio

    publicRagId estable de la colección RAG. Los valores heredados collectionName y name siguen siendo aceptados.

Parámetros de consulta

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de elementos devueltos en una página con paginación por cursor. Omite limit y cursor para conservar la respuesta legacy sin paginar.

  • cursor
    Tipo: string

    Cursor opaco devuelto en meta.nextCursor por la página anterior.

Respuestas

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

Archivos presentes en la colección RAG.

Cargar archivos en una colección RAG

​

Carga uno o varios archivos en la colección RAG, inicia la vectorización en Chroma y guarda el detalle del archivo para hacerlo visible en los GET posteriores.

Envía los archivos como multipart/form-data en el campo repetible files. ragId es el publicRagId estable devuelto por la lista de colecciones. Los valores heredados collectionName y name siguen siendo aceptados.

Parámetros de ruta

  • ragId
    Tipo: string
    obligatorio

    publicRagId estable de la colección RAG. Los valores heredados collectionName y name siguen siendo aceptados.

Cuerpo

obligatorio
application/json

Respuestas

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

Cargar metadatos aceptados y guardados del archivo

Eliminar un archivo de una colección RAG

​

Elimina el documento del almacén vectorial Chroma y quita el detalle del archivo de la lista de la colección.

ragId es el publicRagId estable devuelto por la lista de colecciones. Los valores heredados collectionName y name siguen siendo aceptados.

Parámetros de ruta

  • ragId
    Tipo: string
    obligatorio

    publicRagId estable de la colección RAG. Los valores heredados collectionName y name siguen siendo aceptados.

  • fileName
    Tipo: string
    obligatorio

    Nombre del archivo a eliminar, tomado de data.documents[].fileName.

Respuestas

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

Archivo eliminado de la colección RAG

Devuelve la configuración RAG actual de un asistente específico

​

Devuelve el estado RAG en tiempo de ejecución del asistente.

Si enabled es true, use el campo name en esta respuesta para completar el PATCH /api/v1/assistants/{assistantApiKey}/runtime/rag cuando quieras conservar, reemplazar o deshabilitar la colección actual.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

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

Configuración de RAG en tiempo de ejecución del asistente

Catalog Tools

​

Herramientas de ejecución disponibles en el lado del cliente y herramientas asociadas con el asistente

Catalog Tools Operaciones

Actualizar enlaces de herramientas asistentes

​

Actualiza las asociaciones de la herramienta asistente con la semántica PATCH merge, replicando el comportamiento del portal.

Parámetros editables:

  • 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 carga útil recomendada es la de alto nivel con su nombre:

  • tools: lista de { toolName, subscriptionName } para agregar
  • deleteTools: lista de { toolName, subscriptionName } para eliminar
  • si agrega un custom_tool, use toolName = toolName y subscriptionName = null
  • si agrega o elimina un plugin_tool, use toolName = toolName y subscriptionName = instanceName
  • si agrega o elimina un custom_mcp_tool, use toolName = toolName y subscriptionName = instanceName

Cómo recuperar valores:

  • para agregar piezas de herramientas desde GET /api/v1/catalog/tools
  • para quitar piezas de herramientas de GET /api/v1/catalog/assistants/{assistantApiKey}/tools
  • siempre reutilice toolName como toolName
  • reutilice siempre instanceName como subscriptionName para objetivos MCP
  • si instanceName y null, la herramienta es un custom_tool clásico y debe enviarse con subscriptionName: null

La carga útil de bajo nivel del portal (toolIds + mcpToolsBySubscription) sigue siendo compatible para mejorar la compatibilidad. En los asistentes voice_to_voice, las herramientas HTTP están escritas en endpointTools y las herramientas MCP en mcpServers en la raíz JSON voice-llm.

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

Carga útil de actualización de asociación de herramientas.

Puede actualizar solo las herramientas clásicas, solo las herramientas MCP o ambas en la misma llamada. Si utiliza forma por nombre, los valores siempre deben tomarse de los catálogos GET documentados anteriormente.

Respuestas

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

Asociaciones de herramientas actualizadas

Enumera todas las herramientas de ejecución del cliente disponibles

​

Devuelve el catálogo completo de herramientas que el cliente puede asociar a un asistente.

Utilice esta respuesta para compilar tools en PATCH /api/v1/assistants/{assistantApiKey}/runtime/tools:

  • reutilizar toolName como toolName
  • si toolType y custom_tool, envíe subscriptionName: null
  • si toolType y plugin_tool, enviar subscriptionName igual a instanceName
  • si toolType y custom_mcp_tool, enviar subscriptionName igual a instanceName

Parámetros de consulta

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de elementos devueltos en una página con paginación por cursor. Omite limit y cursor para conservar la respuesta legacy sin paginar.

  • cursor
    Tipo: string

    Cursor opaco devuelto en meta.nextCursor por la página anterior.

Respuestas

  • 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": "Buscar un cliente potencial en el CRM de la empresa",
        "parameters": null,
        "method": "POST",
        "endpoint": "https://crm.example.com/api/search"
      },
      {
        "toolType": "plugin_tool",
        "toolName": "list_workflows",
        "instanceName": "Marketing",
        "pluginName": "n8n",
        "description": "Enumera los flujos de trabajo disponibles",
        "parameters": {
          "type": "object"
        },
        "method": null,
        "endpoint": null
      },
      {
        "toolType": "plugin_tool",
        "toolName": "execute_workflow",
        "instanceName": "Marketing",
        "pluginName": "n8n",
        "description": "Ejecuta un flujo de trabajo n8n",
        "parameters": {
          "type": "object"
        },
        "method": null,
        "endpoint": null
      },
      {
        "toolType": "custom_mcp_tool",
        "toolName": "search_contact",
        "instanceName": "CRM Custom",
        "pluginName": "CRM Custom",
        "description": "Buscar un contacto en el CRM",
        "parameters": {
          "type": "object"
        },
        "method": null,
        "endpoint": null
      }
    ]
  }
}

Lista unificada de herramientas complementarias, herramientas MCP personalizadas y herramientas personalizadas sin asistenteAPI key como entrada

Enumera las herramientas de tiempo de ejecución asociadas con el asistente.

​

Devuelve las herramientas actualmente asociadas con el asistente.

Utilice esta respuesta para compilar deleteTools en PATCH /api/v1/assistants/{assistantApiKey}/runtime/tools:

  • reutilizar toolName como toolName
  • si toolType y custom_tool, envíe subscriptionName: null
  • si toolType y plugin_tool, enviar subscriptionName igual a instanceName
  • si toolType y custom_mcp_tool, enviar subscriptionName igual a instanceName

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Respuestas

  • 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": "Buscar un cliente potencial en el CRM de la empresa",
        "parameters": null,
        "method": "POST",
        "endpoint": "https://crm.example.com/api/search"
      },
      {
        "toolType": "plugin_tool",
        "toolName": "execute_workflow",
        "instanceName": "Marketing",
        "pluginName": "n8n",
        "description": "Ejecuta un flujo de trabajo n8n",
        "parameters": {
          "type": "object"
        },
        "method": null,
        "endpoint": null
      },
      {
        "toolType": "custom_mcp_tool",
        "toolName": "search_contact",
        "instanceName": "CRM Custom",
        "pluginName": "CRM Custom",
        "description": "Buscar un contacto en el CRM",
        "parameters": {
          "type": "object"
        },
        "method": null,
        "endpoint": null
      }
    ]
  }
}

Lista unificada de herramientas complementarias, herramientas MCP personalizadas y herramientas personalizadas asociadas con el asistente

Catalog RAG

​

Alias heredados de catálogo para las colecciones RAG de clientes y asistentes. Se mantienen solo para compatibilidad con v1.

Catalog RAG Operaciones

Actualizar la configuración del tiempo de ejecución RAG del asistente

​

Actualice la configuración RAG del asistente con la semántica PATCH merge, alineada con el portal.

Parámetros editables:

  • enabled -name -returnedChunks
  • kbPrompt

Cómo recuperar datos:

  • use GET /api/v1/catalog/rag/collections para obtener colecciones RAG disponibles
  • reutilizar name de la colección como name

Reglas operativas:

  • enabled: true habilita RAG y requiere una colección válida
  • enabled: false elimina la base de conocimientos RAG del asistente
  • returnedChunks replica la configuración del portal
  • kbPrompt actualiza las instrucciones de la base de conocimientos del asistente
  • los campos omitidos conservan el valor actual, si está presente
  • en los asistentes voice_to_voice el backend actualiza knowledgeBases en la raíz JSON voice-llm

Parámetros de ruta

  • assistantId
    Tipo: string
    longitud mín.:  
    1
    longitud máx.:  
    128
    obligatorio

    Identificador público del asistente. El assistantId numérico actual es canónico; el valor legacy assistantApiKey sigue aceptándose durante el periodo de compatibilidad v1.

Cuerpo·

obligatorio
application/json

Fusión de PATCH de la configuración RAG del asistente, alineada con el comportamiento del portal.

Reglas operativas:

  • al menos uno de enabled, name, returnedChunks, kbPrompt debe estar presente
  • use GET /api/v1/catalog/rag/collections para recuperar el name
  • enabled: true requiere una colección válida y activa
  • al enviar name con una colección válida, el RAG se activa si no está explícitamente deshabilitado
  • enabled: false elimina la base de conocimientos RAG del asistente y limpia returnedChunks y kbPrompt
  • returnedChunks sigue la configuración del portal y debe estar entre 1 y 10
  • kbPrompt: null elimina las instrucciones de la base de conocimientos del asistente
  • los campos omitidos conservan el valor actual, si ya están presentes
  • enabled
    Tipo: boolean

    Habilite o deshabilite RAG para el asistente. Si es false, se elimina la base de conocimientos de RAG.

  • kbPrompt
    Tipo: string | null

    Instrucciones de la base de conocimientos del asistente. Si es null, el campo se elimina del tiempo de ejecución de LLM.

  • name
    Tipo: string | null

    Nombre de la colección RAG a asociar. Debe recuperarse de GET /api/v1/catalog/rag/collections. Si es null, la selección se restablece.

  • returnedChunks
    Tipo: integer
    mín.:  
    1
    máx.:  
    10

    Número de fragmentos relevantes que se devolverán de la base de conocimientos.

Respuestas

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

Configuración de tiempo de ejecución de RAG actualizada

Account Analytics

​

Historial de llamadas, recargas, RAG, SMS y respuestas de herramientas del cliente autenticado

Account Analytics Operaciones

Recupera el historial de llamadas entrantes del cliente autenticado

​

Devuelve las llamadas entrantes del cliente con detalle de costos y tokens para cada sesión.

Filtros disponibles:

  • startDate y endDate filtran por fecha de creación (createdAt)
  • ambos son opcionales; si se omite, el backend devuelve todo el historial disponible

Cómo leer los costos:

  • todos los costos están en EUR
  • totalCost = llmInputCost + llmOutputCost + ttsCost + asrCost + ragCost + trafficCost + trafficCostOutbound

Parámetros de consulta

  • startDate
    Tipo: stringFormato: date

    Fecha de inicio del filtro (AAAA-MM-DD, incluida)

  • endDate
    Tipo: stringFormato: date

    Fecha de finalización del filtro (AAAA-MM-DD, incluida)

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de registros. Si se omite junto con cursor, conserva el comportamiento no paginado heredado.

  • cursor
    Tipo: string

    Cursor opaco regresado en meta.nextCursor para leer la página siguiente.

Respuestas

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

Historial de llamadas entrantes

Recupera el historial de llamadas salientes del cliente autenticado

​

Devuelve las llamadas salientes del cliente con detalles de los costos de tráfico para cada sesión.

Filtros disponibles:

  • startDate y endDate filtran por fecha de creación (createdAt)
  • internalId filtra una única llamada saliente utilizando el identificador interno generado por AI4Call
  • el filtro de cliente autenticado siempre se aplica, incluso cuando internalId está presente
  • si se omite internalId, el backend devuelve el historial disponible del cliente autenticado

Parámetros de consulta

  • internalId
    Tipo: Formato: uuid

    Filtra por el UUID outbound generado por AI4Call.

    UUID generado por AI4Call para correlacionar la solicitud outbound, el callback y la consulta del estado final de llamada.

  • internal_id
    Tipo: Formato: uuid
    obsoleto

    Alias ​​heredado de internalId.

    UUID generado por AI4Call para correlacionar la solicitud outbound, el callback y la consulta del estado final de llamada.

  • startDate
    Tipo: stringFormato: date

    Fecha de inicio del filtro (AAAA-MM-DD, incluida)

  • endDate
    Tipo: stringFormato: date

    Fecha de finalización del filtro (AAAA-MM-DD, incluida)

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de registros. Si se omite junto con cursor, conserva el comportamiento no paginado heredado.

  • cursor
    Tipo: string

    Cursor opaco regresado en meta.nextCursor para leer la página siguiente.

Respuestas

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

Historial de llamadas salientes

Recupera el historial de llamadas previas a la llamada de MCP del cliente autenticado

​

Devuelve las invocaciones previas a la llamada de MCP del cliente con detalles del token y costos de LLM para cada solicitud.

El MCP previo a la llamada realiza validaciones numéricas y configuraciones de MCP antes de que la llamada se enrute al asistente.

Filtros disponibles:

  • startDate y endDate filtran por fecha de creación (createdAt)
  • ambos son opcionales; si se omite, el backend devuelve todo el historial disponible

Parámetros de consulta

  • startDate
    Tipo: stringFormato: date

    Fecha de inicio del filtro (AAAA-MM-DD, incluida)

  • endDate
    Tipo: stringFormato: date

    Fecha de finalización del filtro (AAAA-MM-DD, incluida)

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de registros. Si se omite junto con cursor, conserva el comportamiento no paginado heredado.

  • cursor
    Tipo: string

    Cursor opaco regresado en meta.nextCursor para leer la página siguiente.

Respuestas

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

Historial de invocaciones previas a la llamada de MCP

Recupera el historial de llamadas posteriores a la llamada de MCP del cliente autenticado

​

Devuelve las invocaciones de MCP posteriores a la llamada del cliente con detalles del token y costos de LLM para cada solicitud.

El MCP posterior a la llamada ejecuta herramientas y automatizaciones después de que se cierra la llamada, utilizando el contexto de la conversación concluida.

Filtros disponibles:

  • startDate y endDate filtran por fecha de creación (createdAt)
  • ambos son opcionales; si se omite, el backend devuelve todo el historial disponible

Parámetros de consulta

  • startDate
    Tipo: stringFormato: date

    Fecha de inicio del filtro (AAAA-MM-DD, incluida)

  • endDate
    Tipo: stringFormato: date

    Fecha de finalización del filtro (AAAA-MM-DD, incluida)

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de registros. Si se omite junto con cursor, conserva el comportamiento no paginado heredado.

  • cursor
    Tipo: string

    Cursor opaco regresado en meta.nextCursor para leer la página siguiente.

Respuestas

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

Historial de invocaciones posteriores a la llamada de MCP

Recuperar el historial de recargas del cliente autenticado

​

Devuelve los movimientos de recarga de crédito del cliente.

Filtros disponibles:

  • startDate y endDate filtran por fecha de creación (createdAt)
  • ambos son opcionales; si se omite, el backend devuelve todo el historial disponible

status valores:

  • completed — recarga completada y crédito acreditado
  • pending — transacción pendiente de confirmación de la puerta de enlace
  • failed — transacción fallida
  • cancelled — transacción cancelada

Parámetros de consulta

  • startDate
    Tipo: stringFormato: date

    Fecha de inicio del filtro (AAAA-MM-DD, incluida)

  • endDate
    Tipo: stringFormato: date

    Fecha de finalización del filtro (AAAA-MM-DD, incluida)

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de registros. Si se omite junto con cursor, conserva el comportamiento no paginado heredado.

  • cursor
    Tipo: string

    Cursor opaco regresado en meta.nextCursor para leer la página siguiente.

Respuestas

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

Historial de recarga

Recupera el historial de consumo de RAG del cliente autenticado.

​

Devuelve el detalle del consumo de incorporación de RAG del cliente, agregado por colección.

Filtros disponibles:

  • startDate y endDate filtran por fecha de creación del registro de consumo (createdAt)
  • ambos son opcionales; si se omite, el backend devuelve todo el historial disponible

Cómo leer los datos:

  • totalToken: total de tokens de inserción procesados para esa colección en el período
  • totalCost — coste total de incorporación en EUR para esa colección en el período
  • fileCount — número de archivos indexados en la colección en el momento del registro

Parámetros de consulta

  • startDate
    Tipo: stringFormato: date

    Fecha de inicio del filtro (AAAA-MM-DD, incluida)

  • endDate
    Tipo: stringFormato: date

    Fecha de finalización del filtro (AAAA-MM-DD, incluida)

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de registros. Si se omite junto con cursor, conserva el comportamiento no paginado heredado.

  • cursor
    Tipo: string

    Cursor opaco regresado en meta.nextCursor para leer la página siguiente.

Respuestas

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

Historial de consumo de RAG

Recupera las busquedas RAG tarifadas del cliente autenticado

​

Devuelve el detalle de las busquedas RAG cobradas al cliente, un registro por busqueda.

Distinto de /api/v1/account/analytics/rag, que cubre el coste de cargar los documentos en las colecciones: este endpoint cubre el coste de consultarlas.

Filtros disponibles:

  • startDate y endDate filtran por fecha de la busqueda (createdAt)
  • ambos son opcionales; si se omiten, el backend devuelve todo el historico disponible

Como leer los datos:

  • queryTokens - tokens de la consulta, la cantidad sobre la que se tarifa la busqueda
  • pricePerTokenNoVat - precio unitario aplicado desde la tarifa del cliente
  • totalCost - importe cobrado, IVA incluido; totalCostNoVat es el mismo importe sin IVA
  • resultCount - chunks devueltos, como maximo 10 por busqueda

Si el cliente nunca ha ejecutado una busqueda tarifada la lista esta vacia.

Parámetros de consulta

  • startDate
    Tipo: stringFormato: date

    Fecha de inicio del filtro (AAAA-MM-DD, incluida)

  • endDate
    Tipo: stringFormato: date

    Fecha de finalización del filtro (AAAA-MM-DD, incluida)

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de registros. Si se omite junto con cursor, conserva el comportamiento no paginado heredado.

  • cursor
    Tipo: string

    Cursor opaco regresado en meta.nextCursor para leer la página siguiente.

Respuestas

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

Historico de las busquedas RAG tarifadas

Recuperar el historial de SMS del cliente autenticado

​

Devuelve mensajes SMS enviados por el cliente a través de asistentes.

Filtros disponibles:

  • startDate y endDate filtran por fecha de envío (createdAt)
  • ambos son opcionales; si se omite, el backend devuelve todo el historial disponible

Cómo leer los datos:

  • usageSms — número de SMS deducidos del crédito de SMS para este mensaje (depende de la longitud del texto)
  • alias — nombre o etiqueta del asistente configurado para el canal SMS

Parámetros de consulta

  • startDate
    Tipo: stringFormato: date

    Fecha de inicio del filtro (AAAA-MM-DD, incluida)

  • endDate
    Tipo: stringFormato: date

    Fecha de finalización del filtro (AAAA-MM-DD, incluida)

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de registros. Si se omite junto con cursor, conserva el comportamiento no paginado heredado.

  • cursor
    Tipo: string

    Cursor opaco regresado en meta.nextCursor para leer la página siguiente.

Respuestas

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

Historial de SMS enviados

Recupera el historial de respuestas de la herramienta del cliente autenticado.

​

Devuelve las respuestas de las herramientas invocadas por los asistentes durante las llamadas.

Filtros disponibles:

  • startDate y endDate filtran por fecha de creación (createdAt)
  • ambos son opcionales; si se omite, el backend devuelve todo el historial disponible

Cómo leer los datos:

  • toolName — nombre de la herramienta invocada (corresponde al name de la herramienta configurada en el asistente)
  • toolCallId — identificador único de la invocación generada por el LLM
  • callUuid — UUID de la llamada telefónica que originó la invocación
  • toolResponse — carga útil de respuesta devuelta por la herramienta; la estructura varía para cada herramienta

Parámetros de consulta

  • startDate
    Tipo: stringFormato: date

    Fecha de inicio del filtro (AAAA-MM-DD, incluida)

  • endDate
    Tipo: stringFormato: date

    Fecha de finalización del filtro (AAAA-MM-DD, incluida)

  • limit
    Tipo: integer
    mín.:  
    1
    máx.:  
    100

    Número máximo de registros. Si se omite junto con cursor, conserva el comportamiento no paginado heredado.

  • cursor
    Tipo: string

    Cursor opaco regresado en meta.nextCursor para leer la página siguiente.

Respuestas

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

Herramienta de historial de respuestas

Public RAG

​

Búsqueda pública de RAG a través de API de clave de cliente

Public RAG Operaciones

Buscar fragmentos en una colección RAG pública

​

Realiza una búsqueda vectorial en una colección RAG utilizando el ID de API público de la colección.

El punto final utiliza el dominio dedicado https://rag.ai4call.com y requiere una clave API del cliente. generado por el portal AI4Call en la sección Seguridad -> Clave API.

El campo rag_id es el ID de API público que se muestra en la interfaz de usuario de administración de RAG, no el ID numérico. base de datos interna. La búsqueda devuelve un máximo de 4 fragmentos.

Cuerpo·

obligatorio
application/json

Solicitud de búsqueda Public RAG aceptada por el servicio RAG dedicado.

  • query
    Tipo: string
    obligatorio

    Texto para buscar semánticamente en la colección RAG

  • rag_id
    Tipo: string
    obligatorio

    ID de API pública de la colección RAG que se muestra en la interfaz de usuario del portal

Respuestas

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

Resultados de búsqueda de RAG

Outbound

​

Webhook para iniciar llamadas salientes con PBX del cliente o troncal AI4Call

Outbound Operaciones

Llamada saliente utilizando la configuración telefónica del cliente

​

Inicia una llamada saliente utilizando la configuración telefónica del cliente.

Hay dos modos disponibles:

  • Modo PBX IP (predeterminado): omite method_uac o establécelo en false, y proporciona ip_pbx y sip_port. ip_pbx debe ser una de las IP públicas autorizadas disponibles en GESTIONE -> Abilita IP.
  • Modo UAC registrado: establece method_uac en true y omite ip_pbx y sip_port.

La clave API del encabezado debe generarse desde el portal en la sección SICUREZZA -> API key.

Cuerpo·

obligatorio
application/json

Respuestas

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

Solicitud de llamada aceptada

Llamada saliente con troncal AI4Call

​

Inicie una llamada saliente utilizando troncales VoIP AI4Call. No requiere configuración de PBX del cliente.

callerId debe ser una demostración o un número AI4Call comprado presente en la cuenta. Puede ver la demostración y los números comprados en NUMERI AI4Call -> Routing.

La clave API en el encabezado debe ser generada por el portal en la sección SICUREZZA -> API key.

Cuerpo·

obligatorio
application/json

Respuestas

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

Solicitud de llamada aceptada

Recuperar el estado almacenado de una llamada outbound

​

Recupera el CDR outbound final usando el internal_id recibido en el callback de resultado.

El callback puede llegar cuando duration es 0; los clientes pueden repetir esta solicitud hasta que el CDR se haya almacenado. La clave API debe pertenecer al cliente que inició la llamada outbound.

Parámetros de ruta

  • uuid
    Tipo: Formato: uuid
    obligatorio

    Identificador interno outbound recibido en el callback.

    UUID generado por AI4Call para correlacionar la solicitud outbound, el callback y la consulta del estado final de llamada.

Respuestas

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

Estado almacenado de la llamada outbound

Modelos

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