Saltar al contenido principal
Endpoint · POST /conversation/actions
Dos acciones gestionan qué empleado AI atiende la conversación: assign_ai_employee lo asigna (opcionalmente lo ejecuta) y unassign_ai lo retira (la conversación pasa a un humano).

assign_ai_employee

Asigna un empleado AI a la conversación. Con run: true, además lo ejecuta de inmediato (solo entonces cuenta como acción que dispara AI). Campos
  • ai_employee — { name } del empleado AI (obligatorio).
  • run — booleano (opcional, default false). Con true ejecuta el empleado de inmediato tras asignarlo.
  • instructions — texto opcional con instrucciones puntuales para esa ejecución. Solo aplica con run: true.
  • scheduled_message_action — reassign | cancel. Qué hacer con el mensaje programado activo de la conversación. Manda cancel por defecto (ver el aviso).
Programación activa al reasignar. Si la conversación la atiende un empleado AI que dejó un mensaje programado pendiente y la reasignas a otro empleado AI, la API exige que decidas qué pasa con esa programación: sin scheduled_message_action la acción falla con SCHEDULED_MESSAGE_ACTION_REQUIRED.
  • cancel — cancela el mensaje programado; el empleado AI nuevo empieza sin él.
  • reassign — conserva la programación y la reapunta al empleado AI nuevo.
Como la API no expone si una conversación tiene una programación activa, lo más robusto es mandar siempre "scheduled_message_action": "cancel": es válido en cualquier asignación y no hace nada si no hay programación que cancelar. Usa reassign solo cuando reasignas de un empleado AI a otro y quieres conservar la programación — enviarlo en cualquier otro caso falla con SCHEDULED_MESSAGE_ACTION_INVALID.
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. 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.
Con run: true y 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). Un empleado v2 se asigna igual que uno clásico, y con scheduled_message_action: reassign el mensaje programado de la conversación pasa a él. Con run, se ejecuta: si el motor v2 está apagado, o si un empleado clásico de su cadena lo ejecuta como asignado (run_assigned), el grupo se rechaza con AI_EMPLOYEE_V2_NOT_SUPPORTED (422) y no se reasigna nada. Sin run se asigna siempre. Si el motor v2 está apagado, la conversación pasa a pendiente cuando el cliente escriba, y si el mensaje programado que le pasaste con reassign se dispara con el motor apagado, se cancela sin llegarle al cliente y la conversación pasa a pendiente en ese momento. Ver Cómo se ejecuta.

unassign_ai

Retira el empleado AI (la conversación pasa a un humano). Sin campos; idempotente (no-op exitoso si la conversación ya no tiene AI). Cancela el mensaje programado activo del AI, si lo hay.
En una lista, estos objetos van en el array actions de un POST /conversation/actions — ver Armar una lista de acciones.

Ejemplo ejecutable

Dos acciones gestionan el empleado AI de una conversación identificada por teléfono y canal: assign_ai_employee lo asigna (con run: true además lo ejecuta) y unassign_ai lo retira. Manda scheduled_message_action: cancel por defecto; usa reassign solo al reasignar de un empleado AI a otro conservando su mensaje programado.

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.