Ejecuta un empleado AI a partir de una instrucción escrita en tus palabras
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:
{ "conversation": { "uuid": "9f3c1a4e-…", "channel": "ch_7A9K2M4Q" }, "ai_employee": { "name": "Agente Ventas" }, "instructions": "Revisa si quedó pendiente la cotización; si es así, envíasela y marca el seguimiento."}
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 los action sets que tiene asignados, 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, 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.
Antes de integrarte, pide al negocio la lista de action sets 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.
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.
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}.
Revisa si el cliente preguntó por el envío y todavía no le respondimos.Si es así, respóndele con la información de envío y etiquétalo como "Seguimiento".
Haz lo que corresponda.
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.
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.
Si la ventana de 24 h está cerrada, este 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. El corte es síncrono y previo, pero la llamada sí ocurrió:
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.Esto incluye los action sets cuyo envío tiene una plantilla configurada, que con la ventana
cerrada sí saldrían por su cuenta: en preflight no se sabe qué va a decidir el empleado, así que el
guard los bloquea igual. Smart Actions no sirve para reabrir una ventana cerrada.Es deliberado. Lo más común que hace este endpoint es mandarle un mensaje al cliente, y con la
ventana cerrada Meta lo rechaza. Sin este guard recibirías un 202, el mensaje quedaría marcado
como fallido en el chat y la conversación escalaría a pendiente — todo sin que te llegara ninguna
señal.Para reabrir una ventana cerrada, envía primero una plantilla con
/conversation/actions. Cuando el cliente responda, la ventana
vuelve a abrirse y Smart Actions queda disponible.Para saberlo de antemano, consulta POST /conversation/status: devuelve window.status
(open o closed) y window.expires_at.
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.
