> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Herramientas y webhooks
> Permite que los asistentes usen herramientas durante una conversación, y envía los resultados de las llamadas a tus sistemas mediante webhooks
Los asistentes pueden usar herramientas durante una conversación para consultar información o realizar una acción. Cuando una llamada o conversación termina, Famulor puede enviar el resultado a tus sistemas mediante un webhook.
## Herramientas reutilizables del asistente
Crea las herramientas una vez en la página **Tools**, y luego asígnalas en **Assistant → Settings → Tools** o añádelas a un Flow. Actualizar una herramienta reutilizable actualiza todas sus asignaciones.
### Herramientas de API
Las herramientas de API llaman a un endpoint HTTP durante la conversación. Define:
* el endpoint y la autenticación,
* los datos que el asistente debe recopilar,
* cualquier valor fijo,
* qué debe contener la respuesta, y
* si quien llama debe escuchar una breve frase de progreso.
Usa descripciones claras y devuelve solo los datos que el asistente necesita para continuar la conversación. La descripción de una herramienta también decide *cuándo* el asistente recurre a ella — indica con claridad la condición que la activa ("usa esto cuando quien llama pregunte por un pedido existente") en lugar de describir solo lo que hace la herramienta.
| Método | Úsalo para |
| -------- | ---------------------------------------------------------------- |
| `GET` | Obtener datos — una consulta, una comprobación de disponibilidad |
| `POST` | Crear algo nuevo — un pedido, un ticket, una reserva |
| `PUT` | Reemplazar por completo un registro existente |
| `PATCH` | Actualizar campos específicos de un registro existente |
| `DELETE` | Eliminar algo |
Las solicitudes agotan el tiempo de espera a los 10 segundos de forma predeterminada (configurable hasta 120), y una respuesta de más de 2 MB se rechaza — mantén los endpoints rápidos y las respuestas pequeñas. Usa una clave de API con alcance limitado y el mínimo privilegio necesario en lugar de una credencial maestra, y mantén los datos identificativos del cliente fuera de cualquier mensaje de error que el asistente pueda leer en voz alta.
Crea una herramienta de API cuando la respuesta cambia con frecuencia y el endpoint responde rápido y de forma fiable. Si la información apenas cambia, una [base de conocimientos](/es/assistants/knowledge-base) o el prompt del sistema resulta más económico y no puede fallar a mitad de la llamada.
**Ejemplos de configuración**
Cada valor que recopila el asistente es un parámetro con nombre y una descripción que le indica qué pedir. Los parámetros viajan en la cadena de consulta en `GET` y `DELETE`, y en el cuerpo JSON en `POST`, `PUT` y `PATCH`. Para colocar uno en la ruta en su lugar, escribe `{{parameter_name}}` en la URL del endpoint. Configura el origen de un parámetro como **Static** para un valor fijo que el asistente nunca tiene que preguntar, y guarda las credenciales en **Headers**.
| Patrón | Método | Cómo configurarlo |
| ---------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------- |
| Buscar por ID | `GET` | Endpoint `.../orders/{{order_number}}`, con `order_number` como parámetro que recopila el asistente |
| Crear algo | `POST` | Endpoint `.../appointments`, con `date` y `service` como parámetros — se envían en el cuerpo JSON |
| Comprobar antes de continuar | `GET` | Endpoint `.../customers/lookup`, con `phone` y `email` como parámetros — se envían como valores de consulta |
| Solo notificar | `POST` | Endpoint `.../notify` solo con parámetros estáticos; el asistente simplemente confirma que transmitió el mensaje |
El asistente lee la respuesta y responde con sus propias palabras, así que devuelve campos cortos y con nombres claros (`ship_date`, `confirmed_time`) en lugar de un objeto profundamente anidado que tenga que interpretar.
### Agent Connector de Perplexity
Abre **Tools → Agent Connectors**, elige **Perplexity AI** y pega tu propia clave de API. Selecciona **Load models** para validar la clave y obtener los modelos actualmente disponibles para tu cuenta. El mismo selector de modelos está disponible después en **Edit** y recarga el catálogo usando la clave almacenada de forma segura. Puedes añadir un prompt del sistema opcional y ajustar la temperatura (`0.2` por defecto), Top P (`0.9`), la penalización por presencia (`0`) y la penalización por frecuencia (`1`). El máximo de tokens está vacío de forma predeterminada y se omite de las solicitudes hasta que le asignes un valor. El prompt del sistema controla el tono, el idioma, el estilo y el formato de la respuesta; el asistente sigue aportando la solicitud de investigación completa en tiempo de ejecución. La clave guardada aparece enmascarada y la API de herramientas nunca la devuelve.
### Servidores MCP externos
Conecta un servidor MCP introduciendo su URL y, cuando haga falta, los datos de autenticación. Puedes permitir todas las herramientas ofrecidas o seleccionar solo las que un asistente puede usar. Recurre a esto cuando el otro lado ya expone todo un conjunto de herramientas MCP — conectarte una vez trae consigo todas las herramientas que ofrece; para un único endpoint HTTP, una herramienta de API sencilla como la anterior suele ser más simple.
Una URL que termina en `/mcp` se trata como Streamable HTTP y una que termina en `/sse` como SSE clásico; cualquier otra prueba primero Streamable HTTP y luego recurre a SSE. La autenticación puede ser **none**, un **static header or bearer token**, u **OAuth** — cuando el servidor admite OAuth, Famulor ejecuta el flujo de inicio de sesión y almacena el token resultante.
La lista Installed muestra el resultado de la última ejecución y marca las conexiones que necesitan atención. Si OAuth caduca, elige **Reauthorize** en la herramienta existente. El flujo de inicio de sesión repara esa herramienta en el sitio, por lo que se conservan las asignaciones, las herramientas permitidas, la configuración y el historial de ejecuciones.
Para cada herramienta seleccionada, **Execution behavior** te permite controlar la cancelación, las llamadas simultáneas y los avisos de progreso hablados. Cancelar no puede deshacer una acción que el servicio externo ya haya completado.
Conecta solo servicios de confianza. Sus descripciones de herramientas, resultados y mensajes de progreso pueden influir en la conversación.
### Herramientas integradas
Las herramientas integradas cubren acciones habituales como transferencia de llamada, transferencia a otro asistente, SMS, correo electrónico, comprobación de horario comercial, devoluciones de llamada, entrada por teclado, recopilación de datos de tarjeta de pago, variables y finalización de llamada.
## Gestionar herramientas mediante la API
Usa la API pública para automatizar la gestión de herramientas:
* `GET /api/v1/tools` y `POST /api/v1/tools`
* `POST /api/v1/tools/perplexity/models` para listar los modelos disponibles con una clave de API proporcionada o con el ID de un conector existente
* `GET /api/v1/tools/{id}`, `PATCH /api/v1/tools/{id}` y `DELETE /api/v1/tools/{id}`
* `POST /api/v1/tools/{id}/reauthorize` para recibir una URL de inicio de sesión de navegador de corta duración para una herramienta MCP OAuth existente
* `GET /api/v1/assistants/{id}/tools` y `PUT /api/v1/assistants/{id}/tools`
* `GET /api/v1/assistants/{id}/automations`, `POST /api/v1/assistants/{id}/automations` y `DELETE /api/v1/assistants/{id}/automations/{automationId}`
El [endpoint de MCP](/es/api/mcp) conectado ofrece operaciones equivalentes para herramientas de asistente, incluidas `reauthorize_tool` y `list_perplexity_models`. Las respuestas de lista de herramientas incluyen el estado de la conexión sin secretos y el resultado de la última ejecución. Los valores de autenticación secretos se enmascaran después de guardarse.
Para una [automatización](/es/automations/overview) que el asistente deba poder llamar durante una conversación, usa el endpoint de automatización de asistente o la herramienta MCP `create_assistant_automation`. Proporciona una descripción precisa de cuándo debe ejecutarse. La misma asignación está disponible en conversaciones de voz, chat web, mensajería y correo electrónico. La plataforma crea un flujo de trabajo en borrador y conecta de forma segura la herramienta necesaria sin devolver credenciales. Construye sus pasos, devuelve un resultado conciso adecuado para respuestas habladas o escritas, y pon la automatización en Live cuando esté lista; pausarla también desactiva la herramienta invocable en todas partes. Estas herramientas generadas se muestran como gestionadas por la automatización y solo se pueden editar o desconectar desde Assistant settings. Los reintentos conversacionales reutilizan la misma ejecución y respuesta, así que no repiten la facturación ni los efectos secundarios.
## Recibir resultados de llamada mediante webhooks
Cuando una llamada termina, Famulor envía su resultado a la URL de webhook configurada en el asistente (**Settings → Automations → Call completed**). La URL no va firmada y pertenece a ese único asistente. Los ajustes de entrega por asistente — tiempo de espera, número de reintentos y un envío de prueba — se gestionan en [Webhooks posteriores a la llamada](/es/assistants/webhooks).
Los hilos de correo reutilizan la misma URL del asistente: en cuanto el asistente responde, Famulor entrega ahí un evento `conversation.ended` con la transcripción del hilo y su análisis. Telegram, Slack y los demás conectores de mensajería tienen en su lugar su propia **Conversation ended webhook URL**, configurada por conector — consulta [Canales de mensajería](/es/channels/messaging).
La firma funciona de otra forma para el **webhook de variables** entrante — la URL por asistente que Famulor llama al inicio de una llamada entrante para enriquecer variables. Esa solicitud lleva una firma HMAC-SHA256; consulta [Variables personalizadas](/es/assistants/variables#webhook-de-variables-entrante).
### `call.completed`
El evento incluye datos de llamada orientados al cliente, como asistente, dirección, estado, duración, marcas de tiempo, transcripción, variables del Flow recopiladas, contexto de campaña y enlaces de grabación disponibles.
Si la llamada no puede completarse, el payload incluye un objeto `failure` independiente del proveedor con un código estable, un mensaje seguro para el cliente, una indicación de reintento y una acción sugerida. Construye tu lógica de recuperación a partir de este objeto en lugar de depender de detalles específicos de la infraestructura.
Devuelve una respuesta `2xx` correcta cuanto antes. Procesa el trabajo de seguimiento más largo después de confirmar la recepción del webhook.
## Consultar en lugar de recibir un webhook
Puedes obtener el mismo resultado de llamada con `GET /api/v1/calls`, `GET /api/v1/calls/{id}`, o las herramientas de historial de llamadas en [MCP](/es/api/mcp). Una llamada recién creada devuelve inicialmente su estado actual; consúltala hasta que alcance un estado final.