Saltar al contenido principal
Endpoint · POST /conversation/actions
Ejecuta un empleado AI. ai_employee es opcional — sin él usa el asignado a la conversación. instructions es opcional. Campos
  • ai_employee — { name } del empleado AI (opcional; sin él usa el asignado a la conversación).
  • instructions — texto libre (opcional).
En una lista, este objeto va en el array actions de un POST /conversation/actions — ver Armar una lista de acciones.
Con la ventana de 24 h cerrada, el empleado corre igual y la acción no falla por la ventana, así que no corta la lista aunque stop_on_error sea true. Si sus instrucciones indican un action set con plantilla, esa plantilla le llega al contacto; si no, su texto libre no se entrega y la conversación pasa a pendiente. Un action set que solo tiene una respuesta rápida sí falla, con AI_EXECUTION_FAILED, y corta la lista. Solo falla con WINDOW_CLOSED si la ejecución con la ventana cerrada no está disponible. El detalle está en ai_assistance.
Empleados con motor nuevo (v2). run_ai ejecuta un empleado v2 igual que uno clásico, con sus poderes. Si el motor v2 está apagado, un run_ai que ejecutaría a un v2 —el ai_employee que nombras o, sin él, el asignado— se rechaza con AI_EMPLOYEE_V2_NOT_SUPPORTED (422). Un asignado v2 solo cuenta cuando un empleado clásico —el que nombras o uno de su cadena— ejecuta al asignado (run_assigned): ahí el grupo se rechaza con el mismo 422, porque los action sets de un empleado clásico no ejecutan a un v2. Dos casos fallan por acción, después del 202, sin escalar: un run_ai sin ai_employee precedido por un assign_ai_employee del grupo, cuando el asignado nuevo es un v2 y el motor está apagado, y una acción cuyo empleado clásico ejecuta al asignado (run_assigned) cuando, después de un assign_ai_employee o un unassign_ai anterior, el asignado es un v2 (porque ese assign lo asignó, o porque no llegó a cambiarlo). Ver Cómo se ejecuta.
La ejecución puede dejar un mensaje programado. Si las instrucciones del empleado o la conversación lo llevan a autoprogramarse, la conversación puede quedar con un programado de IA activo. En una lista de acciones eso afecta a las que vienen después: en un assign_ai_employee posterior manda siempre scheduled_message_action (si no, puede fallar con SCHEDULED_MESSAGE_ACTION_REQUIRED), y una cancelación o un unassign_ai posterior cancela el seguimiento que el empleado le acaba de prometer al cliente. La ejecución también puede cancelar el programado pendiente. Si cancela uno que programó tu equipo, la conversación pasa a pendiente para que una persona lo reprograme; también pasa a pendiente si el empleado decide programar en una conversación sin IA asignada y le escribió al cliente en esa ejecución. Esta capacidad se habilita de forma gradual. Un empleado v2 (motor nuevo) no decide programar ni cancelar en esta ejecución, pero sus poderes sí pueden cambiar el programado activo: pasar a humano lo cancela si la conversación la atendía un empleado AI, y asignar a otro empleado lo cancela o, si la conversación ya la atendía un empleado AI y así lo configuró el negocio, lo transfiere.

Ejemplo ejecutable

Un run_ai sobre una conversación identificada por teléfono y canal. Con ai_employee corre un empleado explícito; sin él, corre el empleado AI asignado a la conversación. instructions es opcional.

Request

Respuesta

202 Accepted — el grupo se aceptó y corre en background. El resultado real por acción no viaja en la respuesta (se consulta después — ver Cómo se ejecuta).
string
Siempre processing: confirma que el grupo fue aceptado y está en ejecución.
integer
Cuántas acciones del array se admitieron para ejecución — no cuántas tuvieron éxito.