> ## 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. # Asignar empleado AI a conversación > Asigna un empleado AI (tipo `operative`) a la conversación. El cambio queda registrado en el timeline con autor `api_token` y el dashboard recibe el update en tiempo real (evento `ai_employee_changed`). - Solo se pueden asignar empleados de tipo **operative**. Los tipos `json` y `vision` son internos del sistema — si envías un uuid/name de esos, responde `AI_EMPLOYEE_NOT_FOUND`. - Identificación: `ai_employee` acepta `uuid` y/o `name`. Si pasas ambos, prevalece `name` y el `uuid` es fallback (útil cuando el empleado se renombra). - Para ejecutar el AI inmediatamente después de asignar, llama a `POST /conversation/run-ai` — si quieres hacer ambas cosas en una sola request, está `POST /conversation/ai-employee` con `run: true` (P9 Fase 3). - **Schedule activo:** si la conversación tiene un mensaje programado pendiente, la transición humano↔AI lo cancela siempre (reglas 3.3/3.5 del producto) y la transición AI → otro AI exige `scheduled_message_action` explícito (regla 3.2 — sin default). Ver [docs/public-api/assignments.md § Reasignación con schedule activo](../../../docs/public-api/assignments.md#reasignación-con-schedule-activo). - **Ejecución asíncrona (`run: true`):** la asignación y los broadcasts corren síncronos; una vez confirmada la asignación, el empleado AI se ejecuta en background y el endpoint responde `202 Accepted` sin esperar al run. El run con reasoning puede tardar minutos. Los mensajes generados y el uso de tokens se notificarán por webhook (feature futura). ## OpenAPI ````yaml /openapi.json post /{slug}/conversation/ai-employee 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/ai-employee: post: tags: - Conversations summary: Asignar empleado AI a conversación description: >- Asigna un empleado AI (tipo `operative`) a la conversación. El cambio queda registrado en el timeline con autor `api_token` y el dashboard recibe el update en tiempo real (evento `ai_employee_changed`). - Solo se pueden asignar empleados de tipo **operative**. Los tipos `json` y `vision` son internos del sistema — si envías un uuid/name de esos, responde `AI_EMPLOYEE_NOT_FOUND`. - Identificación: `ai_employee` acepta `uuid` y/o `name`. Si pasas ambos, prevalece `name` y el `uuid` es fallback (útil cuando el empleado se renombra). - Para ejecutar el AI inmediatamente después de asignar, llama a `POST /conversation/run-ai` — si quieres hacer ambas cosas en una sola request, está `POST /conversation/ai-employee` con `run: true` (P9 Fase 3). - **Schedule activo:** si la conversación tiene un mensaje programado pendiente, la transición humano↔AI lo cancela siempre (reglas 3.3/3.5 del producto) y la transición AI → otro AI exige `scheduled_message_action` explícito (regla 3.2 — sin default). Ver [docs/public-api/assignments.md § Reasignación con schedule activo](../../../docs/public-api/assignments.md#reasignación-con-schedule-activo). - **Ejecución asíncrona (`run: true`):** la asignación y los broadcasts corren síncronos; una vez confirmada la asignación, el empleado AI se ejecuta en background y el endpoint responde `202 Accepted` sin esperar al run. El run con reasoning puede tardar minutos. Los mensajes generados y el uso de tokens se notificarán por webhook (feature futura). parameters: - $ref: '#/components/parameters/SlugPathParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssignAiEmployeeRequest' responses: '200': description: Empleado AI asignado (`run=false` — asignación pura). 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/AssignAiEmployeeResponse' '202': description: >- Solo con `run=true`: empleado AI asignado y su ejecución encolada en background — la respuesta no espera al run del 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/AssignAiEmployeeResponse' '400': description: >- Body inválido (INVALID_REQUEST). Reasignación AI → otro AI con schedule activo sin `scheduled_message_action` (SCHEDULED_MESSAGE_ACTION_REQUIRED) o con valor fuera del enum `cancel`/`reassign` (SCHEDULED_MESSAGE_ACTION_INVALID). 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: >- Solo con `run=true`: wallet del empleado AI bloqueada (WALLET_BLOCKED) o wallet de visión bloqueada / items pending (VISION_WALLET_BLOCKED, 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 no encontrado / no es operative (AI_EMPLOYEE_NOT_FOUND). 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: >- Más de un empleado AI coincide con el `name` (AMBIGUOUS_AI_EMPLOYEE) — pasar `uuid` para desempatar. Solo con `run=false`: el empleado indicado ya es el asignado actual (AI_EMPLOYEE_ALREADY_ASSIGNED). 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: >- Solo con `run=true`: ventana 24h cerrada (WINDOW_CLOSED) o profundidad del grafo de action sets excedida (ACTIONS_DEPTH_EXCEEDED). 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 escribir la asignación (UPDATE_FAILED) o al leer (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: AssignAiEmployeeRequest: type: object properties: conversation: $ref: '#/components/schemas/ConversationRef' ai_employee: $ref: '#/components/schemas/AiEmployeeRef' run: type: boolean default: false example: false description: >- `false` (default) solo asigna y responde `200`. `true` asigna y luego ejecuta al empleado AI en background — agrega los guards de `/run-ai` (ventana 24h, wallet, visión, depth) y responde `202`. El resultado del run (`message_uuids`, `tokens`) NO viene en la respuesta: se notificará por webhook (feature futura). instructions: type: string minLength: 1 maxLength: 1000 example: Confirma la cita y pregunta si quiere recordatorio el día anterior. description: >- Solo aplica con `run=true`. Instrucciones extra que se pasan al empleado AI además del contexto natural de la conversación. Ignorado si `run=false`. scheduled_message_action: type: string enum: - reassign - cancel example: cancel description: >- Decisión sobre el mensaje programado activo de la conversación al cambiar el AI. **Obligatorio cuando la transición es AI → otro AI con un schedule activo** — la API no asume default (regla 3.2). Si se omite en ese caso responde `SCHEDULED_MESSAGE_ACTION_REQUIRED` (400). Para humano↔AI el campo es ignorado y el schedule se cancela siempre (reglas 3.3/3.5). Si se pasa `reassign` con una transición que no es AI→AI, responde `SCHEDULED_MESSAGE_ACTION_INVALID` (400). Si la conversación no tiene schedule activo, el campo también es ignorado. required: - conversation - ai_employee AssignAiEmployeeResponse: type: object properties: conversation: type: object properties: uuid: type: string format: uuid required: - uuid ai_employee: type: object properties: uuid: type: - string - 'null' format: uuid name: type: - string - 'null' required: - uuid - name schedule_action: type: string enum: - preserved - reassigned - cancelled - none example: cancelled description: >- Resultado de la operación sobre el schedule activo. `none` cuando no había schedule (caso normal) o cuando un race con cancel concurrente dejó el UPDATE en 0 filas. `cancelled` cuando se canceló (humano→AI, AI→humano, AI→AI con `cancel`). `reassigned` cuando se preservó apuntando al AI nuevo (AI→AI con `reassign`). `preserved` reservado para futuras semánticas — hoy el orquestador no lo emite. Útil para feedback al cliente externo del cambio aplicado al schedule. status: type: string enum: - processing example: processing description: >- Solo presente con `run=true`: la asignación se aplicó 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 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. AiEmployeeRef: type: object properties: uuid: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 description: >- UUID del empleado AI. Identificador estable; preferido si el cliente lo sincroniza. name: type: string minLength: 1 maxLength: 128 example: Asistente de Ventas description: >- Nombre del empleado AI. Case-insensitive. El servidor aplica `trim` y exige longitud 1–128 caracteres post-trim. Si el nombre coincide con más de uno responde `AMBIGUOUS_AI_EMPLOYEE` — pasar `uuid` para desempatar. description: >- Referencia al empleado AI. Al menos uno de `uuid` / `name` debe venir. Si se pasan ambos, prevalece `name`; si el name no matchea ningún empleado, cae al `uuid` como fallback. 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_... ````