Saltar al contenido principal
Endpoint · POST /conversation/smart-actions
Describe lo que quieres que ocurra en tus palabras y deja que el empleado AI decida cómo hacerlo. En vez de armar un array de acciones tipadas, mandas una conversación, un empleado y una instrucción:
El empleado lee el historial de la conversación, interpreta tu instrucción y ejecuta los action sets que tiene asignados.

Cuándo usar este endpoint y cuándo el grupo de acciones

Usa /conversation/actions

Cuando ya sabes exactamente qué quieres que ocurra. Es más barato, más rápido y más predecible: ejecutas las acciones que nombras, en el orden que las nombras.

Usa Smart Actions

Cuando quieres describir la intención y que el empleado juzgue el caso — sobre todo si la decisión depende de lo que diga el historial de la conversación.
La instrucción es obligatoria y admite hasta 4000 caracteres: espacio para reglas de negocio de verdad, no para un comando.

Lo más importante: la instrucción dirige, no amplía

El empleado ejecuta lo que tiene configurado —los action sets de un empleado clásico, los poderes de un empleado v2—, y nada más. Tu instrucción elige entre lo que ya sabe hacer; no le agrega capacidades.Si le pides algo para lo que no existe un action set o un poder, la ejecución responde y no ejecuta nada, sin devolver error. No vas a ver un 4xx: vas a ver una conversación donde no pasó lo que esperabas.
La ejecución puede dejar un mensaje programado. Si tu instrucción o las del empleado lo llevan a autoprogramarse, la conversación puede quedar con un programado de IA activo. Si después asignas otro empleado a esa conversación con el grupo de acciones, manda siempre scheduled_message_action en el assign_ai_employee. 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.
Antes de integrarte, pide al negocio la lista de action sets o poderes que el empleado tiene asignados —lo que sabe hacer sale de ahí y de su prompt, no de tu instrucción—. Si necesitas que ocurra algo concreto y garantizado —aplicar una etiqueta, mover de buzón, cambiar el estado— usa /conversation/actions, que ejecuta exactamente lo que le pides.

Solo empleados operative

Un empleado json devuelve AI_EMPLOYEE_NOT_FOUND (404). Descubre los disponibles con GET /ai-employees, que informa el type de cada uno. Para ejecutar un empleado json, usa /conversation/actions con la acción run_ai o ai_assistance.

Cómo escribir la instrucción

El empleado no puede adivinar los nombres de tus etiquetas, buzones o plantillas: nómbralos explícitamente. Descúbrelos con GET /tags, GET /mailbox-categories, GET /quick-replies y GET /templates/{name}/{language}.
El tope de 4000 se mide en unidades UTF-16. Si recortas el texto para respetarlo, no lo cortes a la mitad de un emoji: un carácter partido devuelve 400 INVALID_REQUEST.

La respuesta

El 202 confirma aceptación, no resultado. Una ejecución con razonamiento puede tardar minutos, así que corre en segundo plano.El detalle de lo que ocurrió no se notifica todavía — llegará por webhook (funcionalidad futura), igual que en /conversation/actions. Mientras tanto, lo ejecutado se ve en el Registro de Actividad del panel del negocio.

Con la ventana de 24 h cerrada, el empleado corre igual

Si la ventana de 24 h está cerrada, el empleado corre igual y decide qué mandar, y la respuesta es el mismo 202. Con la ventana cerrada WhatsApp solo entrega plantillas:
  • Si sus instrucciones indican un action set con plantilla y lo ejecuta, esa plantilla le llega al contacto.
  • Si responde con texto libre, el mensaje no se entrega: queda marcado como fallido en el chat y la conversación pasa a pendiente para que la atienda una persona. El 202 no te lo avisa.
  • Si ejecuta un action set que solo tiene una respuesta rápida, la ejecución falla: no sale nada y la conversación pasa a pendiente.
  • Si decide no mandar nada, no sale ningún mensaje.
En todos los casos el turno consume tokens.Si la ejecución con la ventana cerrada no está disponible, el endpoint responde 422 WINDOW_CLOSED y no ejecuta al empleado: no se gastan tokens, no se manda ningún mensaje y la conversación no cambia de estado. La llamada sí consume una petición de tu rate limit y queda en el Registro de Actividad del panel como un intento rechazado, con su código.Si no quieres gastar el turno, consulta POST /conversation/status y, si window.status es closed, manda una plantilla con /conversation/actions. Cuando el cliente responda, la ventana vuelve a abrirse.

Una llamada duplicada se ejecuta dos veces

Este endpoint no deduplica. No acepta Idempotency-Key, y el 202 no es promesa de ejecución única.
  • Mantén un solo request en vuelo por conversación.
  • No reintentes a ciegas un 5xx de este endpoint, a diferencia de lo que sugiere la tabla general de errores: el reintento vuelve a ejecutar y puede enviarle otro mensaje al cliente.
  • La ejecución puede solaparse con la respuesta automática que dispara un mensaje entrante del cliente.

Errores

El catálogo completo está en errores.