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

# API de tickets y escalaciones

> Descubre trabajo pendiente, gestiona responsables humanos y concilia acciones de agentes.

Tickets está disponible para los espacios incluidos en el despliegue gradual. Los espacios activados permiten consultar y modificar según los permisos indicados; no existe un modo de solo lectura independiente. Los espacios desactivados devuelven `TICKETS_UNAVAILABLE`. Desactivar la función conserva los elementos y su historial; el acceso se recupera al volver a activarla.

## Elementos y ciclo de vida

Los tickets generales y las escalaciones son elementos persistentes vinculados a una conversación. Pueden coexistir varios tickets con una escalación sin resolver. Las revisiones manuales anteriores aparecen como tickets con sus mismos identificadores e historial, sin copiar registros. `requested` corresponde a `pending`; `active` corresponde a `in_progress`.

Leer, asignar o responder no inicia el trabajo. Debes pulsar **Empezar trabajo** o llamar a su operación. Un agente debe asignar una persona activa del equipo antes de iniciar un elemento sin responsable. Una persona que inicia un elemento sin responsable se lo asigna. Los tickets tienen un responsable independiente de la conversación; las escalaciones siguen al responsable de la conversación.

Los tickets abiertos permiten editar título/descripción, asignar, añadir notas internas, iniciar, resolver o cancelar. Se pueden resolver o cancelar directamente desde Pendiente. Los elementos cerrados siguen siendo legibles, pero no se pueden reabrir, modificar ni eliminar permanentemente. Prioridades, fechas límite, recordatorios, tickets sin conversación y agentes como responsables quedan fuera de v1.

Las operaciones de tickets generales no cambian el modo de IA, el estado de lectura ni la atención de respuesta. Aceptar una escalación pausa la IA e invalida respuestas pendientes con la persistencia, notificaciones y facturación canónicas de escalaciones. Resolver el caso exacto permite volver a responder a la IA, sujeto a otras restricciones. Resolver cualquiera de los dos tipos no envía mensajes ni elimina una obligación de respuesta separada.

## Rutas y herramientas MCP

Las rutas son relativas a `/m2m/v1`. El dashboard y las aplicaciones móviles usan los mismos servicios de dominio.

| Método y ruta | Herramienta MCP | Permiso necesario |
| - | - | - |
| GET /tickets | list\_tickets | tickets:read |
| GET /tickets/{ticketId} | get\_ticket | tickets:read |
| GET /tickets/{ticketId}/events | list\_ticket\_events | tickets:read |
| GET /tickets/requests/{requestId} | get\_ticket\_request\_status | tickets:read |
| POST /tickets | create\_ticket | tickets:write |
| PATCH /tickets/{ticketId} | update\_ticket | tickets:write |
| PUT /tickets/{ticketId}/assignment | assign\_ticket | tickets:write |
| POST /tickets/{ticketId}/notes | add\_ticket\_note | tickets:write |
| POST /tickets/{ticketId}/start | start\_ticket | tickets:write |
| POST /tickets/{ticketId}/resolve | resolve\_ticket | tickets:write |
| POST /tickets/{ticketId}/cancel | cancel\_ticket | tickets:write |
| POST /escalations | create\_escalation | conversations:handoffs:create |
| PUT /escalations/{ticketId}/assignment | assign\_escalation | conversations:assignment:write |
| POST /escalations/{ticketId}/notes | add\_escalation\_note | conversations:handoffs:write |
| POST /escalations/{ticketId}/start | start\_escalation | conversations:handoffs:write |
| POST /escalations/{ticketId}/resolve | resolve\_escalation | conversations:handoffs:write |

`tickets:read` permite ver ambos tipos. No concede acceso a transcripciones, mensajes, política, comprobantes de acciones o entregas. Estas consultas conservan sus permisos existentes. Un contexto denegado debe declararse como permiso denegado; una fuente no disponible no equivale a evidencia vacía. Las respuestas incluyen `contextStatus`, identificadores y procedencia, no transcripciones completas.

## Creación y mutaciones seguras

Crear requiere `conversationId`, `title` no vacío (máximo 160 caracteres) e `Idempotency-Key`. Descripción y negocio son opcionales. Los tickets generales aceptan un `operatorId` humano y `sourceMessageId` almacenado opcionales; su descripción admite 2.000 caracteres. La descripción de escalación admite 800. Asigna al responsable humano de la escalación después con la operación independiente de asignación.

```json theme={null}
{
  "conversationId": "identificador-de-conversacion",
  "title": "Comprobar el documento solicitado",
  "description": "Confirmar la información antes de responder.",
  "operatorId": "identificador-de-persona-activa"
}
```

Las mutaciones posteriores usan el `ticketId` exacto y su `revision` entera actual. Las ediciones necesitan al menos un campo editable. Asignación acepta un identificador humano o null para quitarlo. Las notas son internas y necesitan `note` no vacío. Las revisiones avanzan de forma atómica; un estado obsoleto devuelve HTTP 409. Vuelve a leer y decide de nuevo. La auditoría identifica al agente por su credencial/concesión OAuth y no suplanta a una persona.

La clave de creación vincula espacio, actor y entrada exacta. Una respuesta de escalación incierta incluye `requestId`. Consulta `get_ticket_request_status` antes de repetir. `processing` y `reconciliation_required` no confirman finalización. Si existe un identificador, inspecciona el elemento y su control de la conversación. No crees otra escalación para sustituir una operación incierta. La recuperación conserva el control aceptado y concilia la facturación y el comprobante según el procedimiento operativo.

## Descubrimiento, vigencia e historial

Las listas aceptan `type`, `status`, `owner` (all, unassigned o identificador humano), `propertyId`, `channel`, `conversationId`, `updatedSince`, `limit` y `cursor`. Página predeterminada: 25; máximo: 100. La credencial fija el espacio; no admite parámetros para cambiarlo. Las respuestas incluyen `asOf`, conteos por estado bajo los demás filtros, `hasMore` y `nextCursor`. Las listas son vivas: los cambios pueden mover elementos entre páginas. Continúa con los mismos filtros y concilia el elemento exacto por revisión.

El detalle incluye tipo, estado, título, descripción, revisión, fechas, responsable humano, identificadores de origen, procedencia y `permittedActions`. Una escalación también incluye motivo guardado, campos capturados/pendientes, `ownershipActive` y consecuencias de resolución. Las notas y eventos tienen paginación independiente; no se incluye toda la conversación.

## Flujo de un agente

1. Descubre con `list_tickets` y continúa las páginas restantes.
2. Inspecciona `get_ticket` y `list_ticket_events`; consulta conversación, mensajes, política, comprobantes y pruebas de entrega con sus herramientas y permisos existentes.
3. Selecciona una persona con `list_assignable_operators` y la operación de asignación correspondiente.
4. Lee de nuevo la revisión y llama explícitamente a `start_ticket` o `start_escalation`.
5. Añade notas internas con evidencia y siguiente paso. Enviar respuestas requiere herramientas y autorización independientes.
6. Resuelve cuando el trabajo esté terminado. Resolver una escalación permite respuestas de IA sujeto a otras restricciones.
7. Lee de nuevo el elemento exacto y, cuando corresponda, la política/entrega. Concilia conflictos y resultados inciertos antes de otra escritura.

## Eventos y compatibilidad

`ticket.created` y `ticket.updated` reutilizan outbox persistente, reintentos/DLQ de RabbitMQ y entrega/recuperación de webhooks. Contienen identificadores de elemento/conversación, tipo, revisión y acción de cambio, sin notas, datos de contacto ni transcripciones. Suscribirse requiere `tickets:read`. Puede haber duplicados o desorden: deduplica `eventId` y lee las revisiones más recientes. Se conservan eventos de escalación anteriores. Las claves, concesiones OAuth, formatos de endpoints de revisión/escalación y URLs anteriores siguen siendo válidos y no reciben permisos automáticamente.

Tickets sustituye el nombre anterior Tasks. Las rutas `/tasks` y los nombres MCP anteriores siguen como adaptadores compatibles con sus campos `taskId`, `type=task` y `tasks`. Los permisos existentes `tasks:read/write` conservan la misma autoridad sin añadir permisos. Las suscripciones `task.created/updated` conservan sus nombres, formato e identidad de evento. Las integraciones nuevas deben usar los nombres Tickets. No se reescriben los registros ni el historial.

Consulta [permisos](/es/api-docs/permissions), [webhooks](/es/api-docs/webhooks) y [guía de producto](/es/product-guides/product/tickets).

## Contexto estructurado de falta de conocimiento

`GET /tickets/{ticketId}` y MCP `get_ticket` incluyen `escalation.knowledgeGap` opcional para estas escalaciones: `contextStatus`, `schemaVersion` guardada, `category`, `sourceCount`, hasta cinco `sourceTitles` de 200 caracteres, y `importance`/`confidence` anteriores cuando existen. Estos valores de diagnóstico no son prioridades del ticket. Un registro de detección correspondiente puede añadir `receipt`, con `receiptId`, `reportedAt`, `behavior` configurado y `disposition` registrado. El resultado de detección describe el reporte original, independientemente del estado actual del ticket y de la disponibilidad de la IA.

El contexto de apoyo en M2M/MCP requiere `conversations:read` además de `tickets:read`. Sin él, `contextStatus=permission_denied` no incluye categorías, fuentes ni detección. El contexto guardado ausente o inválido devuelve `unavailable`; un registro correspondiente ausente o no legible establece `receiptStatus=unavailable`, conservando el contexto válido del caso. La detección debe coincidir con espacio, conversación, evento de origen y caso exactos; no se sustituye por un reporte más reciente. Los casos anteriores no requieren migración.

Las listas y respuestas de mutaciones omiten estos detalles. Consulta `get_ticket` después de una mutación. Los títulos identifican fuentes de recuperación registradas; no muestran su contenido ni prueban que cada fuente causó el conflicto. Inspecciona conversación, mensajes y comprobantes con sus herramientas y permisos existentes. No se repiten llamadas a proveedores, se reevalúa la política actual, se crean tickets generales automáticamente ni se envían respuestas.


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