Saltar al contenido principal
Endpoint · POST /conversation/actions
ai_assistance ejecuta el empleado AI que elijas sobre la conversación sin asignarlo. Es una ejecución puntual: el empleado corre de forma transitoria y genera su asistencia (contexto/sugerencia) sobre la conversación, pero no se convierte en el empleado asignado — la conversación sigue con quien la atiende (otro empleado AI o un humano) y la asignación no cambia. Cómo se diferencia de las otras acciones de AI:
  • run_ai ejecuta al empleado asignado —el que atiende— y toma el turno.
  • assign_ai_employee cambia qué empleado atiende la conversación.
  • ai_assistance ejecuta a otro empleado sin asignarlo — su salida no cambia quién atiende.
Campos
  • ai_employee — { name } del empleado AI a consultar (obligatorio).
  • instructions — texto opcional con la consulta o el foco para el empleado (por ejemplo, “¿Este cliente califica para el plan empresarial?”).
Consume tokens del modelo del empleado consultado y cuenta como acción que dispara AI (máximo 3 por grupo, contando también los send_json). En una lista, este objeto va en el array actions de un POST /conversation/actions — ver Armar una lista de acciones.
Esta acción no valida la ventana de 24 h, y el empleado sí puede responderle al cliente.Con la ventana cerrada la corrida se ejecuta igual y consume tokens:
  • Si las instrucciones del empleado indican un action set con plantilla y lo ejecuta, esa plantilla le llega al contacto.
  • El texto libre que emita lo rechaza Meta: queda marcado como fallido en el chat y la conversación escala a pendiente. No llega como WINDOW_CLOSED de la acción — el resultado per-acción sale en verde, porque el turno corrió bien; lo que falló fue la entrega.
  • Un action set que solo tiene una respuesta rápida falla: la acción sale con AI_EXECUTION_FAILED, corta la lista con stop_on_error y deja la conversación en pendiente.
run_ai, assign_ai_employee con run y /conversation/smart-actions también corren con la ventana cerrada, pero responden WINDOW_CLOSED sin ejecutar al empleado si la ejecución con la ventana cerrada no está disponible. Esta acción no lo hace nunca.Si no quieres gastar el turno, consulta POST /conversation/status y, si window.status es closed, manda primero una plantilla. Cuando el cliente responda, la ventana vuelve a abrirse.
Empleados con motor nuevo (v2). La asistencia ejecuta un empleado v2 igual que uno clásico. Si el motor v2 está apagado y ai_employee es v2, el grupo se rechaza con AI_EMPLOYEE_V2_NOT_SUPPORTED (422). Que la conversación tenga asignado un v2 no impide la asistencia: solo cuenta cuando un empleado clásico ejecuta al asignado (run_assigned). En ese caso el grupo se rechaza con el mismo 422, salvo que un assign_ai_employee o un unassign_ai anterior del grupo pueda cambiar al asignado: entonces la acción falla por acción, después del 202 y sin escalar, si el asignado es v2 en ese momento (también cuando ese assign acaba de asignarlo). 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 ai_assistance sobre una conversación identificada por teléfono y canal: ejecuta de forma puntual al empleado AI elegido, sin cambiar la asignación de la conversación.

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.