Usa el contrato OpenAPI para generar un cliente de integración. La API pública, el panel y el endpoint de gestión MCP operan sobre los mismos recursos y permisos del espacio de trabajo.
| Capacidad | Endpoint |
|---|---|
| Herramientas reutilizables | GET / POST /api/v1/voice/tools |
| Leer / actualizar / eliminar una herramienta | GET / PATCH / DELETE /api/v1/voice/tools/{id} |
| Previsualizar o probar una herramienta | POST /api/v1/voice/tools/{id}/test |
| Vincular herramientas a un agente | PUT /api/v1/voice/agents/{id}/tools |
| Bases de conocimiento | GET / POST /api/v1/voice/knowledge-bases |
| Leer / actualizar / eliminar una base de conocimiento | GET / PATCH / DELETE /api/v1/voice/knowledge-bases/{id} |
| Añadir / listar documentos | POST / GET /api/v1/voice/knowledge-bases/{id}/documents |
| Leer / eliminar un documento | GET / DELETE /api/v1/voice/knowledge-bases/{id}/documents/{doc_id} |
Activa o desactiva un documento (enabled), o la relectura semanal de una página (sync) | PATCH /api/v1/voice/knowledge-bases/{id}/documents/{doc_id} |
| Añade un sitio web entero, un documento por página | POST /api/v1/voice/knowledge-bases/{id}/site |
| Suscripciones a eventos de llamada | GET / POST /api/v1/voice/webhooks |
| Leer / actualizar / eliminar una suscripción | GET / PATCH / DELETE /api/v1/voice/webhooks/{id} |
| Enviar un evento de prueba firmado | POST /api/v1/voice/webhooks/{id}/test |
| Descubrir herramientas MCP remotas | POST /api/v1/voice/mcp/discover |
| Endpoint de gestión MCP | /api/v1/voice/mcp |
Registra una herramienta HTTP que consulta tu adaptador de CRM:
{
"name": "lookup_customer",
"description": "Find a customer after confirming their customer ID.",
"kind": "http",
"url": "https://crm.example.com/customers/{{customer_id}}",
"method": "GET",
"read_only": true,
"credential_ref": "crm",
"input_schema": {
"type": "object",
"properties": { "customer_id": { "type": "string" } },
"required": ["customer_id"],
"additionalProperties": false
},
"response_path": "data"
}
POST /tools devuelve { "data": { "id": "TOOL_ID", ... } }. Vincula su definición a un agente con PUT /agents/AGENT_ID/tools y { "tool_ids": ["TOOL_ID"] }. Esto sustituye toda la lista de herramientas por instantáneas; vuelve a vincular cuando cambie una herramienta de la biblioteca. Eliminar una definición de la biblioteca conserva las instantáneas existentes. También puedes leer y sustituir definiciones en línea con el campo tools de la API de agentes. Usa analysis_config y widget_config para configurar el análisis y el widget mediante la API de agentes.
Una herramienta puede usar GET, POST, PUT, PATCH o DELETE. query y request_body aceptan plantillas JSON anidadas como { "customer": { "id": "{{customer_id}}" } }. Un marcador completo conserva el tipo JSON original. Los marcadores de la URL se codifican y solo pueden aparecer después de un host HTTPS público fijo. Sin request_body, las herramientas que no son GET reciben { "arguments": {...}, "call": { "callId": "...", "agentId": "...", "toolCallId": "...", "idempotencyKey": "..." } }. response_path selecciona un campo con notación de puntos. Los parameters simples se siguen aceptando; input_schema admite además objetos anidados, arrays, enumeraciones y límites numéricos. No se aceptan referencias a esquemas externos ni expresiones regulares.
static_args: valores enviados en cada llamada escriba lo que escriba el modelo, como un id de tienda; también rellenan {{name}} en la dirección y el cuerpo.extract: [{name, path}] conserva campos de la respuesta de una función (data.id) para el {{name}} de funciones posteriores, de modo que el customer_id de una consulta pueda pasar al pedido siguiente sin que el modelo lo repita. Los campos de una consulta de inicio se conservan igual.reject_when: hasta 5 reglas {on: caller|agent, pattern, negate}; mientras todas se cumplan en las últimas palabras, la función no se ejecuta y el agente recibe reject_message.model_says: en cada llamada, el modelo escribe una frase que se dice mientras la función se ejecuta, en lugar del speak_before fijo.Conecta una app en Integraciones → Webhooks y notificaciones → Apps conectadas y después usa «Añadir una función predefinida» en la pestaña Conocimiento y herramientas del agente; no necesitas ningún endpoint propio:
check_availability (horas libres en una fecha) y book_appointment (reserva la hora que eligió quien llama). Las horas de Google Calendar siguen la zona horaria, los días de apertura, el horario y la duración de cita que definas; Cal.com usa la disponibilidad propia del tipo de evento, y un correo de reserva que definas cuando quien llama no da ninguno.save_to_sheet, que añade una fila con las columnas que indiques, más el ID y la hora de la llamada.notify_team, que publica en un canal de Slack (incoming webhook) un mensaje que escribe el agente.lookup_order, que informa a quien llama de su pedido solo cuando da el número y el email, teléfono o código postal del pedido (tras tres intentos fallidos, no más en esa llamada), y search_products (productos activos, precios, existencias). Los pedidos se leen en vivo de la tienda y no se guardan; el enlace a la página de estado del pedido puede enviarse como tarjeta.cancel_order (un pedido aún no enviado, con reembolso de lo pagado), change_shipping_address (para un pedido aún no enviado) y refund_order (todo o parte de un pedido); todos están desactivados por defecto. Quien llama demuestra primero que el pedido es suyo, como en lookup_order. Por defecto, un miembro del equipo aprueba cada solicitud en la bandeja de entrada antes de que cambie nada en la tienda; también puedes dejar que el agente haga uno al momento. Un reembolso por encima del límite que fijes siempre espera a un miembro del equipo. Shopify avisa al cliente por correo de una cancelación o un reembolso. La primera vez, el propietario de la tienda permite los cambios de pedidos en Shopify.add_to_cart, view_cart y, si indicas un código de descuento que ya existe en Shopify, apply_discount. Se ejecutan en el navegador del visitante en la página de tu tienda, solo cambian su carrito y nunca se ofrecen por teléfono. El agente puede enviar el enlace de pago y productos como tarjetas. search_products muestra las variantes de cada producto con el id que usa el carrito.track_shipment, que dice al cliente dónde está su paquete, el último escaneo y cuándo debería llegar, a partir del número de seguimiento (lo da lookup_order). Con AfterShip conectado, la bandeja también muestra el estado de cada paquete junto a los pedidos. Se conecta con una clave API de AfterShip.return_status, que dice al cliente cómo va la devolución que inició (reembolso o cambio, estado de la etiqueta) cuando da el número de pedido y el correo del pedido; tres intentos fallidos lo terminan para la llamada. Se conecta con una clave API de Loop con el permiso Returns.lookup_subscriptions (qué recibe el cliente, cada cuánto, el precio y la próxima entrega) cuando da el correo y el código postal o teléfono de su cuenta; tres intentos fallidos lo terminan para la llamada. Activa skip_next_delivery, change_next_delivery_date (hasta un año) y cancel_subscription uno a uno; todos están desactivados por defecto y, como los cambios de pedido, esperan la aprobación de un miembro del equipo en la bandeja, salvo que dejes que el agente los haga al momento. Se conecta con un token de API de Recharge.El plano de control de EvaSay ejecuta estas funciones con la cuenta que conectaste; ni el worker ni la definición del agente guardan las credenciales de la app. Al leer un agente con la API, aparecen como kind: "app" (con app, action, connection_id, app_config); devuélvelas sin cambios al sustituir tools para conservarlas. Las apps se conectan solo desde el panel.
Define run_at_start: true en una de las herramientas de un agente y se llamará al empezar cada llamada, antes de que el agente salude o responda. Los parámetros llamados caller_number, called_number, direction, channel o call_id se rellenan por ti. Los campos que devuelve rellenan {{variables}} en first_message, system_prompt e idle_messages (los campos un nivel más abajo, como {{customer.name}}), y la respuesta completa se entrega al agente como contexto. Un saludo con variables espera hasta 3 segundos la respuesta; lo que no se encuentre queda en blanco. Solo una herramienta por agente puede ejecutarse al inicio.
Las credenciales se configuran en el entorno del servidor para tu espacio de trabajo y destino; pide a support@evasay.com que aprovisione un credential_ref. No pongas claves de API en las definiciones de agente, cabeceras, prompts ni parámetros de herramientas. Tu adaptador puede guardar las credenciales del CRM en su propio entorno.
Previsualiza una herramienta antes de hacer solicitudes al sistema de negocio:
{
"arguments": { "customer_id": "customer-123" },
"dry_run": true,
"mock_result": { "name": "Alex", "order_status": "shipped" }
}
Una vista previa valida los parámetros y muestra la solicitud resultante; no ejecuta una conversación ni contacta con el sistema de negocio. Define dry_run=false para una ejecución real. Una prueba de escritura real también exige confirmed=true e idempotency_key (8–128 letras, números, puntos, guiones bajos, dos puntos o guiones). Las respuestas de prueba incluyen ok, status, duration_ms y un resultado acotado. No devuelven credenciales. Las pruebas de lectura y escritura requieren permiso de escritura en el espacio de trabajo.
Durante una llamada, las solicitudes de negocio llevan un Idempotency-Key estable. Tu endpoint de negocio debe respetarlo. Las escrituras idénticas dentro de una llamada se deduplican, incluidas las operaciones con resultado desconocido tras un tiempo de espera agotado. Una operación distinta e intencionada necesita un argumento de negocio distinto, como operation_id. EvaSay no reproduce escrituras automáticamente. Los eventos de ejecución de herramientas incluyen estado y duración; la función de prueba de conversación sigue siendo una simulación de texto, no una prueba de ejecución de herramientas.
POST /mcp/discover acepta { "url": "https://crm.example.com/mcp", "credential_ref": "crm" } y devuelve las herramientas y los esquemas del servidor. Registra solo la herramienta seleccionada:
{
"name": "lookup_customer",
"description": "Find a CRM customer by confirmed ID.",
"kind": "mcp",
"url": "https://crm.example.com/mcp",
"mcp_tool": "get_customer",
"credential_ref": "crm",
"read_only": true,
"input_schema": {
"type": "object",
"properties": { "customer_id": { "type": "string" } },
"required": ["customer_id"]
}
}
Solo las herramientas registradas quedan disponibles para el agente. Las conexiones remotas admiten Streamable HTTP con respuestas JSON o SSE a las solicitudes, destinos HTTPS públicos y credenciales preconfiguradas. No se admiten los endpoints SSE heredados, la negociación OAuth, el muestreo ni la elicitación iniciados por el servidor, ni los adjuntos binarios. El descubrimiento no concede automáticamente acceso a todas las herramientas del servidor. El esquema de la herramienta remota debe estar en línea y usar el subconjunto admitido de JSON Schema.