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
conversationse 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 Acceptedinmediato{ 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
202solo 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, yassign_ai_employeeconrun: true. Excederlo también devuelveBATCH_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.
Las 11 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 |
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).
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.
Autorizaciones
API token emitido desde Settings → API Token del dashboard 1TO1 AI. Enviar en header Authorization: Bearer sk_1to1_...
Parámetros de ruta
Slug del business, case-insensitive. Debe coincidir con el business del token.
"acme"
Cuerpo
Identificador de la conversación — al menos UNO de los tres campos debe venir. Orden de resolución: uuid > whatsapp_user_id > phone. El lookup filtra por el business del token (defense in depth cross-tenant).
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).
1 - 10 elementsUna acción del grupo. El campo type discrimina entre las 11 operaciones disponibles.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
- Option 11
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.
true
Respuesta
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.
El grupo fue aceptado y se ejecuta en background — la respuesta no espera a las acciones.
processing "processing"
Cantidad de acciones aceptadas para ejecución — igual al largo del array actions enviado.
x >= 13