Ejecutar grupo de acciones sobre una conversación

Ejecuta un grupo de acciones sobre una conversación en una sola request. Cada acción del array actions espeja 1:1 un endpoint de acción individual de la API pública — este endpoint las agrupa para evitar N round-trips.

Contrato:

• Una conversación por request. La conversation se identifica una sola vez en el body y aplica a todas las acciones del grupo.
• Ejecución asíncrona. El request valida el body, resuelve la conversación y corre el preflight de forma síncrona. Si el preflight pasa, la lista completa se ejecuta en background y la respuesta es un 202 Accepted inmediato { conversation, status, actions_accepted } — un ack puro, sin resultado por acción.
• Orden garantizado. Las acciones se ejecutan secuencialmente en el orden del array actions.
• Una acción puede fallar. El 202 solo confirma que el grupo fue aceptado. Una acción individual puede fallar durante la ejecución en background; ese resultado se notificará por webhook (feature futura).

Límites:

• Máximo 10 acciones por grupo. Excederlo devuelve BATCH_LIMIT_EXCEEDED (400).
• Subcap de 3 acciones AI-triggering por grupo — run_ai, ai_assistance, y assign_ai_employee con run: true. Excederlo también devuelve BATCH_LIMIT_EXCEEDED (400).

stop_on_error:

• true (default) — la primera acción que falla aborta el resto de la ejecución en background.
• false — ejecuta todas las acciones del grupo.

Una acción cuyo estado deseado ya se cumple (tag, buzón o empleado ya en ese estado) es un no-op idempotente: cuenta como éxito y no dispara stop_on_error.

escalate_on_error:

• true (default) — cuando una acción falla con un código de delivery / AI execution / DB write / race de asignación AI (SEND_FAILED, PREPARE_FAILED, AI_EXECUTION_FAILED, ACTIONS_DEPTH_EXCEEDED, UPDATE_FAILED, NO_AI_EMPLOYEE_ASSIGNED), la conversación se escala a inbox_status='pending' con pending_reason='action_set_failed' para que el operador la vea bloqueada en el inbox con motivo legible. Una sola escalada por grupo aunque varias acciones fallen.
• false — solo se reportan los errores; no se toca el estado de la conversación. Útil para integradores cuyo reporte out-of-band ya cubre el seguimiento.

Los errores 4xx por input incorrecto del integrador (*_NOT_FOUND, *_AMBIGUOUS, WINDOW_CLOSED, TEMPLATE_NOT_APPROVED, TEMPLATE_FAKE_REQUIRES_TESTER_CONVERSATION, etc.) y los guards de billing (WALLET_BLOCKED, VISION_WALLET_BLOCKED) nunca escalan independientemente del flag — el integrador corrige y reintenta sin necesidad de atención humana. La paridad con el path AI nativo (donde la escalada es automática y no configurable) se mantiene por default.

Las 12 acciones (type):

Preflight (rechaza TODO el grupo antes de ejecutar): la conversación se resuelve una vez; luego corre un guard de visión único y, por cada acción AI-triggering (run_ai, ai_assistance, assign_ai_employee con run: true), se resuelve el empleado y se corren sus guards (wallet, depth). Si una acción AI no puede ejecutarse — sin tokens, empleado inexistente, etc. — se rechaza la lista completa con un 4xx síncrono y ninguna acción se ejecuta. El message del error indica cuál acción de la lista lo disparó.

La ventana 24h no se chequea en el preflight, pero sí es un error per-acción: run_ai, assign_ai_employee con run y send_message (texto / media / quick reply) fallan con WINDOW_CLOSED si la ventana está cerrada al ejecutarse — stop_on_error decide si el resto de la lista continúa. send_quick_reply_or_template y las acciones no-AI no se ven afectadas. Las acciones no-AI no se pre-chequean: si una falla, lo hace durante la ejecución en background.

maxDuration es 800 s — un techo para el grupo completo, por encima del presupuesto de un solo pipeline AI (300 s). Un grupo con varios runs AI lentos en serie puede aún excederlo: es una limitación conocida del modelo de ejecución in-invoke (ver el feature doc action-groups.md).