> ## 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. # Estado puntual de una conversación > Devuelve el estado público de una conversación: ventana 24h, asignación, buzón, tags, inbox_status y último mensaje. Operación de **lectura pura** — idempotente, sin side effects. **Campos clave:** - `window.status` — `"open"` si puedes enviar mensajes libres; `"closed"` si necesitas template primero. - `assignment.type` — `"ai_employee"` cuando hay AI asignado (`ai_employee_id !== null`); `"human"` cuando la conversación es atendida por humano (`ai_employee_id === null`). Un `inbox_status === "pending"` no bloquea la ejecución AI desde la API (`/run-ai`, `/ai-employee run=true` y `/ai-assistance` corren bajo responsabilidad del caller). Para dejar la conversación en `"human"` usa `POST /conversation/unassign-ai`. - `mailbox` — `null` si la conversación no tiene buzón asignado. - `tags` — lista de etiquetas vigentes (sin las soft-deleted). - `is_tester` — `true` en conversaciones del módulo tester. El servidor respeta el reloj virtual (`tester_virtual_now`) al calcular `hours_remaining`. **POST (no GET)** — la conversación se identifica por body (`phone` / `whatsapp_user_id` / `username` / `uuid`) siguiendo la convención de `/conversation/*`. El endpoint NO muta nada; el audit queda con `read_conversation_status` para trazar quién consulta qué. ## OpenAPI ````yaml /openapi.json post /{slug}/conversation/status 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/status: post: tags: - Conversations summary: Estado puntual de una conversación description: >- Devuelve el estado público de una conversación: ventana 24h, asignación, buzón, tags, inbox_status y último mensaje. Operación de **lectura pura** — idempotente, sin side effects. **Campos clave:** - `window.status` — `"open"` si puedes enviar mensajes libres; `"closed"` si necesitas template primero. - `assignment.type` — `"ai_employee"` cuando hay AI asignado (`ai_employee_id !== null`); `"human"` cuando la conversación es atendida por humano (`ai_employee_id === null`). Un `inbox_status === "pending"` no bloquea la ejecución AI desde la API (`/run-ai`, `/ai-employee run=true` y `/ai-assistance` corren bajo responsabilidad del caller). Para dejar la conversación en `"human"` usa `POST /conversation/unassign-ai`. - `mailbox` — `null` si la conversación no tiene buzón asignado. - `tags` — lista de etiquetas vigentes (sin las soft-deleted). - `is_tester` — `true` en conversaciones del módulo tester. El servidor respeta el reloj virtual (`tester_virtual_now`) al calcular `hours_remaining`. **POST (no GET)** — la conversación se identifica por body (`phone` / `whatsapp_user_id` / `username` / `uuid`) siguiendo la convención de `/conversation/*`. El endpoint NO muta nada; el audit queda con `read_conversation_status` para trazar quién consulta qué. parameters: - $ref: '#/components/parameters/SlugPathParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConversationStatusRequest' examples: byPhone: summary: Por número de teléfono value: conversation: phone: '+525512345678' byUuid: summary: Por UUID directo value: conversation: uuid: 7b8a9c6d-1234-5678-9abc-def012345678 responses: '200': description: Snapshot del estado de la conversació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/ConversationStatusResponse' '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 no encontrada (CONVERSATION_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: >- 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`. 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 estado (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: ConversationStatusRequest: type: object properties: conversation: $ref: '#/components/schemas/ConversationRef' required: - conversation ConversationStatusResponse: type: object properties: conversation: type: object properties: uuid: type: string format: uuid phone: type: - string - 'null' example: '529612864799' description: >- Teléfono del contacto: WhatsApp `wa_id` raw (NO E.164 — sin prefijo `+`, p.ej. "529612864799"). Identificador legacy; coincide con `whatsapp_user_id` solo cuando el contacto aún no tiene BSUID. El request del endpoint acepta formato E.164 con `+` y lo normaliza a dígitos antes del lookup por teléfono. whatsapp_user_id: type: - string - 'null' description: >- Identificador forward-compatible del contacto. Devuelve el BSUID real (identidad opaca de Meta) cuando el contacto lo tiene; mientras Meta no migre, hace fallback al `wa_id` (`phone`) para que siempre haya un valor resoluble. Si el contacto aún no tiene BSUID, este campo trae el teléfono: para resolver la conversación reenvíalo como `phone`, no como `whatsapp_user_id` (el resolver solo acepta BSUIDs reales y daría `404`). **Source of truth recomendado para nuevos clientes** — `phone` se mantiene en paralelo por compatibilidad. required: - uuid - phone - whatsapp_user_id window: $ref: '#/components/schemas/ConversationWindow' assignment: $ref: '#/components/schemas/ConversationAssignment' mailbox: $ref: '#/components/schemas/ConversationStatusMailbox' tags: type: array items: $ref: '#/components/schemas/ConversationStatusTag' inbox_status: type: string enum: - pending - resolved example: pending description: >- Estado del inbox: `pending` (aún no resuelta) o `resolved` (cerrada por el equipo). last_message: $ref: '#/components/schemas/ConversationStatusLastMessage' is_tester: type: boolean description: >- Si `true`, la conversación pertenece al módulo tester (ficticia). No se envían mensajes reales a Meta. tester_virtual_now: type: - string - 'null' format: date-time description: >- Hora virtual actual (`now() + virtual_offset`) — solo cuando `is_tester=true`. Útil para correlacionar con el dashboard del tester sin otra request. required: - conversation - window - assignment - mailbox - tags - inbox_status - last_message - is_tester - tester_virtual_now 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. ConversationWindow: type: object properties: status: type: string enum: - open - closed example: open description: Estado de la ventana de 24h de WhatsApp. expires_at: type: - string - 'null' format: date-time description: >- ISO timestamp de cierre de ventana. `null` si nunca se abrió (el contacto jamás envió un mensaje). hours_remaining: type: - number - 'null' example: 18.5 description: >- Horas restantes hasta el cierre (redondeado a 2 decimales). `null` si la ventana está cerrada. required: - status - expires_at - hours_remaining ConversationAssignment: type: object properties: type: type: string enum: - ai_employee - human description: >- `ai_employee` cuando hay un empleado AI asignado (`ai_employee_id !== null`). `human` cuando la conversación es atendida por un humano (`ai_employee_id === null`). Son los dos únicos estados — antes existía `unassigned` y un flag separado `human_assistance_status`, ambos deprecados en abril 2026. ai_employee: type: - object - 'null' properties: uuid: type: string format: uuid name: type: string required: - uuid - name description: Empleado AI asignado (si aplica). required: - type - ai_employee ConversationStatusMailbox: type: - object - 'null' properties: uuid: type: string format: uuid name: type: string required: - uuid - name ConversationStatusTag: type: object properties: uuid: type: string format: uuid name: type: string color: type: - string - 'null' required: - uuid - name - color ConversationStatusLastMessage: type: - object - 'null' properties: uuid: type: string format: uuid author_type: type: string enum: - customer - ai_employee - api_token - human - mass_campaign - unknown description: >- Tipo de autor del último mensaje. `unknown` solo aplica a mensajes legacy sin `meta_data.author.type`. is_from_customer: type: boolean created_at: type: string format: date-time required: - uuid - author_type - is_from_customer - created_at 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_... ````