> ## 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 empleado AI > Ejecuta un empleado AI sobre la conversación. - **Sin `ai_employee`** → ejecuta el empleado AI **asignado**. Si la conversación la atiende un humano (`ai_employee_id IS NULL`), devuelve `INVALID_ASSIGNEE_FOR_RUN_AI` (409): el caller debe pasar `ai_employee` explícito o reasignar un AI con `POST /conversation/ai-employee`. - **Con `ai_employee`** → ejecuta ese empleado aunque no esté asignado a la conversación. Si coincide con el asignado corre como `run_assigned`; si difiere, como ejecución transient que **no cambia** `ai_employee_id`. Paridad con el botón "Ejecutar agente" del dashboard. Identificación del empleado: `ai_employee` acepta `uuid` y/o `name`. Si pasas ambos prevalece `name` con fallback a `uuid`. Solo resuelve empleados operativos activos. **Preconditions:** - Ventana de 24h abierta (`WINDOW_CLOSED` si cerrada). El AI responde al cliente — con la ventana cerrada el mensaje no se entrega. - Wallet del empleado a ejecutar OK. - Visión OK (fail-closed si hay items pending — el AI podría necesitar interpretarlos). - Grafo de action sets dentro del límite de profundidad (`ACTIONS_DEPTH_EXCEEDED`). **No** aplica guard de `inbox_status`: la API puede ejecutar el AI sobre una conversación `pending` bajo responsabilidad del caller. **Ejecución asíncrona:** los guards corren síncronos; si pasan, el endpoint responde `202 Accepted` de inmediato y el empleado AI se ejecuta en background. La respuesta **no espera** al empleado — el run con reasoning puede tardar minutos. Los mensajes generados y el uso de tokens se notificarán por webhook (feature futura). Si un guard falla, se responde un 4xx síncrono y el AI no se ejecuta. ## OpenAPI ````yaml /openapi.json post /{slug}/conversation/run-ai 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/run-ai: post: tags: - Conversations summary: Ejecutar empleado AI description: >- Ejecuta un empleado AI sobre la conversación. - **Sin `ai_employee`** → ejecuta el empleado AI **asignado**. Si la conversación la atiende un humano (`ai_employee_id IS NULL`), devuelve `INVALID_ASSIGNEE_FOR_RUN_AI` (409): el caller debe pasar `ai_employee` explícito o reasignar un AI con `POST /conversation/ai-employee`. - **Con `ai_employee`** → ejecuta ese empleado aunque no esté asignado a la conversación. Si coincide con el asignado corre como `run_assigned`; si difiere, como ejecución transient que **no cambia** `ai_employee_id`. Paridad con el botón "Ejecutar agente" del dashboard. Identificación del empleado: `ai_employee` acepta `uuid` y/o `name`. Si pasas ambos prevalece `name` con fallback a `uuid`. Solo resuelve empleados operativos activos. **Preconditions:** - Ventana de 24h abierta (`WINDOW_CLOSED` si cerrada). El AI responde al cliente — con la ventana cerrada el mensaje no se entrega. - Wallet del empleado a ejecutar OK. - Visión OK (fail-closed si hay items pending — el AI podría necesitar interpretarlos). - Grafo de action sets dentro del límite de profundidad (`ACTIONS_DEPTH_EXCEEDED`). **No** aplica guard de `inbox_status`: la API puede ejecutar el AI sobre una conversación `pending` bajo responsabilidad del caller. **Ejecución asíncrona:** los guards corren síncronos; si pasan, el endpoint responde `202 Accepted` de inmediato y el empleado AI se ejecuta en background. La respuesta **no espera** al empleado — el run con reasoning puede tardar minutos. Los mensajes generados y el uso de tokens se notificarán por webhook (feature futura). Si un guard falla, se responde un 4xx síncrono y el AI no se ejecuta. parameters: - $ref: '#/components/parameters/SlugPathParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RunAiBody' responses: '202': description: >- Run aceptado. Los guards (ventana, wallet, visión, depth) pasaron y el empleado AI se ejecuta en background — la respuesta no espera al empleado. 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/RunAiResponse' '400': description: Body inválido (INVALID_REQUEST). 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: >- Wallet bloqueada (WALLET_BLOCKED / VISION_WALLET_BLOCKED) o visión con items pending (VISION_BLOCKED). 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: >- Conversación (CONVERSATION_NOT_FOUND) o empleado AI pasado en `ai_employee` (AI_EMPLOYEE_NOT_FOUND) no encontrado. 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: >- Sin `ai_employee` y la conversación la atiende un humano (INVALID_ASSIGNEE_FOR_RUN_AI — no hay AI que ejecutar; pasar `ai_employee` o reasignar uno). O bien `name` matchea más de un empleado (AMBIGUOUS_AI_EMPLOYEE — pasar `uuid` para desempatar). Además, el identificador de conversación puede resultar 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`. 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: >- Ventana 24h cerrada (WINDOW_CLOSED), grafo de action sets excede profundidad (ACTIONS_DEPTH_EXCEEDED), o el empleado asignado fue desactivado/soft-deleted entre el snapshot y la resolución (NO_AI_EMPLOYEE_ASSIGNED — race; 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' '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 ejecución (FETCH_FAILED). 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: RunAiBody: type: object properties: conversation: $ref: '#/components/schemas/ConversationRef' ai_employee: type: object properties: uuid: type: string format: uuid name: type: string minLength: 1 maxLength: 128 description: >- Empleado AI a ejecutar. Opcional: si se omite, se ejecuta el empleado asignado a la conversación. Si se pasa, ejecuta ese empleado aunque no esté asignado (transient — no cambia `ai_employee_id`). Acepta `uuid` y/o `name`; si pasas ambos prevalece `name` con fallback a `uuid`. instructions: type: string minLength: 1 maxLength: 1000 example: Responde al cliente que el descuento aplica hasta el viernes description: >- Instrucciones adicionales que se pasan al empleado además del contexto de la conversación. Min 1, max 1000 chars (whitespace al inicio/final se trimea). required: - conversation RunAiResponse: type: object properties: conversation: type: object properties: uuid: type: string format: uuid required: - uuid ai_employee: type: object properties: uuid: type: string format: uuid name: type: string required: - uuid - name status: type: string enum: - processing example: processing description: >- El run fue aceptado y el empleado AI se ejecuta en background. La respuesta NO espera al empleado — los mensajes generados y el uso de tokens se notificarán por webhook (feature futura). required: - conversation - ai_employee - status 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. 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_... ````