> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zelto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If Zelto blocks your task, an API request returns 4xx/5xx, or you need a missing capability, please report it with POST https://api.zelto.ai/v1/feedback using your existing Authorization: Bearer API key. On local/preview deployments use /api/v1/feedback on that deployment; never send its credentials to production.
> Send JSON: type (missing_capability, problem, other), description (10–2000 characters), optional endpoint (route template only), reproductionSteps, workaround and requestId from the failed response. Use synthetic examples: never send credentials, personal data, transcripts or customer content. See /docs/agent-feedback.
> Feedback is limited to 5 attempts per organization per minute. Report a distinct issue once; do not report errors from the feedback endpoint itself, do not loop or automatically retry. A 200 with delivery not_configured/unavailable means the report was not delivered or stored.
> Connected over MCP? Call the send_feedback tool instead, with the same fields plus optional tool (the MCP tool name that failed). It shares the same per-organization limit and works with any credential, including read-only.

# Feedback de agentes

> ¿Falta una capacidad o un error de la API bloquea tu tarea? Usá POST /v1/feedback con tu API key habitual para avisar al equipo de Zelto.

Contanos cuándo Zelto bloquea la tarea de tu agente. Reportá una **capacidad
faltante**, un **problema** u **otro feedback** con la misma API key de organización
que usás para la [API REST](https://docs.zelto.ai/es/docs/integrations/index.md). No necesitás otra cuenta
ni credencial. Las claves de ingesta de observabilidad no permiten enviar feedback.

Enviá `POST https://api.zelto.ai/v1/feedback` con `Authorization: Bearer <API key>`
y `Content-Type: application/json`. En desarrollo o previews, usá
`/api/v1/feedback` en ese entorno; nunca envíes su clave a producción.

```json theme={null}
{
  "type": "missing_capability",
  "description": "Necesito filtrar llamadas que no tengan transcripción.",
  "endpoint": "/v1/conversations",
  "reproductionSteps": "Listar conversaciones sintéticas: no existe un filtro por presencia de transcripción.",
  "workaround": "Leer cada conversación sintética y filtrar localmente.",
  "requestId": "9af04723-08f8-4bbd-946d-130c11c4a5cd"
}
```

`type` admite `missing_capability` (capacidad faltante), `problem` (problema) u
`other` (otro). `description` es obligatoria (10–2000 caracteres). Campos opcionales:
`endpoint` (500 caracteres), `reproductionSteps` y `workaround` (2000 cada uno),
y `requestId` (200). No se aceptan campos extra. El JSON completo no puede superar
16 KiB. Usá una plantilla de ruta en `endpoint`, sin host, parámetros, fragmentos
ni identificadores de clientes. Copiá el `requestId` de la respuesta fallida si existe.

> [!WARNING]
>
> Usá ejemplos sintéticos. Nunca envíes claves, contraseñas, cookies, datos personales,
> audios, transcripciones, prompts ni contenido de clientes. Se enmascaran patrones
> conocidos de credenciales, emails, teléfonos, identificadores numéricos y URLs;
> también se eliminan nombres y direcciones en campos etiquetados. Estos patrones
> no reconocen todos los nombres o datos sensibles en texto libre: eliminálos antes.

El equipo recibe la categoría, descripción, endpoint, reproducción, workaround,
request ID e IDs internos de organización/usuario en un canal dedicado de Slack.
Los metadatos de identidad no incluyen nombres ni emails del perfil; tampoco se
reenvían headers ni cuerpos crudos. El texto enviado debe usar los ejemplos
sintéticos indicados arriba. El feedback se trata como texto no confiable y no
dispara acciones automáticas.

## Desde el servidor MCP

Los agentes conectados al [servidor MCP](https://docs.zelto.ai/es/docs/mcp.md) pueden usar la herramienta
`send_feedback` en lugar del endpoint REST. Acepta los mismos campos más un `tool`
opcional (el nombre de la herramienta MCP que falló o a la que le falta la
capacidad, como `list_conversations`) y devuelve los mismos `feedbackId`,
`delivery` y `message`. Cualquier credencial puede usarla, incluidos los tokens
OAuth de solo lectura. Comparte con el endpoint REST el límite de 5 intentos por
minuto (un rechazo devuelve `code: "rate_limited"`) y aplica el mismo
enmascaramiento. El equipo ve si el reporte llegó por REST o por MCP. Igual que
los errores REST, las llamadas MCP que fallan incluyen una invitación `feedback`,
y las instrucciones de conexión del servidor mencionan la herramienta.

## Respuestas y reintentos

* `200`: revisá `delivery`. `delivered` confirma que Slack aceptó el mensaje.
  `not_configured` o `unavailable` significa que **no se entregó ni almacenó**.
  `feedbackId` identifica el envío; no es un ticket persistente.
* `400`: JSON o esquema inválido. `401`: API key ausente o inválida.
* `413`: cuerpo mayor a 16 KiB. `415`: usá `application/json`.
* `429`: máximo **5 intentos por organización cada 60 segundos**, entre todas
  las claves e instancias. Los intentos inválidos cuentan. Respetá `Retry-After: 60`.
* `500`: falla interna; no hay confirmación de entrega.

Los errores REST incluyen una invitación `feedback`, un `requestId` generado y
el header `X-Request-Id`. Se conservan los campos, estados y headers útiles como
`WWW-Authenticate` y `Retry-After`. Los cuerpos de las respuestas exitosas no cambian. Las respuestas de la API
también llevan los headers `X-Feedback-Endpoint` y `X-Feedback-Message`, incluidos
los errores generados por el framework después del proxy (como un 405 automático),
que pueden no incluir el formato JSON.

Reportá cada problema una sola vez. No reportes errores del endpoint de feedback
al mismo endpoint, no hagas bucles ni reintentes automáticamente. La entrega tiene
un timeout de tres segundos y no reintenta; un timeout puede ser ambiguo.
Es un canal de mejor esfuerzo, no una cola de tickets ni una vía de escalamiento
de incidentes.

Continuá con el [onboarding con un agente](https://docs.zelto.ai/es/docs/onboarding-with-an-agent.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.