> ## Documentation Index > Fetch the complete documentation index at: https://docs.visitoai.com/llms.txt > Use this file to discover all available pages before exploring further. # API de operaciones diarias > Buscar conversaciones, gestionar seguimientos y revisiones, iniciar conversaciones de WhatsApp y consultar reservas y mensajes a huéspedes. Las rutas son relativas a `/m2m/v1`. Usa `Authorization: Bearer `. La credencial fija el negocio; no se admite cambiarlo mediante parámetros. Las claves y autorizaciones OAuth existentes no reciben permisos nuevos automáticamente: un administrador debe concederlos. Las mismas operaciones están disponibles como herramientas MCP cuando el servicio MCP está habilitado. ## Endpoints y herramientas MCP | Endpoint | Permiso requerido | Herramienta MCP | | - | - | - | | `GET /conversations/start/whatsapp-template-status` | `conversations:read` | `get_conversation_start_status` | | `POST /conversations/start` | `conversations:start` | `start_conversation` | | `POST /conversations/{conversationId}/read` | `conversations:triage:write` | `mark_conversation_read` | | `POST /conversations/{conversationId}/needs-reply/resolve` | `conversations:triage:write` | `resolve_conversation_needs_reply` | | `POST /conversations/{conversationId}/review` | `conversations:reviews:write` | `create_conversation_review` | | `PUT /conversations/{conversationId}/review/assignment` | `conversations:reviews:write` | `assign_conversation_review` | | `POST /conversations/{conversationId}/review/resolve` | `conversations:reviews:write` | `resolve_conversation_review` | | `GET /crm/follow-ups` | `crm:followups:read` | `list_follow_ups` | | `POST /crm/follow-ups` | `crm:followups:write` | `create_follow_up` | | `PATCH /crm/follow-ups/{followUpId}` | `crm:followups:write` | `update_follow_up` | | `POST /crm/follow-ups/{followUpId}/dismiss` | `crm:followups:write` | `dismiss_follow_up` | | `POST /crm/follow-ups/{followUpId}/cancel` | `crm:followups:write` | `cancel_follow_up` | | `POST /crm/follow-ups/{followUpId}/send` | `crm:followups:send` | `send_follow_up` | | `GET /crm/follow-up-settings` | `crm:automation:read` | `get_follow_up_settings` | | `PATCH /crm/follow-up-settings` | `crm:automation:write` | `update_follow_up_settings` | | `GET /reservations` | `reservations:read` | `list_reservations` | | `GET /conversations/{conversationId}/reservations` | `reservations:read` | `list_conversation_reservations` | | `GET /reservations/readiness` | `reservations:read` | `get_reservation_readiness` | | `GET /reservations/sync/receipts` | `reservations:read` | `list_reservation_sync_receipts` | | `GET /reservations/lifecycle/attempts` | `reservations:read` | `list_reservation_message_attempts` | | `GET /reservations/lifecycle/events` | `reservations:read` | `get_reservation_message_settings` | | `PUT /reservations/lifecycle/integrations/{integrationId}/events/{eventType}` | `reservations:messaging:write` | `set_reservation_message_event` | | `PUT /reservations/lifecycle/integrations/{integrationId}/sender` | `reservations:messaging:write` | `set_reservation_message_sender` | ## Buscar una conversación `GET /conversations?contactQuery=Maria&channel=whatsapp&owner=OPERATOR_ID&limit=50` `contactQuery` usa la búsqueda de contactos del panel (2–200 caracteres). `channel`: `all`, `whatsapp`, `instagram`, `messenger` o `webchat`. `owner`: `all` o el ID de 24 caracteres de un operador activo del negocio; las credenciales de máquina no admiten `mine`. Consulta operadores con `/conversations/assignable-operators` y el permiso `conversations:assignment:read`. Pasa `nextCursor` como `cursor` mientras `hasMore` sea verdadero, conservando todos los filtros. La lista es dinámica: mensajes nuevos pueden mover conversaciones entre páginas. Elimina duplicados por `conversationId` al combinar páginas. Los filtros también afectan los contadores. Un cursor o filtro inválido devuelve 400; un operador externo o inactivo, 404. ## Gestionar seguimientos Busca oportunidades de venta para obtener `leadId` y `conversationId`. La lista admite estado, modo, lead, conversación y `dueAfter`; devuelve 50 por defecto, máximo 200. Continúa con `nextCursor` mientras `hasMore` sea verdadero. ```json theme={null} {"leadId":"LEAD_ID","conversationId":"CONVERSATION_ID","reason":"El huésped solicitó seguimiento","messageDraft":"Hola, ¿te gustaría continuar?","dueAt":"2026-10-01T15:00:00Z"} ``` Crear devuelve 201 y no es idempotente: si la respuesta es incierta, consulta la lista antes de repetir. PATCH cambia `messageDraft` o `dueAt`; `dueAt:null` elimina la fecha. Descartar/cancelar acepta `feedbackReason` opcional. Enviar acepta `messageText` opcional y reutiliza la identidad durable del envío. Una ejecución activa o completada puede devolver 409. No crees otro seguimiento para reintentar un envío. El envío devuelve 202 con `followUp` y `reply`. Consulta `reply.requestEventId` mediante `/message-requests/{requestEventId}/status`, con `messages:read`. `crmStatusUpdateFailed:true` significa que el envío fue aceptado pero falló la actualización del CRM: verifica el recibo antes de reintentar. Aceptado no significa entregado. Los envíos manuales heredan la pausa de respuestas configurada para el negocio. ## Configurar automatización Consulta `/crm/follow-up-settings` antes de modificarlo. PATCH admite `followUpMode` (`off`, `draft`, `auto`), `followUpLevel` (`light`, `balanced`, `proactive`), `followUpInstructions` (máximo 2.000 caracteres) y `quietHours` (`start`/`end`, valores `HH:mm` distintos en la zona horaria del negocio). Solo cambian los campos enviados; se requiere al menos uno. ```json theme={null} {"followUpMode":"draft","quietHours":{"start":"21:00","end":"09:00"}} ``` Activar `auto` puede producir envíos futuros, incluidos seguimientos existentes elegibles. Cambia la automatización solo por instrucción explícita. Crear o editar un seguimiento no modifica esta configuración. Se mantienen las reglas existentes de elegibilidad y horario del CRM. ## Completar trabajo de la bandeja Marcar como leído, resolver respuesta pendiente, resolver revisión y resolver derivación son operaciones diferentes. Crear una revisión admite `reasonCode` (`other` por defecto), `note` y `assignedOperatorId` opcionales. Motivos: `ai_response_issue`, `knowledge_gap`, `policy_compliance`, `guest_experience`, `booking_payment`, `other`. Las notas admiten 2.000 caracteres. Una revisión o derivación ya abierta devuelve 409. Para asignar se requiere `operatorId`; usa `null` para quitar la asignación. Resolver admite `resolutionNote` opcional. Se conservan las actualizaciones en tiempo real del panel y se registra la credencial como actor. Resolver respuesta pendiente no cierra una derivación ni una revisión. ## Iniciar una conversación de WhatsApp Consulta `/conversations/start/whatsapp-template-status?channelId=CHANNEL_ID`. Lee el estado guardado sin crear ni actualizar plantillas en el proveedor. `not_prepared` indica que falta prepararla desde el panel. Iniciar requiere una plantilla preparada y aprobada, un canal disponible, consentimiento del destinatario y ausencia de opt-out. Envía `POST /conversations/start` con una cabecera `Idempotency-Key` estable: ```json theme={null} {"channel":"whatsapp","targetChannelId":"CHANNEL_ID","phoneNumber":"+15551234567","locale":"es_MX","messageText":"Damos seguimiento a tu solicitud.","consentConfirmed":true} ``` Solo se admiten `en_US` y `es_MX`. `contactName` es opcional; `messageText` admite 1.024 caracteres. Repite una clave únicamente con los mismos datos. Las claves se delimitan por negocio y conversación destino; datos incompatibles devuelven 409. Los intentos antiguos del panel sin huella de solicitud conservan su comportamiento de reintento. La respuesta incluye `conversationId`, `replyId` y `requestEventId`. El 202 significa en cola, no entregado. Verifica un intento fallido antes de iniciar otro envío. ## Reservas y mensajes a huéspedes `GET /reservations` consulta registros sincronizados, no disponibilidad en tiempo real. Filtra por `integrationId`, `reservationId` o estado; ordena por `booked_at` o `check_in_date`, ascendente o descendente. Las páginas admiten 20 registros. Continúa con `nextCursor` mientras `hasNext` sea verdadero, manteniendo filtros y orden. Recibos e intentos usan la misma paginación de 20 registros. La consulta por conversación devuelve hasta cinco reservas con la asociación existente por teléfono del huésped. Las lecturas de disponibilidad de configuración y eventos muestran integraciones, remitentes y ajustes. Las escrituras admiten una integración Cloudbeds por solicitud. Configura un evento con `{"enabled":false}` o el remitente con `{"channelId":"CHANNEL_ID"}`. Eventos: `booking_confirmed`, `pre_checkin`, `post_checkout_review`. El remitente debe ser un canal WhatsApp disponible del mismo negocio. Integraciones externas o no compatibles devuelven 404; remitentes inválidos o no disponibles, 400/404. Se respetan las restricciones globales existentes. Activar un evento cambia mensajes futuros; no envía inmediatamente ni garantiza entrega. Los resultados `would_send`, `deferred`, `skipped`, `invalid`, `duplicate` y `error` son diagnósticos, no recibos de entrega. Los contadores existentes denominados sent tampoco prueban entrega del proveedor. No se exponen creación/cancelación de reservas, disponibilidad en vivo, campañas masivas ni cambios de eventos para todo el negocio. ## Errores y reintentos Credenciales inválidas o ausentes: 401; permiso faltante: 403; entrada inválida: 400; recurso inexistente o externo: 404; conflicto de estado/idempotencia: 409. Los servicios dependientes pueden devolver 5xx. Puedes reintentar lecturas. Para envíos, verifica recibos aceptados antes de repetir. Los PUT de configuración establecen valores explícitos; repetirlos no alterna el estado.