Saltar al contenido principal
El endpoint POST /conversation/actions ejecuta un grupo de hasta 10 acciones sobre una sola conversación, en el orden que las envías. En vez de hacer N requests para etiquetar, dejar una nota y ejecutar el AI, los encadenas en un solo request.

​
Las 12 acciones

Cada elemento del array actions lleva un campo type. Casi todas espejan un endpoint individual de la API; send_quick_reply_or_template es la excepción: envía la quick reply si la ventana de 24h está abierta, o la plantilla si está cerrada — el modo lo decide el servidor en tiempo de ejecución.
  • send_message — envía un mensaje (texto, media, quick reply o plantilla).
  • send_quick_reply_or_template — quick reply o plantilla, según la ventana.
  • assign_label — asigna una etiqueta a la conversación.
  • remove_label — quita una etiqueta de la conversación.
  • assign_mailbox — mueve la conversación a un buzón.
  • context_note — deja una nota interna.
  • mark_resolved — marca la conversación como resuelta.
  • mark_pending — marca la conversación como pendiente.
  • run_ai — ejecuta el empleado AI sobre la conversación.
  • ai_assistance — genera una respuesta sugerida con el AI.
  • assign_ai_employee — asigna un empleado AI a la conversación.
  • unassign_ai — retira el empleado AI (pasa la conversación a un humano). Sin campos; idempotente (no-op si la conversación ya no tiene AI).
Un grupo admite hasta 10 acciones, de las cuales como máximo 3 pueden disparar al AI. Excederlo falla con BATCH_LIMIT_EXCEEDED.

​
Cómo se ejecuta

1

Validación síncrona

La API valida el request. Si el preflight lo rechaza (ej. el AI no tiene tokens), responde un 4xx síncrono y ninguna acción se ejecuta.
2

202 Accepted

Si pasa la validación, responde 202 de inmediato; el grupo corre en background.
3

Ejecución en orden

Las acciones se ejecutan una por una, en el orden enviado.
El 202 confirma que el grupo fue aceptado, no que cada acción tuvo éxito. El resultado por acción no viaja en la respuesta — consúltalo en el estado de la conversación o en el activity log del negocio.

​
Stop on error

stop_on_error controla qué pasa cuando una acción falla durante la ejecución:

​
Escalada a pending

escalate_on_error controla si una falla del grupo escala la conversación a inbox_status='pending' para que un humano la revise:
Los errores de input del integrador (*_NOT_FOUND, *_AMBIGUOUS, WINDOW_CLOSED, TEMPLATE_NOT_APPROVED, etc.), los guards de billing (WALLET_BLOCKED, VISION_WALLET_BLOCKED) y el guard de integridad de mark_resolved (TRANSCRIPTION_REQUIRED_TO_RESOLVE) nunca escalan — corrígelos y reintenta sin intervención humana.

​
Ejemplo

Etiquetar, dejar una nota y ejecutar el AI, sin cortar ante fallos:
Pasar a humano — una sola acción unassign_ai, sin campos. Es idempotente: si la conversación ya no tiene AI, es un no-op exitoso.
¿Solo necesitas pasar a humano y quieres el resultado al instante? El endpoint síncrono POST /conversation/unassign-ai hace exactamente esto y responde 200 con el resultado real ({ "ai_employee": null, "schedule_action": "cancelled" | "none" }), sin el modelo asíncrono del grupo.
Si el preflight rechaza el grupo, la respuesta es un 4xx síncrono y ninguna acción se ejecuta. Ver Errores.