> ## 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.

# Grupo de acciones

> Ejecuta hasta 10 acciones sobre una conversación en un solo request.

El endpoint `POST /conversation/actions` ejecuta un **grupo de hasta 10
acciones** sobre **una sola conversación**, en el orden que las envías. En vez
de hacer N requests para etiquetar, dejar una nota y ejecutar el AI, los
encadenas en un solo request.

## Las 12 acciones

Cada elemento del array `actions` lleva un campo `type`. Casi todas espejan un
endpoint individual de la API; `send_quick_reply_or_template` es la excepción:
envía la quick reply si la ventana de 24h está abierta, o la
[plantilla](/es/templates) si está cerrada — el modo lo decide el servidor en
tiempo de ejecución.

<AccordionGroup>
  <Accordion title="Mensajería" icon="paper-plane">
    * `send_message` — envía un mensaje (texto, media, quick reply o plantilla).
    * `send_quick_reply_or_template` — quick reply o plantilla, según la ventana.
  </Accordion>

  <Accordion title="Etiquetas" icon="tag">
    * `assign_label` — asigna una etiqueta a la conversación.
    * `remove_label` — quita una etiqueta de la conversación.
  </Accordion>

  <Accordion title="Buzón y notas" icon="inbox">
    * `assign_mailbox` — mueve la conversación a un buzón.
    * `context_note` — deja una nota interna.
    * `mark_resolved` — marca la conversación como resuelta.
    * `mark_pending` — marca la conversación como pendiente.
  </Accordion>

  <Accordion title="AI" icon="robot">
    * `run_ai` — ejecuta el empleado AI sobre la conversación.
    * `ai_assistance` — genera una respuesta sugerida con el AI.
    * `assign_ai_employee` — asigna un empleado AI a la conversación.
    * `unassign_ai` — retira el empleado AI (pasa la conversación a un humano). Sin campos; idempotente (no-op si la conversación ya no tiene AI).
  </Accordion>
</AccordionGroup>

<Note>
  Un grupo admite hasta **10 acciones**, de las cuales como máximo **3** pueden
  disparar al AI. Excederlo falla con `BATCH_LIMIT_EXCEEDED`.
</Note>

## Cómo se ejecuta

<Steps>
  <Step title="Validación síncrona">
    La API valida el request. Si el preflight lo rechaza (ej. el AI no tiene
    tokens), responde un `4xx` síncrono y **ninguna** acción se ejecuta.
  </Step>

  <Step title="202 Accepted">
    Si pasa la validación, responde **`202`** de inmediato; el grupo corre en
    **background**.
  </Step>

  <Step title="Ejecución en orden">
    Las acciones se ejecutan una por una, en el orden enviado.
  </Step>
</Steps>

<Warning>
  El `202` confirma que el grupo fue **aceptado**, no que cada acción tuvo éxito.
  El resultado por acción **no viaja en la respuesta** — consúltalo en el estado
  de la conversación o en el activity log del negocio.
</Warning>

## Stop on error

`stop_on_error` controla qué pasa cuando una acción falla durante la ejecución:

| Valor            | Comportamiento                                                         |
| ---------------- | ---------------------------------------------------------------------- |
| `true` (default) | La primera falla **corta** las acciones siguientes.                    |
| `false`          | El grupo ejecuta **todas** las acciones, ignorando fallos intermedios. |

## Escalada a pending

`escalate_on_error` controla si una falla del grupo escala la conversación a `inbox_status='pending'` para que un humano la revise:

| Valor            | Comportamiento                                                                                                                                                                                                                                                                                                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `true` (default) | Si una acción falla con un error de **entrega, ejecución AI, escritura en DB, o race de asignación AI** (`SEND_FAILED`, `PREPARE_FAILED`, `AI_EXECUTION_FAILED`, `ACTIONS_DEPTH_EXCEEDED`, `UPDATE_FAILED`, `NO_AI_EMPLOYEE_ASSIGNED`), la conversación se marca como `pending` con `pending_reason='action_set_failed'`. Una sola escalada por grupo aunque varias acciones fallen. |
| `false`          | Las fallas se reportan en el activity log pero la conversación queda intacta.                                                                                                                                                                                                                                                                                                        |

<Note>
  Los errores de input del integrador (`*_NOT_FOUND`, `*_AMBIGUOUS`, `WINDOW_CLOSED`, `TEMPLATE_NOT_APPROVED`, etc.), los guards de billing (`WALLET_BLOCKED`, `VISION_WALLET_BLOCKED`) y el guard de integridad de `mark_resolved` (`TRANSCRIPTION_REQUIRED_TO_RESOLVE`) **nunca escalan** — corrígelos y reintenta sin intervención humana.
</Note>

## Ejemplo

Etiquetar, dejar una nota y ejecutar el AI, sin cortar ante fallos:

<CodeGroup>
  ```jsonc Request theme={null}
  {
    "conversation": { "phone": "+5215512345678" },
    "stop_on_error": false,
    "actions": [
      { "type": "assign_label", "tags": [{ "name": "VIP" }] },
      { "type": "context_note", "note": "Cliente pidió cotización." },
      { "type": "run_ai", "ai_employee": { "name": "Agente Ventas" } }
    ]
  }
  ```

  ```jsonc Respuesta 202 theme={null}
  {
    "conversation": { "uuid": "..." },
    "status": "processing",
    "actions_accepted": 3
  }
  ```
</CodeGroup>

**Pasar a humano** — una sola acción `unassign_ai`, sin campos. Es idempotente:
si la conversación ya no tiene AI, es un no-op exitoso.

<CodeGroup>
  ```jsonc Request theme={null}
  {
    "conversation": { "phone": "+5215512345678" },
    "actions": [{ "type": "unassign_ai" }]
  }
  ```

  ```jsonc Respuesta 202 theme={null}
  {
    "conversation": { "uuid": "..." },
    "status": "processing",
    "actions_accepted": 1
  }
  ```
</CodeGroup>

<Note>
  ¿Solo necesitas pasar a humano y quieres el resultado al instante? El endpoint
  síncrono `POST /conversation/unassign-ai`
  hace exactamente esto y responde `200` con el resultado real
  (`{ "ai_employee": null, "schedule_action": "cancelled" | "none" }`), sin el
  modelo asíncrono del grupo.
</Note>

<Tip>
  Si el preflight rechaza el grupo, la respuesta es un `4xx` síncrono y ninguna
  acción se ejecuta. Ver [Errores](/es/errors).
</Tip>