> ## 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. # Enviar mensaje de texto libre > 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 un template primero para reabrirla. **Variantes según body:** - `body` sin `file_uuid` → texto libre puro (max 4096 chars). - `file_uuid` sin `body` → archivo solo (imagen/video/audio/documento). - `body` + `file_uuid` → archivo con caption (max 1024 chars). **Excepción audio:** WhatsApp no soporta captions en audio — si el `file_category` resuelto es `audio` y viene `body`, la API responde `INVALID_REQUEST` (400) con mensaje explícito. Envía el audio sin `body`, o manda texto libre en un request separado. **Flujo para enviar con adjunto:** 1. Sube el archivo con `POST /files/request-upload` → obtén `upload_url` y `file_uuid`. 2. Haz `PUT` del binario al `upload_url` directo a Supabase Storage (no pasa por este server). 3. Confirma con `POST /files/confirm` → el archivo queda `upload_status='confirmed'`. 4. Llama a este endpoint con ese `file_uuid`. El `file_category` del archivo determina el tipo de mensaje WhatsApp (image / video / audio / document). El `file_uuid` solo puede usarse una vez "lógicamente" — nada impide reusarlo en múltiples mensajes (el archivo en Storage es el mismo), pero cada envío genera un `message_uuid` y `wamid` distintos. **Guards aplicados:** - Ventana 24h (siempre, texto y media). - Wallet de visión (solo si `file_uuid`) — si el business no tiene tokens de visión, el AI no podría procesar respuestas que referencien el multimedia y la API rechaza upfront con `VISION_WALLET_BLOCKED` (402). ## OpenAPI ````yaml /openapi.json post /{slug}/conversation/messages/text 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/messages/text: post: tags: - Messages summary: Enviar mensaje de texto libre description: >- 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 un template primero para reabrirla. **Variantes según body:** - `body` sin `file_uuid` → texto libre puro (max 4096 chars). - `file_uuid` sin `body` → archivo solo (imagen/video/audio/documento). - `body` + `file_uuid` → archivo con caption (max 1024 chars). **Excepción audio:** WhatsApp no soporta captions en audio — si el `file_category` resuelto es `audio` y viene `body`, la API responde `INVALID_REQUEST` (400) con mensaje explícito. Envía el audio sin `body`, o manda texto libre en un request separado. **Flujo para enviar con adjunto:** 1. Sube el archivo con `POST /files/request-upload` → obtén `upload_url` y `file_uuid`. 2. Haz `PUT` del binario al `upload_url` directo a Supabase Storage (no pasa por este server). 3. Confirma con `POST /files/confirm` → el archivo queda `upload_status='confirmed'`. 4. Llama a este endpoint con ese `file_uuid`. El `file_category` del archivo determina el tipo de mensaje WhatsApp (image / video / audio / document). El `file_uuid` solo puede usarse una vez "lógicamente" — nada impide reusarlo en múltiples mensajes (el archivo en Storage es el mismo), pero cada envío genera un `message_uuid` y `wamid` distintos. **Guards aplicados:** - Ventana 24h (siempre, texto y media). - Wallet de visión (solo si `file_uuid`) — si el business no tiene tokens de visión, el AI no podría procesar respuestas que referencien el multimedia y la API rechaza upfront con `VISION_WALLET_BLOCKED` (402). parameters: - $ref: '#/components/parameters/SlugPathParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendTextBody' responses: '201': description: Mensaje creado y enviado a Meta. `wamid` es el id asignado. 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/SendTextResponse' '400': description: >- Body inválido (INVALID_REQUEST). Se devuelve para schema malformado, tipo de archivo no admitido (`INVALID_FILE_TYPE`) o combinación no soportada — en particular, `audio` con `body` (captions en audio no están soportados por WhatsApp). 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 de visión bloqueada (VISION_WALLET_BLOCKED). El business no tiene tokens de visión — no se puede adjuntar multimedia porque el AI no podría procesar respuestas del cliente que referencien el archivo. Solo aplica al path con `file_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' '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: >- La conversación, el contacto, o el archivo referenciados no existen o no pertenecen al business del token (CONVERSATION_NOT_FOUND, CONTACT_NOT_FOUND, FILE_NOT_FOUND, FILE_NOT_UPLOADED). 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 contacto no tiene número de teléfono y el envío a su identificador business-scoped (BSUID) no está habilitado para esta cuenta (`BSUID_SEND_DISABLED`). No es reintentable con el mismo contacto hasta que se habilite. 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: >- Estado que no admite envío: `WINDOW_CLOSED` cuando la ventana de 24h ya cerró (enviar template primero para reabrirla). Las conversaciones del módulo tester (ficticias) aceptan texto plano (replica el flujo real sin tocar Meta, persiste con `is_tester=true` y broadcast al canal tester); `TESTER_CONVERSATION_NOT_WRITABLE` aparece SOLO cuando se adjunta `file_uuid` — media en tester todavía no está soportado. 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: >- Error del servidor. Códigos posibles: `CHANNEL_NOT_CONFIGURED` (canal sin `phone_number_id`/`access_token` activos), `PREPARE_FAILED` (error inesperado al persistir el mensaje pending en DB), `FETCH_FAILED` (error de DB al cargar datos de envío — retry-able), `UNKNOWN_ERROR` (código no catalogado). 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' '502': description: >- Error del upstream de Meta (SEND_FAILED). El mensaje quedó persistido en DB con status `failed`; el caller puede reintentar con un nuevo POST (no reutiliza el mismo recurso). 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: SendTextBody: type: object properties: conversation: $ref: '#/components/schemas/ConversationRef' body: type: string minLength: 1 maxLength: 4096 example: Hola! Gracias por tu compra. description: >- Contenido del mensaje. Sin `file_uuid` es texto libre (max 4096 chars). Con `file_uuid` actúa como caption del adjunto (max 1024 chars). Opcional solo si `file_uuid` viene — al menos uno de los dos es obligatorio. file_uuid: type: string format: uuid description: >- UUID de un archivo ya confirmado via `POST /files/confirm`. El archivo debe pertenecer al mismo business del token y estar en estado `confirmed`. El `file_category` determina el tipo de mensaje (image, video, audio, document). Los stickers (image/webp) no se soportan por esta ruta. reply_to_uuid: type: string format: uuid description: >- UUID de un mensaje previo para citar (reply). Opcional — se ignora si el mensaje referenciado no pertenece a la conversación o no existe. required: - conversation SendTextResponse: type: object properties: message_uuid: type: string format: uuid description: >- UUID interno del mensaje creado. Útil para correlacionar con webhooks o reintentos. wamid: type: string description: >- ID del mensaje asignado por Meta (wa-message-id). Se usa para trazar en la Graph API de Meta o para reacciones. required: - message_uuid - wamid 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_... ````