> ## Documentation Index
> Fetch the complete documentation index at: https://docs.1to1ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Smart Actions

> Ejecuta un empleado AI a partir de una instrucción escrita en tus palabras

<Info>
  **Endpoint** · `POST /conversation/smart-actions`
</Info>

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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Usa /conversation/actions" icon="list-check">
    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.
  </Card>

  <Card title="Usa Smart Actions" icon="wand-magic-sparkles">
    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.
  </Card>
</CardGroup>

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

<Warning>
  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.
</Warning>

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`](/es/action-groups/overview), 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}`.

<CodeGroup>
  ```text Sirve theme={null}
  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".
  ```

  ```text No sirve theme={null}
  Haz lo que corresponda.
  ```
</CodeGroup>

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

```json theme={null}
{
  "conversation": { "uuid": "9f3c1a4e-…" },
  "ai_employee": { "uuid": "4d81b0…", "name": "Agente Ventas" },
  "status": "processing"
}
```

<Note>
  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.
</Note>

## La ventana de 24 h se valida antes de ejecutar

<Warning>
  Si la [ventana de 24 h](/es/conversations) 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](/es/rate-limits) 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](/es/templates) con
  [`/conversation/actions`](/es/action-groups/overview). 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`.
</Warning>

## Una llamada duplicada se ejecuta dos veces

<Warning>
  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](/es/errors): 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.
</Warning>

## Errores

| Código                   | Status | Cuándo                                                                                                          |
| ------------------------ | ------ | --------------------------------------------------------------------------------------------------------------- |
| `INVALID_REQUEST`        | 400    | Falta `instructions`, o excede 4000, o trae un carácter que no podemos almacenar (un emoji partido al recortar) |
| `CONVERSATION_NOT_FOUND` | 404    | La conversación no existe o está eliminada                                                                      |
| `CHANNEL_NOT_FOUND`      | 404    | La clave de `channel` no corresponde a un canal activo                                                          |
| `AI_EMPLOYEE_NOT_FOUND`  | 404    | No existe un empleado **`operative`** activo con ese nombre                                                     |
| `AMBIGUOUS_AI_EMPLOYEE`  | 409    | El nombre resuelve a más de un empleado. Desambigua con `uuid`                                                  |
| `PHONE_NUMBER_AMBIGUOUS` | 409    | El teléfono corresponde a más de un contacto en ese canal                                                       |
| `WALLET_BLOCKED`         | 402    | El wallet de tokens del modelo del empleado está vacío o bloqueado. Recarga para continuar                      |
| `VISION_WALLET_BLOCKED`  | 402    | El wallet de vision tokens está vacío. El procesamiento de visión requiere recarga                              |
| `VISION_BLOCKED`         | 402    | El hilo está bloqueado por visión, o su media entrante quedó sin transcripción después de que la visión terminó |
| `WINDOW_CLOSED`          | 422    | La ventana de 24h está cerrada. Envía una plantilla con `/conversation/actions` para reabrirla                  |
| `ACTIONS_DEPTH_EXCEEDED` | 422    | Los action sets del empleado encadenan más allá del límite                                                      |

El catálogo completo está en [errores](/es/errors).