Saltar al contenido principal
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. 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.
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.
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 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.