> ## 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. # Ejecutar grupo de acciones sobre una conversación > Ejecuta un **grupo de acciones** sobre una conversación en una sola request. Cada acción del array `actions` espeja 1:1 un endpoint de acción individual de la API pública — este endpoint las agrupa para evitar N round-trips. **Contrato:** - **Una conversación por request.** La `conversation` se identifica una sola vez en el body y aplica a todas las acciones del grupo. - **Ejecución asíncrona.** El request valida el body, resuelve la conversación y corre el preflight de forma síncrona. Si el preflight pasa, la lista **completa** se ejecuta en background y la respuesta es un `202 Accepted` inmediato `{ conversation, status, actions_accepted }` — un ack puro, **sin resultado por acción**. - **Orden garantizado.** Las acciones se ejecutan secuencialmente en el orden del array `actions`. - **Una acción puede fallar.** El `202` solo confirma que el grupo fue aceptado. Una acción individual puede fallar durante la ejecución en background; ese resultado se notificará por webhook (feature futura). **Límites:** - Máximo **10 acciones** por grupo. Excederlo devuelve `BATCH_LIMIT_EXCEEDED` (400). - Subcap de **3 acciones AI-triggering** por grupo — `run_ai`, `ai_assistance`, y `assign_ai_employee` con `run: true`. Excederlo también devuelve `BATCH_LIMIT_EXCEEDED` (400). **`stop_on_error`:** - `true` (default) — la primera acción que falla aborta el resto de la ejecución en background. - `false` — ejecuta todas las acciones del grupo. Una acción cuyo estado deseado ya se cumple (tag, buzón o empleado ya en ese estado) es un **no-op idempotente**: cuenta como éxito y no dispara `stop_on_error`. **`escalate_on_error`:** - `true` (default) — cuando una acción falla con un código de **delivery / AI execution / DB write / 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 escala a `inbox_status='pending'` con `pending_reason='action_set_failed'` para que el operador la vea bloqueada en el inbox con motivo legible. Una sola escalada por grupo aunque varias acciones fallen. - `false` — solo se reportan los errores; no se toca el estado de la conversación. Útil para integradores cuyo reporte out-of-band ya cubre el seguimiento. Los errores **4xx por input incorrecto del integrador** (`*_NOT_FOUND`, `*_AMBIGUOUS`, `WINDOW_CLOSED`, `TEMPLATE_NOT_APPROVED`, `TEMPLATE_FAKE_REQUIRES_TESTER_CONVERSATION`, etc.) y los **guards de billing** (`WALLET_BLOCKED`, `VISION_WALLET_BLOCKED`) **nunca escalan** independientemente del flag — el integrador corrige y reintenta sin necesidad de atención humana. La paridad con el path AI nativo (donde la escalada es automática y no configurable) se mantiene por default. **Las 12 acciones (`type`):** | `type` | Qué hace | Endpoint equivalente | |---|---|---| | `send_message` | Envía texto / media / quick reply / template | `/conversation/messages/{text,quick-reply,template}` | | `send_quick_reply_or_template` | Quick reply si la ventana 24h está abierta, plantilla si está cerrada | — (solo grupo / campañas) | | `assign_label` | Asigna 1+ tags | `POST /conversation/tags` | | `remove_label` | Quita 1+ tags | `DELETE /conversation/tags` | | `assign_mailbox` | Mueve a mailbox o categoría | `POST /conversation/mailbox` | | `context_note` | Agrega una nota interna | `POST /conversation/notes` | | `mark_resolved` | Marca la conversación como `resolved` (cierra el handoff humano) | `POST /conversation/resolve` | | `mark_pending` | Marca la conversación como `pending` (reabre el handoff humano) | `POST /conversation/pending` | | `run_ai` | Ejecuta el AI asignado o uno explícito | `POST /conversation/run-ai` | | `ai_assistance` | Consulta puntual a otro AI | `POST /conversation/ai-assistance` | | `assign_ai_employee` | Asigna un AI (y lo ejecuta si `run: true`) | `POST /conversation/ai-employee` | | `unassign_ai` | Retira el AI asignado (pasa a humano, `ai_employee_id → NULL`) | `POST /conversation/unassign-ai` | **Preflight (rechaza TODO el grupo antes de ejecutar):** la conversación se resuelve una vez; luego corre un guard de visión único y, por cada acción AI-triggering (`run_ai`, `ai_assistance`, `assign_ai_employee` con `run: true`), se resuelve el empleado y se corren sus guards (wallet, depth). Si una acción AI no puede ejecutarse — sin tokens, empleado inexistente, etc. — se **rechaza la lista completa** con un 4xx síncrono y **ninguna acción se ejecuta**. El `message` del error indica cuál acción de la lista lo disparó. La ventana 24h **no** se chequea en el preflight, pero sí es un error **per-acción**: `run_ai`, `assign_ai_employee` con `run` y `send_message` (texto / media / quick reply) fallan con `WINDOW_CLOSED` si la ventana está cerrada al ejecutarse — `stop_on_error` decide si el resto de la lista continúa. `send_quick_reply_or_template` y las acciones no-AI no se ven afectadas. Las acciones no-AI no se pre-chequean: si una falla, lo hace durante la ejecución en background. maxDuration es 800 s — un **techo** para el grupo completo, por encima del presupuesto de un solo pipeline AI (300 s). Un grupo con varios runs AI lentos en serie puede aún excederlo: es una limitación conocida del modelo de ejecución in-invoke (ver el feature doc `action-groups.md`). ## OpenAPI ````yaml /openapi.json post /{slug}/conversation/actions openapi: 3.1.0 info: title: 1TO1 AI Public API version: 0.2.0 description: >- API pública de 1TO1 AI para integraciones externas (n8n, CRMs, scripts). Auth via Bearer token. Rate limit 60 req/min por API key. Contrato REST puro: el body de éxito es el payload directo (status HTTP como señal), errores retornan `{code, message}` con ambos campos garantizados. Ver schema `PublicError`. servers: - url: https://app.1to1.ai/api/v1/public description: Producción security: - bearerAuth: [] paths: /{slug}/conversation/actions: post: tags: - Conversations summary: Ejecutar grupo de acciones sobre una conversación description: >- Ejecuta un **grupo de acciones** sobre una conversación en una sola request. Cada acción del array `actions` espeja 1:1 un endpoint de acción individual de la API pública — este endpoint las agrupa para evitar N round-trips. **Contrato:** - **Una conversación por request.** La `conversation` se identifica una sola vez en el body y aplica a todas las acciones del grupo. - **Ejecución asíncrona.** El request valida el body, resuelve la conversación y corre el preflight de forma síncrona. Si el preflight pasa, la lista **completa** se ejecuta en background y la respuesta es un `202 Accepted` inmediato `{ conversation, status, actions_accepted }` — un ack puro, **sin resultado por acción**. - **Orden garantizado.** Las acciones se ejecutan secuencialmente en el orden del array `actions`. - **Una acción puede fallar.** El `202` solo confirma que el grupo fue aceptado. Una acción individual puede fallar durante la ejecución en background; ese resultado se notificará por webhook (feature futura). **Límites:** - Máximo **10 acciones** por grupo. Excederlo devuelve `BATCH_LIMIT_EXCEEDED` (400). - Subcap de **3 acciones AI-triggering** por grupo — `run_ai`, `ai_assistance`, y `assign_ai_employee` con `run: true`. Excederlo también devuelve `BATCH_LIMIT_EXCEEDED` (400). **`stop_on_error`:** - `true` (default) — la primera acción que falla aborta el resto de la ejecución en background. - `false` — ejecuta todas las acciones del grupo. Una acción cuyo estado deseado ya se cumple (tag, buzón o empleado ya en ese estado) es un **no-op idempotente**: cuenta como éxito y no dispara `stop_on_error`. **`escalate_on_error`:** - `true` (default) — cuando una acción falla con un código de **delivery / AI execution / DB write / 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 escala a `inbox_status='pending'` con `pending_reason='action_set_failed'` para que el operador la vea bloqueada en el inbox con motivo legible. Una sola escalada por grupo aunque varias acciones fallen. - `false` — solo se reportan los errores; no se toca el estado de la conversación. Útil para integradores cuyo reporte out-of-band ya cubre el seguimiento. Los errores **4xx por input incorrecto del integrador** (`*_NOT_FOUND`, `*_AMBIGUOUS`, `WINDOW_CLOSED`, `TEMPLATE_NOT_APPROVED`, `TEMPLATE_FAKE_REQUIRES_TESTER_CONVERSATION`, etc.) y los **guards de billing** (`WALLET_BLOCKED`, `VISION_WALLET_BLOCKED`) **nunca escalan** independientemente del flag — el integrador corrige y reintenta sin necesidad de atención humana. La paridad con el path AI nativo (donde la escalada es automática y no configurable) se mantiene por default. **Las 12 acciones (`type`):** | `type` | Qué hace | Endpoint equivalente | |---|---|---| | `send_message` | Envía texto / media / quick reply / template | `/conversation/messages/{text,quick-reply,template}` | | `send_quick_reply_or_template` | Quick reply si la ventana 24h está abierta, plantilla si está cerrada | — (solo grupo / campañas) | | `assign_label` | Asigna 1+ tags | `POST /conversation/tags` | | `remove_label` | Quita 1+ tags | `DELETE /conversation/tags` | | `assign_mailbox` | Mueve a mailbox o categoría | `POST /conversation/mailbox` | | `context_note` | Agrega una nota interna | `POST /conversation/notes` | | `mark_resolved` | Marca la conversación como `resolved` (cierra el handoff humano) | `POST /conversation/resolve` | | `mark_pending` | Marca la conversación como `pending` (reabre el handoff humano) | `POST /conversation/pending` | | `run_ai` | Ejecuta el AI asignado o uno explícito | `POST /conversation/run-ai` | | `ai_assistance` | Consulta puntual a otro AI | `POST /conversation/ai-assistance` | | `assign_ai_employee` | Asigna un AI (y lo ejecuta si `run: true`) | `POST /conversation/ai-employee` | | `unassign_ai` | Retira el AI asignado (pasa a humano, `ai_employee_id → NULL`) | `POST /conversation/unassign-ai` | **Preflight (rechaza TODO el grupo antes de ejecutar):** la conversación se resuelve una vez; luego corre un guard de visión único y, por cada acción AI-triggering (`run_ai`, `ai_assistance`, `assign_ai_employee` con `run: true`), se resuelve el empleado y se corren sus guards (wallet, depth). Si una acción AI no puede ejecutarse — sin tokens, empleado inexistente, etc. — se **rechaza la lista completa** con un 4xx síncrono y **ninguna acción se ejecuta**. El `message` del error indica cuál acción de la lista lo disparó. La ventana 24h **no** se chequea en el preflight, pero sí es un error **per-acción**: `run_ai`, `assign_ai_employee` con `run` y `send_message` (texto / media / quick reply) fallan con `WINDOW_CLOSED` si la ventana está cerrada al ejecutarse — `stop_on_error` decide si el resto de la lista continúa. `send_quick_reply_or_template` y las acciones no-AI no se ven afectadas. Las acciones no-AI no se pre-chequean: si una falla, lo hace durante la ejecución en background. maxDuration es 800 s — un **techo** para el grupo completo, por encima del presupuesto de un solo pipeline AI (300 s). Un grupo con varios runs AI lentos en serie puede aún excederlo: es una limitación conocida del modelo de ejecución in-invoke (ver el feature doc `action-groups.md`). parameters: - $ref: '#/components/parameters/SlugPathParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ActionGroupBody' examples: tagAndNote: summary: Etiquetar y dejar una nota interna value: conversation: phone: '+525512345678' actions: - type: assign_label tags: - name: VIP - type: context_note note: Cliente recurrente — priorizar. replyAndHandoff: summary: Responder, mover de mailbox y asignar un AI que ejecuta value: conversation: uuid: 550e8400-e29b-41d4-a716-446655440000 stop_on_error: false actions: - type: send_message body: En un momento te atendemos. - type: assign_mailbox mailbox: name: Soporte - type: assign_ai_employee ai_employee: name: Asistente de Soporte run: true responses: '202': description: >- El grupo fue aceptado: el preflight pasó y las acciones se ejecutan en background. La respuesta es un ack puro `{ conversation, status, actions_accepted }` — sin resultado por acción. headers: X-Request-Id: schema: type: string format: uuid description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. required: true description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. content: application/json: schema: $ref: '#/components/schemas/ActionGroupAccepted' '400': description: >- Body inválido (INVALID_REQUEST) o se excedió un límite del grupo (BATCH_LIMIT_EXCEEDED — más de 10 acciones, o más de 3 acciones AI-triggering). El `message` distingue el cap total del subcap AI. headers: X-Request-Id: schema: type: string format: uuid description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. required: true description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. content: application/json: schema: $ref: '#/components/schemas/PublicError' '401': description: Token ausente, mal formado o no válido (INVALID_API_TOKEN) headers: X-Request-Id: schema: type: string format: uuid description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. required: true description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. content: application/json: schema: $ref: '#/components/schemas/PublicError' '402': description: >- Preflight bloqueado — wallet de un empleado AI sin saldo (WALLET_BLOCKED), wallet de visión sin saldo (VISION_WALLET_BLOCKED) o items de visión pendientes (VISION_BLOCKED). Rechaza el grupo entero: ninguna acción se ejecutó. headers: X-Request-Id: schema: type: string format: uuid description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. required: true description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. content: application/json: schema: $ref: '#/components/schemas/PublicError' '403': description: >- El slug del path no coincide con el business del token (TOKEN_BUSINESS_MISMATCH) headers: X-Request-Id: schema: type: string format: uuid description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. required: true description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. content: application/json: schema: $ref: '#/components/schemas/PublicError' '404': description: >- La conversación no resuelve para el business del token (CONVERSATION_NOT_FOUND) o una acción AI referencia un empleado inexistente (AI_EMPLOYEE_NOT_FOUND). Rechaza el grupo entero. headers: X-Request-Id: schema: type: string format: uuid description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. required: true description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. content: application/json: schema: $ref: '#/components/schemas/PublicError' '409': description: >- Una acción AI referencia un empleado por `name` que matchea más de uno (AMBIGUOUS_AI_EMPLOYEE), o un `run_ai` sin `ai_employee` sobre una conversación sin AI asignado y sin un `assign_ai_employee` previo en el grupo que se lo asigne (INVALID_ASSIGNEE_FOR_RUN_AI). También cuando el identificador de conversación es ambiguo: varios contactos comparten el teléfono (`PHONE_NUMBER_AMBIGUOUS`) o el username (`USERNAME_AMBIGUOUS`) — identifica la conversación por `whatsapp_user_id` o `uuid`. Rechaza el grupo entero. headers: X-Request-Id: schema: type: string format: uuid description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. required: true description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. content: application/json: schema: $ref: '#/components/schemas/PublicError' '422': description: >- Una acción AI no puede ejecutarse: profundidad del grafo de action sets excedida (ACTIONS_DEPTH_EXCEEDED) o el empleado asignado fue desactivado entre el snapshot y la resolución (NO_AI_EMPLOYEE_ASSIGNED). Rechaza el grupo entero. headers: X-Request-Id: schema: type: string format: uuid description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. required: true description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. content: application/json: schema: $ref: '#/components/schemas/PublicError' '429': description: >- Rate limit excedido (RATE_LIMIT_EXCEEDED). Headers `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` indican cuándo reintentar. headers: X-Request-Id: schema: type: string format: uuid description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. required: true description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. content: application/json: schema: $ref: '#/components/schemas/PublicError' '500': description: >- Fallo de DB al cargar el snapshot de preflight (FETCH_FAILED). Rechaza el grupo entero: ninguna acción se ejecutó. headers: X-Request-Id: schema: type: string format: uuid description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. required: true description: >- ID único para correlacionar con logs server-side. Si el cliente envía uno válido (UUID), se preserva; si no, se genera uno nuevo. content: application/json: schema: $ref: '#/components/schemas/PublicError' components: parameters: SlugPathParam: schema: $ref: '#/components/schemas/SlugPathParam' required: true description: >- Slug del business, case-insensitive. Debe coincidir con el business del token. name: slug in: path schemas: ActionGroupBody: type: object properties: conversation: $ref: '#/components/schemas/ConversationRef' stop_on_error: type: boolean default: true example: true description: >- `true` (default): la primera acción que falla corta el resto de la ejecución en background. `false`: ejecuta todas las acciones. Una acción cuyo estado deseado ya se cumple (tag ya asignado, empleado ya asignado, etc.) es un no-op idempotente: cuenta como éxito y NO dispara `stop_on_error`. escalate_on_error: type: boolean default: true example: true description: >- `true` (default): cuando una acción falla con un código de **delivery / AI execution / DB write / 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 escala a `inbox_status='pending'` con `pending_reason='action_set_failed'` para que el operador la vea bloqueada en el inbox con motivo legible. **Una sola escalada por grupo** aunque varias acciones fallen. `false`: solo se reportan los errores en el resultado, sin tocar el estado de la conversación. Los errores 4xx por input incorrecto del integrador (`*_NOT_FOUND`, `*_AMBIGUOUS`, `WINDOW_CLOSED`, `TEMPLATE_NOT_APPROVED`, etc.) y los guards de billing (`WALLET_BLOCKED`, `VISION_WALLET_BLOCKED`) **nunca escalan** — el integrador corrige y reintenta sin necesidad de atención humana. actions: type: array items: $ref: '#/components/schemas/ActionGroupAction' minItems: 1 maxItems: 10 description: >- Acciones a ejecutar en orden del array. Mínimo 1, máximo 10. Subcap: máximo 3 acciones AI-triggering (`run_ai`, `ai_assistance`, y `assign_ai_employee` con `run: true`). required: - conversation - actions ActionGroupAccepted: type: object properties: conversation: type: object properties: uuid: type: string format: uuid required: - uuid status: type: string enum: - processing example: processing description: >- El grupo fue aceptado y se ejecuta en background — la respuesta no espera a las acciones. actions_accepted: type: integer minimum: 1 example: 3 description: >- Cantidad de acciones aceptadas para ejecución — igual al largo del array `actions` enviado. required: - conversation - status - actions_accepted PublicError: type: object properties: code: type: string example: INVALID_API_TOKEN message: type: string example: >- The provided API token is invalid or has been revoked. Generate a new one in Settings → API Token. required: - code - message description: >- Public API error body. The client should match against `code` (stable canonical identifier) and NOT against `message` (human text, may be refined between API versions without notice). The HTTP status code is the error-type signal (4xx client, 5xx server). SlugPathParam: type: string example: acme description: >- Slug del business, case-insensitive. Debe coincidir con el business del token. ConversationRef: type: object properties: uuid: type: string format: uuid description: >- UUID interno de 1TO1 AI. Fallback — los CRMs externos normalmente no lo conocen. whatsapp_user_id: type: string description: >- BSUID de WhatsApp (identidad opaca de Meta). Se resuelve por igualdad exacta contra el identificador BSUID del contacto (no se normaliza). username: type: string example: '@mariana.lopez' description: >- Username público de WhatsApp del contacto. Se acepta con o sin `@` inicial y sin distinguir mayúsculas (match case-insensitive contra el último username observado por la plataforma; best-effort: el usuario puede cambiarlo — la clave estable es `uuid`). Si varios contactos lo comparten, la API responde 409 `USERNAME_AMBIGUOUS`. phone: type: string example: +52 55 1234 5678 description: >- Teléfono en formato E.164. Se normaliza (solo dígitos) antes del lookup por teléfono del contacto. Puede estar duplicado entre contactos (números reciclados / identidades separadas): en ese caso la API responde 409 `PHONE_NUMBER_AMBIGUOUS` en vez de adivinar. description: >- Identificador de la conversación — exactamente UNO de los cuatro campos debe venir. Orden de resolución: uuid > whatsapp_user_id > username > phone. El lookup filtra por el business del token (defense in depth cross-tenant). Resolver por `phone` o `username` puede devolver 409 (`PHONE_NUMBER_AMBIGUOUS` / `USERNAME_AMBIGUOUS`) cuando varios contactos comparten el identificador — aplica a cualquier endpoint que acepte esta referencia. ActionGroupAction: oneOf: - $ref: '#/components/schemas/SendMessageAction' - $ref: '#/components/schemas/SendQuickReplyOrTemplateAction' - $ref: '#/components/schemas/AssignLabelAction' - $ref: '#/components/schemas/RemoveLabelAction' - $ref: '#/components/schemas/AssignMailboxAction' - $ref: '#/components/schemas/ContextNoteAction' - $ref: '#/components/schemas/MarkResolvedAction' - $ref: '#/components/schemas/MarkPendingAction' - $ref: '#/components/schemas/RunAiAction' - $ref: '#/components/schemas/AiAssistanceAction' - $ref: '#/components/schemas/AssignAiEmployeeAction' - $ref: '#/components/schemas/UnassignAiAction' discriminator: propertyName: type mapping: send_message: $ref: '#/components/schemas/SendMessageAction' send_quick_reply_or_template: $ref: '#/components/schemas/SendQuickReplyOrTemplateAction' assign_label: $ref: '#/components/schemas/AssignLabelAction' remove_label: $ref: '#/components/schemas/RemoveLabelAction' assign_mailbox: $ref: '#/components/schemas/AssignMailboxAction' context_note: $ref: '#/components/schemas/ContextNoteAction' mark_resolved: $ref: '#/components/schemas/MarkResolvedAction' mark_pending: $ref: '#/components/schemas/MarkPendingAction' run_ai: $ref: '#/components/schemas/RunAiAction' ai_assistance: $ref: '#/components/schemas/AiAssistanceAction' assign_ai_employee: $ref: '#/components/schemas/AssignAiEmployeeAction' unassign_ai: $ref: '#/components/schemas/UnassignAiAction' description: >- Una acción del grupo. El campo `type` discrimina entre las 12 operaciones disponibles. SendMessageAction: type: object properties: type: type: string enum: - send_message body: type: string example: Hola! Gracias por tu compra. description: >- Texto del mensaje (modo texto). Con `file_uuid` actúa de caption (máx 1024 chars). Ignorado en modo quick reply / template. file_uuid: type: string format: uuid description: >- UUID de un archivo ya confirmado vía `POST /files/confirm` (modo media). reply_to_uuid: type: string format: uuid description: UUID de un mensaje previo para citar (reply). Opcional. quick_reply: allOf: - $ref: '#/components/schemas/ActionQuickReplyRef' - description: Referencia a una quick reply a enviar (modo quick reply). template: allOf: - $ref: '#/components/schemas/ActionTemplateInput' - description: >- Template a enviar (modo template). Es el único modo enviable con la ventana de 24h cerrada. required: - type description: >- Envía un mensaje. **Exactamente un modo:** `body`/`file_uuid` (texto o media), `quick_reply`, o `template`. Espejo de los endpoints `/conversation/messages/{text,quick-reply,template}`. SendQuickReplyOrTemplateAction: type: object properties: type: type: string enum: - send_quick_reply_or_template quick_reply: allOf: - $ref: '#/components/schemas/ActionQuickReplyRef' - description: Quick reply a enviar cuando la ventana de 24h está **abierta**. template: allOf: - $ref: '#/components/schemas/ActionTemplateInput' - description: >- Plantilla a enviar cuando la ventana de 24h está **cerrada** (el template es el único mensaje enviable fuera de la ventana). required: - type - quick_reply - template description: >- Envía una **quick reply** si la ventana de 24h de la conversación está abierta, o una **plantilla** si está cerrada. El modo lo decide la acción en tiempo de ejecución según el estado de la ventana — pensada para campañas, donde el estado varía por conversación. Ambos campos son obligatorios. AssignLabelAction: type: object properties: type: type: string enum: - assign_label tags: type: array items: $ref: '#/components/schemas/ActionTagRef' minItems: 1 maxItems: 20 description: Tags a asignar a la conversación. Entre 1 y 20 por acción. required: - type - tags description: >- Asigna uno o más tags a la conversación. Espejo de `POST /conversation/tags`. RemoveLabelAction: type: object properties: type: type: string enum: - remove_label tags: type: array items: $ref: '#/components/schemas/ActionTagRef' minItems: 1 maxItems: 20 description: Tags a quitar de la conversación. Entre 1 y 20 por acción. required: - type - tags description: >- Quita uno o más tags de la conversación. Espejo de `DELETE /conversation/tags`. AssignMailboxAction: type: object properties: type: type: string enum: - assign_mailbox mailbox: allOf: - $ref: '#/components/schemas/ActionMailboxRef' - description: Mailbox de destino. Mutuamente excluyente con `category`. category: allOf: - $ref: '#/components/schemas/ActionMailboxCategoryRef' - description: >- Categoría de mailbox de destino. Mutuamente excluyente con `mailbox`. required: - type description: >- Mueve la conversación a un mailbox. **Exactamente uno de `mailbox` / `category`.** Espejo de `POST /conversation/mailbox`. ContextNoteAction: type: object properties: type: type: string enum: - context_note note: type: string minLength: 1 maxLength: 5000 example: Cliente prefiere ser contactado por las tardes. description: >- Texto de la nota interna (1–5000 chars). Visible solo para el equipo. required: - type - note description: >- Agrega una nota interna a la conversación. Espejo de `POST /conversation/notes`. MarkResolvedAction: type: object properties: type: type: string enum: - mark_resolved required: - type description: >- Marca la conversación como `resolved` (cierra el handoff humano). No toca el empleado AI asignado. Espejo de `POST /conversation/resolve`. MarkPendingAction: type: object properties: type: type: string enum: - mark_pending required: - type description: >- Marca la conversación como `pending` (reabre el handoff humano). No toca el empleado AI asignado. Espejo de `POST /conversation/pending`. RunAiAction: type: object properties: type: type: string enum: - run_ai ai_employee: allOf: - $ref: '#/components/schemas/ActionAiEmployeeRef' - description: >- Empleado AI a ejecutar. Si se omite, ejecuta el empleado AI asignado a la conversación. Si una acción `assign_ai_employee` lo precede en el grupo, ejecuta el empleado que ese `assign` deja asignado — resuelto en runtime, no del snapshot del preflight. instructions: type: string minLength: 1 maxLength: 1000 example: Responde al cliente que el descuento aplica hasta el viernes. description: Instrucciones extra para el empleado AI (máx 1000 chars). required: - type description: >- Ejecuta un empleado AI sobre la conversación. Acción AI-triggering. Espejo de `POST /conversation/run-ai`. AiAssistanceAction: type: object properties: type: type: string enum: - ai_assistance ai_employee: allOf: - $ref: '#/components/schemas/ActionAiEmployeeRef' - description: Empleado AI al que se le pide la consulta puntual. Obligatorio. instructions: type: string minLength: 1 maxLength: 1000 example: ¿Este cliente califica para el plan empresarial? description: Instrucciones / consulta para el empleado AI (máx 1000 chars). required: - type - ai_employee description: >- Consulta puntual a otro empleado AI sin reasignar la conversación. Acción AI-triggering. Espejo de `POST /conversation/ai-assistance`. AssignAiEmployeeAction: type: object properties: type: type: string enum: - assign_ai_employee ai_employee: allOf: - $ref: '#/components/schemas/ActionAiEmployeeRef' - description: Empleado AI operative a asignar. Obligatorio. run: type: boolean default: false example: false description: >- `false` (default) solo asigna. `true` asigna y ejecuta al empleado AI inmediatamente (cuenta como acción AI-triggering). instructions: type: string minLength: 1 maxLength: 1000 description: >- Instrucciones extra para el empleado AI. Solo aplica con `run: true`. scheduled_message_action: type: string enum: - reassign - cancel example: cancel description: >- Decisión sobre el mensaje programado activo al cambiar el AI. Obligatorio cuando la transición es AI → otro AI con schedule activo. required: - type - ai_employee description: >- Asigna un empleado AI a la conversación; con `run: true` además lo ejecuta (solo entonces cuenta como AI-triggering). Espejo de `POST /conversation/ai-employee`. UnassignAiAction: type: object properties: type: type: string enum: - unassign_ai required: - type description: >- Retira el empleado AI asignado (`ai_employee_id → NULL`), dejando la conversación atendida por un humano. Cancela el mensaje programado activo del AI (si lo hay). Idempotente: desasignar una conversación ya sin AI es un no-op exitoso. Espejo de `POST /conversation/unassign-ai`. ActionQuickReplyRef: type: object properties: uuid: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 name: type: string example: saludo-bienvenida description: >- Referencia a una quick reply. Al menos uno de `uuid` / `name` debe venir. ActionTemplateInput: type: object properties: name: type: string example: confirmacion_cita description: Nombre del template aprobado por Meta (alfanumérico + underscore). language: type: string example: es_MX description: >- Idioma del template (formato Meta `es`, `es_MX`, `pt_BR`). Solo requerido si el nombre existe en varios idiomas. body_variables: type: array items: type: object properties: index: type: integer minimum: 1 example: 1 value: type: string example: Ana required: - index - value description: >- Variables del body del template — `{index, value}` con index 1-based. header: type: object properties: type: type: string enum: - text - image - video - document example: image text: type: string description: Solo para header `text`. file_uuid: type: string format: uuid description: >- Solo para header media — `file_uuid` de un archivo ya confirmado. filename: type: string description: Solo para header `document`. required: - type description: >- Header del template. Para media el cliente pasa `file_uuid` (no URLs). Ver `POST /conversation/messages/template` para el shape discriminado completo. button_parameters: type: array items: type: object properties: subType: type: string enum: - url example: url index: type: integer minimum: 0 example: 0 text: type: string example: ver-promo required: - subType - index - text description: Parámetros para botones URL con placeholder dinámico. required: - name description: >- Entrada del modo `template` de `send_message`. Replica el contrato de `POST /conversation/messages/template`. ActionTagRef: type: object properties: uuid: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 description: UUID del tag. Preferido si el cliente lo sincroniza. name: type: string example: VIP description: Nombre del tag. Case-insensitive, trim aplicado server-side. description: >- Referencia a un tag. Al menos uno de `uuid` / `name` debe venir. Si el nombre matchea más de un tag, esa acción falla con `TAG_AMBIGUOUS`. ActionMailboxRef: type: object properties: uuid: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 name: type: string example: Soporte description: >- Referencia a un mailbox. Al menos uno de `uuid` / `name` debe venir. Mutuamente excluyente con `category` dentro de la acción `assign_mailbox`. ActionMailboxCategoryRef: type: object properties: uuid: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 name: type: string example: Ventas description: >- Referencia a una categoría de mailbox. Al menos uno de `uuid` / `name` debe venir. Mutuamente excluyente con `mailbox` dentro de la acción `assign_mailbox`. ActionAiEmployeeRef: type: object properties: uuid: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 name: type: string example: Asistente de Ventas description: >- Referencia a un empleado AI operative. Al menos uno de `uuid` / `name` debe venir. Si pasas ambos prevalece `name` con fallback a `uuid`. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: sk_1to1_ description: >- API token emitido desde Settings → API Token del dashboard 1TO1 AI. Enviar en header Authorization: Bearer sk_1to1_... ````