> ## 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. # Cambiar buzón de conversación > Cambia el buzón al que está asignada la conversación. Dos modos: - `mailbox`: asigna al buzón específico. Identificación por `uuid` o por `name` (único por business case-insensitive con TRIM, vía `idx_mailboxes_unique_name_per_business`). El mismo `name` resuelve mailboxes regulares y defaults — no requiere identificar la categoría. - `category`: delega a **load balancing** — el servidor elige el buzón con menos chats pendientes dentro de la categoría indicada (uuid o name). Idempotente por buzón específico: si la conversación ya está en ese buzón, responde `409 MAILBOX_ALREADY_ASSIGNED`. Por categoría el load balancer puede reelegir el mismo buzón; no se considera error. El evento queda registrado en el timeline con autor `api_token`; el audit fino vive en Activity Log. ## OpenAPI ````yaml /openapi.json post /{slug}/conversation/mailbox 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/mailbox: post: tags: - Conversations summary: Cambiar buzón de conversación description: >- Cambia el buzón al que está asignada la conversación. Dos modos: - `mailbox`: asigna al buzón específico. Identificación por `uuid` o por `name` (único por business case-insensitive con TRIM, vía `idx_mailboxes_unique_name_per_business`). El mismo `name` resuelve mailboxes regulares y defaults — no requiere identificar la categoría. - `category`: delega a **load balancing** — el servidor elige el buzón con menos chats pendientes dentro de la categoría indicada (uuid o name). Idempotente por buzón específico: si la conversación ya está en ese buzón, responde `409 MAILBOX_ALREADY_ASSIGNED`. Por categoría el load balancer puede reelegir el mismo buzón; no se considera error. El evento queda registrado en el timeline con autor `api_token`; el audit fino vive en Activity Log. parameters: - $ref: '#/components/parameters/SlugPathParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssignMailboxRequest' examples: mailboxByUuid: summary: Mailbox específico por UUID description: >- Asigna al buzón con UUID exacto. No aplica load balancing — si la conversación ya está en ese buzón, responde 409 MAILBOX_ALREADY_ASSIGNED. value: conversation: phone: '+525512345678' mailbox: uuid: 550e8400-e29b-41d4-a716-446655440000 mailboxByName: summary: Mailbox por nombre description: >- Identificación por el string que el agente ve en el dashboard. Único por business case-insensitive con TRIM. AMBIGUOUS_MAILBOX queda como defense-in-depth (el constraint hace que no pase en runtime). value: conversation: phone: '+525512345678' mailbox: name: Ventas · Turno matutino categoryByUuid: summary: Categoría por UUID (load balancing) description: >- Delega al RPC de load balancing — el servidor elige el buzón con menos chats pendientes dentro de la categoría. value: conversation: phone: '+525512345678' category: uuid: 550e8400-e29b-41d4-a716-446655440000 categoryByName: summary: Categoría por nombre (load balancing) description: >- Igual que el caso anterior pero identificando la categoría por nombre. El nombre es único por business, así que no hay ambigüedad. value: conversation: phone: '+525512345678' category: name: Ventas responses: '200': description: Buzón asignado correctamente. 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/AssignMailboxResponse' '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' '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), mailbox (MAILBOX_NOT_FOUND), categoría (CATEGORY_NOT_FOUND) o no hay buzones disponibles en la categoría (NO_MAILBOXES_IN_CATEGORY). 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: >- La conversación ya está en ese buzón (MAILBOX_ALREADY_ASSIGNED), `name` de mailbox coincide con múltiples mailboxes (AMBIGUOUS_MAILBOX) o `name` de categoría coincide con múltiples categorías (AMBIGUOUS_CATEGORY). Ambos AMBIGUOUS son defense-in-depth — no esperados tras P10a por los unique constraints. 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' '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 (UPDATE_FAILED) o de lookup (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: AssignMailboxRequest: allOf: - type: object properties: conversation: $ref: '#/components/schemas/ConversationRef' required: - conversation - oneOf: - type: object properties: mailbox: oneOf: - $ref: '#/components/schemas/MailboxRefByUuid' - $ref: '#/components/schemas/MailboxRefByName' required: - mailbox - type: object properties: category: oneOf: - $ref: '#/components/schemas/CategoryRefByUuid' - $ref: '#/components/schemas/CategoryRefByName' required: - category AssignMailboxResponse: type: object properties: conversation: type: object properties: uuid: type: string format: uuid required: - uuid mailbox: type: object properties: uuid: type: string format: uuid name: type: string example: Ventas · Turno matutino required: - uuid - name required: - conversation - mailbox 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. MailboxRefByUuid: type: object properties: uuid: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 required: - uuid MailboxRefByName: type: object properties: name: type: string minLength: 1 maxLength: 64 example: Ventas · Turno matutino description: >- Nombre del mailbox. Único por business case-insensitive ignorando espacios en extremos (`mailboxes` con UNIQUE en `(business_id, LOWER(TRIM(name)))`). El servidor aplica `trim` y exige longitud entre 1 y 64 caracteres post-trim. required: - name CategoryRefByUuid: type: object properties: uuid: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 required: - uuid CategoryRefByName: type: object properties: name: type: string minLength: 1 maxLength: 64 example: Ventas description: >- Nombre de la categoría de mailboxes. Único por business case-insensitive con `trim`. Longitud post-trim 1–64 caracteres. required: - name 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_... ````