# 1TO1 AI Public API

## Docs

- [Listar empleados AI ejecutables del business](https://docs.1to1ai.com/api-reference/ai-employees/listar-empleados-ai-ejecutables-del-business.md): Devuelve los empleados AI **ejecutables** y activos del business (`is_active = true`, `deleted_at IS NULL`) — tipos `operative` y `json`. Ambos tipos pueden ejecutarse de forma transitoria con `POST /conversation/run-ai` y `POST /conversation/ai-assistance`. La asignación persistente vía `POST /conv…
- [Listar contactos del módulo tester](https://docs.1to1ai.com/api-reference/contacts-tester/listar-contactos-del-módulo-tester.md): Variante del listado que devuelve **solo** contactos creados desde el módulo tester del dashboard (feature donde el usuario usa datos ficticios para probar flujos; `is_tester = true`). Mismo shape de respuesta y paginación que `/contacts`. El listado principal ya incluye reales y tester mezclados —…
- [Listar contactos del business](https://docs.1to1ai.com/api-reference/contacts/listar-contactos-del-business.md): Devuelve contactos del business ordenados por `created_at` desc. Paginación cursor opaco: usa `next_cursor` de la response anterior. Default `limit`=50, máximo 100. Incluye contactos reales y tester mezclados; distinguir por `is_tester`. Para solo-tester existe `/tester/contacts`.
- [Obtener contacto por UUID](https://docs.1to1ai.com/api-reference/contacts/obtener-contacto-por-uuid.md): Devuelve un contacto del business identificado por su UUID. Si no existe o pertenece a otro business, responde 404 (CONTACT_NOT_FOUND) sin distinguir para no exponer enumeración de UUIDs ajenos.
- [Listar conversaciones del módulo tester](https://docs.1to1ai.com/api-reference/conversations-tester/listar-conversaciones-del-módulo-tester.md): Variante del listado que devuelve **solo** conversaciones creadas desde el módulo tester del dashboard (feature donde el usuario prueba flujos con conversaciones ficticias; `is_tester = true`). Mismo shape de respuesta y paginación que `/conversations`. El listado principal ya incluye reales y teste…
- [Agregar nota de contexto](https://docs.1to1ai.com/api-reference/conversations/agregar-nota-de-contexto.md): Agrega una nota de contexto al timeline de la conversación. Útil para que el CRM externo deje registro de información que quieres que el equipo humano (o el AI downstream) considere al retomar el chat — ej. "cliente pidió seguimiento post-vacaciones", "contactó por falla de pagos", etc.
- [Asignar empleado AI a conversación](https://docs.1to1ai.com/api-reference/conversations/asignar-empleado-ai-a-conversación.md): 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`).
- [Cambiar buzón de conversación](https://docs.1to1ai.com/api-reference/conversations/cambiar-buzón-de-conversación.md): Cambia el buzón al que está asignada la conversación. Dos modos:
- [Cerrar handoff humano (marcar resuelta)](https://docs.1to1ai.com/api-reference/conversations/cerrar-handoff-humano-marcar-resuelta.md): Marca una conversación como resuelta:
- [Desasignar empleado AI de conversación](https://docs.1to1ai.com/api-reference/conversations/desasignar-empleado-ai-de-conversación.md): Retira el empleado AI asignado a una conversación:
- [Detalle de conversación](https://docs.1to1ai.com/api-reference/conversations/detalle-de-conversación.md): Devuelve una conversación del business identificada por su UUID.
- [Ejecutar empleado AI](https://docs.1to1ai.com/api-reference/conversations/ejecutar-empleado-ai.md): Ejecuta un empleado AI sobre la conversación.
- [Ejecutar grupo de acciones sobre una conversación](https://docs.1to1ai.com/api-reference/conversations/ejecutar-grupo-de-acciones-sobre-una-conversación.md): 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.
- [Estado puntual de una conversación](https://docs.1to1ai.com/api-reference/conversations/estado-puntual-de-una-conversación.md): 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.
- [Listar conversaciones](https://docs.1to1ai.com/api-reference/conversations/listar-conversaciones.md): Devuelve conversaciones del business ordenadas por `last_message_at`. Paginación cursor opaco: usa `next_cursor` de la response anterior. Default `limit`=50, máximo 100.
- [Listar mensajes de una conversación](https://docs.1to1ai.com/api-reference/conversations/listar-mensajes-de-una-conversación.md): Devuelve mensajes y eventos del timeline de la conversación, ordenados cronológicamente ascendente por `created_at`. **El orden no es configurable** (no soporta un param `order` — a diferencia del endpoint de listado de conversations). Paginación cursor opaco compuesto. Default `limit`=50, máximo 10…
- [Reabrir handoff humano (marcar pendiente)](https://docs.1to1ai.com/api-reference/conversations/reabrir-handoff-humano-marcar-pendiente.md): Marca una conversación como pendiente:
- [Solicitar asistencia AI puntual](https://docs.1to1ai.com/api-reference/conversations/solicitar-asistencia-ai-puntual.md): Ejecuta un empleado AI como **asistencia puntual** sobre la conversación. El empleado consultado genera contexto/sugerencia sin tomar el hilo ni cambiar la asignación.
- [Confirmar upload: validar y obtener signed download](https://docs.1to1ai.com/api-reference/files/confirmar-upload:-validar-y-obtener-signed-download.md): Paso 3 del patrón 2-step. Hace HEAD contra Storage para verificar que el binario llegó y su tamaño matchea el declarado, lee los primeros bytes para validar los magic bytes contra el mime_type, y si todo pasa marca el archivo como `confirmed`. Devuelve un `download_url` para adjuntar el archivo en m…
- [Iniciar upload: obtener signed URL](https://docs.1to1ai.com/api-reference/files/iniciar-upload:-obtener-signed-url.md): Paso 1 del patrón 2-step. Valida mime_type + size_bytes + cuota del business, reserva una fila pending en business_files y devuelve un signed URL con TTL de 5 minutos.
- [Ping de conectividad](https://docs.1to1ai.com/api-reference/health/ping-de-conectividad.md): Devuelve `pong` con metadata del business resuelto desde el token. Sirve para que los clientes validen que su configuración de API key es correcta antes de integrar endpoints reales.
- [Listar categorías de mailbox del business](https://docs.1to1ai.com/api-reference/mailbox-categories/listar-categorías-de-mailbox-del-business.md): Devuelve las categorías de mailbox activas del business (`deleted_at IS NULL`), paginadas por `page` (1-based). Las categorías agrupan mailboxes — cada `MailboxItem` referencia su categoría por `category_uuid`. `search` filtra por substring del nombre (ILIKE, case-insensitive). Default `limit`=20, m…
- [Listar mailboxes del business](https://docs.1to1ai.com/api-reference/mailboxes/listar-mailboxes-del-business.md): Devuelve los mailboxes activos del business (`deleted_at IS NULL`), paginados por `page` (1-based). Útil para descubrir a qué mailbox mover una conversación con `POST /conversation/mailbox`. `search` filtra por substring del nombre (ILIKE, case-insensitive). Default `limit`=20, máximo 100.
- [Enviar mensaje de texto libre](https://docs.1to1ai.com/api-reference/messages/enviar-mensaje-de-texto-libre.md): Envía un mensaje por WhatsApp en nombre del business — texto libre, archivo multimedia, o ambos (texto como caption del archivo). La conversación debe estar dentro de la ventana de 24h (último mensaje del cliente < 24h atrás); si está cerrada, la respuesta es `WINDOW_CLOSED` (422) y el cliente debe…
- [Enviar quick reply (multi-message)](https://docs.1to1ai.com/api-reference/messages/enviar-quick-reply-multi-message.md): Envía un **quick reply** configurado en el business. Un QR puede contener múltiples acciones (text, files, audio, buttons) y cada una emite un mensaje independiente a Meta — por eso la respuesta es un **array** con los mensajes que se generaron en orden.
- [Enviar template (reabre ventana 24h)](https://docs.1to1ai.com/api-reference/messages/enviar-template-reabre-ventana-24h.md): Envía un template de WhatsApp ya aprobado por Meta. **Reabre la ventana de 24h** — se puede usar incluso si el cliente no ha interactuado recientemente. Este es el único tipo de mensaje que puedes enviar fuera de la ventana.
- [Listar quick replies del business](https://docs.1to1ai.com/api-reference/quick-replies/listar-quick-replies-del-business.md): Devuelve las quick replies del business, paginadas por `page` (1-based). Útil para descubrir qué `quick_reply_uuid` enviar con `POST /conversation/messages/quick-reply`. `search` filtra por substring del nombre (ILIKE, case-insensitive). El catálogo expone solo la identidad de la quick reply — el sh…
- [Cancelar schedule pending](https://docs.1to1ai.com/api-reference/schedules/cancelar-schedule-pending.md): Cancela el schedule pending de la conversación. Idempotente: si no hay schedule pending o ya fue ejecutado, retorna `cancelled: false` sin error.
- [Leer schedule pending de una conversación](https://docs.1to1ai.com/api-reference/schedules/leer-schedule-pending-de-una-conversación.md): Retorna el schedule activo (`status=pending`) de la conversación. `data: null` si la conversación existe pero no tiene schedule pending. La conversación debe pertenecer al business del token.
- [Programar mensaje en una conversación](https://docs.1to1ai.com/api-reference/schedules/programar-mensaje-en-una-conversación.md): Programa un mensaje (AI o humano) en una conversación.
- [Asignar tag a conversación](https://docs.1to1ai.com/api-reference/tags/asignar-tag-a-conversación.md): Asocia un tag existente del business a la conversación identificada en el body. La operación es atómica (insert + evento de auditoría). Si el tag ya está asignado responde 409 (TAG_ALREADY_ASSIGNED). Si el tag pertenece a otro business responde 400 (TAG_BUSINESS_MISMATCH). La conversación se identif…
- [Listar tags del business](https://docs.1to1ai.com/api-reference/tags/listar-tags-del-business.md): Devuelve todos los tags activos del business (filtrados por `deleted_at IS NULL`). Default `limit`=100, máximo 500. No pagina por cursor — el set de tags por business es chico (típicamente < 200); `has_more` y `next_cursor` se devuelven como `false`/`null` siempre para mantener shape consistente con…
- [Remover tag de conversación](https://docs.1to1ai.com/api-reference/tags/remover-tag-de-conversación.md): Elimina la asignación del tag en la conversación. La operación es atómica (delete + evento de auditoría). Discrimina por shape: `tag_uuid` borra por uuid; `tag_name` resuelve primero al uuid. Si el tag no está asignado responde 404 (TAG_NOT_ASSIGNED).
- [Detalle de template por name + language](https://docs.1to1ai.com/api-reference/templates/detalle-de-template-por-name-+-language.md): Detalle de un template específico por `name` + `language` — la natural key que maneja Meta y que tu CRM ya conoce. Retorna los `parameters` calculados (body variables, header, button parameters) — usalo para armar el body de `POST /conversation/messages/template` sin tener que parsear el shape de Me…
- [Listar templates APPROVED del business](https://docs.1to1ai.com/api-reference/templates/listar-templates-approved-del-business.md): Lista templates de WhatsApp APPROVED del business. Útil para descubrir qué `template_name` está disponible al usar `POST /conversation/messages/template` o al programar un schedule humano con fallback de template.
- [Grupo de acciones](https://docs.1to1ai.com/es/action-groups.md): Ejecuta hasta 10 acciones sobre una conversación en un solo request.
- [Autenticación](https://docs.1to1ai.com/es/authentication.md): Cómo autenticar tus requests a la API pública de 1TO1 AI.
- [Conversaciones](https://docs.1to1ai.com/es/conversations.md): Cómo se identifica una conversación y por qué la ventana de 24h decide qué puedes enviar.
- [Errores](https://docs.1to1ai.com/es/errors.md): Cómo la API señala los errores y cómo manejarlos.
- [API pública de 1TO1 AI](https://docs.1to1ai.com/es/index.md): Integra 1TO1 AI con tus sistemas externos vía una API REST.
- [Servidor MCP](https://docs.1to1ai.com/es/mcp.md): Conecta tu asistente de IA a la documentación de la API vía Model Context Protocol.
- [Mensajes](https://docs.1to1ai.com/es/messages.md): Las cuatro formas de enviar un mensaje y cuál aplica según la ventana de 24h.
- [Primeros pasos](https://docs.1to1ai.com/es/quickstart.md): Autentica tu primer request y envía un mensaje de WhatsApp en minutos.
- [Rate limits](https://docs.1to1ai.com/es/rate-limits.md): Límites de frecuencia de la API pública.
- [Plantillas](https://docs.1to1ai.com/es/templates.md): Qué es una plantilla de WhatsApp y cuándo necesitas una para enviar.

## OpenAPI Specs

- [openapi](https://docs.1to1ai.com/openapi.json)